set_stream(+Alias, +Stream)

Alias

Atom.

Stream

Stream handle or alias (atom)

Description

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