[ Stream I/O | Reference Manual | Alphabetic Index ]

# get_stream_info(+Stream, ?Attr, -Value)

Succeeds if the attribute Attr of the open stream Stream has the value Value.

Stream
  Stream handle or alias (atom)
Attr
  Atom or variable.
Value
  Variable, atom, string, integer or handle.

## Description

Used to retrieve information associated to an open stream. The available attributes and their meanings are:

        Attr            Value         Description

        aliases         integer       current number of symbolic names

        compress        on, off       a hint for output operations (e.g.
                                      write_exdr/2) to use a more compact
                                      output format (output streams only).
                                      Default: on (file,pipe,socket) or off.

        connection      atom          identification of the connected
                                      socket - file name for unix sockets,
                                      host name for internet ones

        delete_file     off,          delete an opened file automatically when:
                        when_lost,    - its stream handle becomes inaccessible
                        when_closed   - the stream is closed in any way

        device          file, null,   the device behind the stream
                        pipe, queue,
                        socket, tty,
                        string

        encoding        octet,        character encoding used by this stream
                        iso_latin_1,
                        ...

        end_of_line     lf, crlf      which end-of-line sequence to write
                                      (output streams only)

        end_of_stream   at,not,past   indicates whether the stream is currently
                                      positioned at (or past) the end-of-file

        eof_action      eof_code,     how to react to end-of-file
                        error,        (input streams only)
                        reset

        event           atom or       event on writing to empty stream
                        event handle  (see open/4)

        fd              integer       the associated OS file descriptor

        flush           flush,        explicit or implicit flushing
                        end_of_line   (output streams only)

        handle          stream handle a garbage-collectable handle to the stream
                                      (see also get_stream/2)

        input           true, false   this is an input stream (ISO)

        last_written    integer       character code of last written character
                                      (output streams only)

        line            integer       current line number
                                      (input streams only)

        mode            read, write,  the stream's direction
                        update

        name            atom or       associated filename, or contents
                        string        (in case of a string or queue), or
                                      pseudo file name (user, error, null)

        macro_expansion on, off       expand term macros (input streams only)

        offset          integer       current position in the
                                      stream, as given by at/2

        output          true, false   this is an input stream (ISO)

        output_options  list          default output options for all term
                                      output on this stream. The list
                                      format is as in write_term/2,3.

        physical_stream integer       associated stream number
                                      (DEPRECATED: if this number is retrieved,
                                      the system will no longer be able to close
                                      the stream automatically when unused)

        port            integer       port number associated with an
                                      internet socket

        prompt          string        prompt string (input streams only)

        prompt_stream   handle        output stream for the prompt
                                      (input streams only)

        reposition      true, false   the stream can be repositioned (seek/2)

        sigio           on            SIGIO signals enabled (UNIX only)

        system_use      on, off       a system stream is currently
                                      redirected to this stream

        usable          on, off       if the stream can currently be used:
                                      flushing or reading the empty stream
                                      may not be properly handled if `off'.

        yield           on, off       yield on end-of-file (see open/4)

### Modes and Determinism

- get_stream_info(+, -, -) is multi
- get_stream_info(+, +, -) is semidet

### Fail Conditions

Fails if the requested attribute is not available for this stream

### Exceptions

(4) instantiation fault
  Stream is not instantiated.
(5) type error
  Stream is neither an atom nor a handle.
(5) type error
  Attr is instantiated, but not to an atom.
(5) type error
  Value is instantiated, but not to an atom, string, integer or handle.
(6) out of range
  Attr is an atom, but not a valid attribute name.
(193) illegal stream specification
  Stream does not denote an open stream.

## Examples

    Success:
        ?- get_stream_info(input,X,Y), writeln(X is Y), fail.
        name is user
        aliases is 2
        system_use is on
        line is 1
        offset is 0
        prompt is
        prompt_stream is $&(stream,1)
        fd is 0
        reprompt_only is off
        device is tty
        mode is read
        usable is on
        macro_expansion is on
        handle is $&(stream,0)
        No (0.00s cpu)

        ?- get_stream_info(toplevel_input, prompt, P).
        P = "\t"
        Yes (0.00s cpu)

    Fail:
        get_stream_info(output, prompt, P).
        get_stream_info(output, system_use, off).

    Error:
        get_stream_info(X, Y, Z).                      (Error 4)
        get_stream_info(file(f), Y, Z).                (Error 5)
        get_stream_info(output, 7, X).                 (Error 5)
        get_stream_info(output, offset, 8.5).          (Error 5)
        get_stream_info(output, length, Z).            (Error 6)
        get_stream_info(nostream, Y, Z).               (Error 193)

## See Also

set_stream_property / 3, open / 3, open / 4, current_stream / 1, get_stream_info / 3, get_stream / 2, at / 2, write_term / 2, write_term / 3