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

# set_stream(+Alias, +Stream)

The symbolic stream name Alias is associated with the stream Stream.

Alias
  Atom.
Stream
  Stream handle or alias (atom)

## Description

This predicate is used to create new symbolic names (aliases) for streams, or to redirect existing symbolic stream names to other streams.

If Alias is a new user-defined stream name, then that new name is associated with the stream denoted by the Stream. Stream can be given in the form of a stream handle or an already existing alias name.

If Alias is an already existing stream name (including one of the symbolic system stream names like input, output, error, warning_output, log_output), then that stream is redirected to Stream. Note that the setting of the 'input' and 'output' aliases determines the streams used by the I/O predicates that have no stream argument.

Any previous association of the name Alias is forgotten. Other alias names for the same physical stream are not affected by redirection.

When a user-defined symbolic stream is closed, the associated physical stream is closed and the association forgotten. Note that it is not enough to close the stream only via a handle, because the association of symbolic an physical stream remains (even though the physical stream is closed) until the stream alias is closed as well. A system-defined stream alias however will be automatically redirected back to its default when the associated physical stream is closed.

An anonymous stream handle associated with a symbolic stream name can be obtained using get_stream/2 or get_stream_info/3.

An alternative way of creating a stream alias is to specify it during stream creation, i.e. as the Stream-argument to open/3, socket/3, etc., or by using an alias(Alias) option in open/4.

The standard stream aliases stdin, stdout, stderr and null cannot be redirected.

### Modes and Determinism

- set_stream(+, +) is det

### Exceptions

(4) instantiation fault
  Either Alias or Stream is uninstantiated.
(5) type error
  Either Alias is not an atom or Stream is not a stream handle or symbolic stream name.
(193) illegal stream specification
  Stream is an illegal stream specification.
(196) trying to modify a system stream
  Stream is fixed system stream.

## Examples

            % suppress standard output temporarily:
            ?- set_stream(output, null).
            Yes (0.00s cpu)
            ?- writeln(hello).
            Yes (0.00s cpu)

            % set standard output back to default:
            ?- set_stream(output, stdout).
            Yes (0.00s cpu)
            ?- writeln(hello).
            hello
            Yes (0.00s cpu)

            % alias the names s and output:
            ?- open(file1,update,s), set_stream(output,s),
               writeln(output,hi), flush(output).
            yes.
            ?- seek(s,0), read(s,X).
            X = hi
            yes.

    Error:
            set_stream(a, S).        (Error 4).
            set_stream(1.0, S).      (Error 5).
            set_stream(a, nonex).    (Error 193).

## See Also

open / 4, get_stream / 2