
set_stream(+Alias, +Stream)

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

Arguments
   Alias               Atom.
   Stream              Stream handle or alias (atom)

Type
   Stream I/O

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 --- Either Alias or Stream is uninstantiated.
     5 --- Either Alias is not an atom or Stream is not a stream handle or symbolic stream name.
   193 --- Stream is an illegal stream specification.
   196 --- 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
