set_stream(+StreamId, +Stream)

+StreamId

Atom.

+Stream

Integer (stream number) or Atom (reserved or user-defined symbolic stream name).

Description

If StreamId is a new user-defined stream name, then that new name is associated with the physical stream denoted by the Stream. Stream can be in the form of a physical stream number, a name of a physical stream (stdin, stdout, stderr, null), or any existing symbolic stream name.

If StreamId 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. Any previously existing association of the name StreamId is forgotten.

Note that a user-defined symbolic stream is not automatically updated when the associated physical stream is closed. A system-defined symbolic stream will be redirected to its default when the associated physical stream is closed.

The physical stream associated with a symbolic stream name can be queried using get_stream/2.

Fail Conditions

Resatisfiable

Exceptions

(4) instantiation fault

Either StreamId or Stream is uninstantiated.

(5) type error

Either StreamId is not an atom or Stream is not a stream number or symbolic stream name.

(193) illegal stream specification

Stream is an illegal stream specification.

(194) too many symbolic names of a stream

A physical stream has more than 255 logical stream names assigned to it.

Examples

        % suppress standard output temporarily:
	[eclipse]: set_stream(output, null).
	Yes (0.00s cpu)
	[eclipse]: writeln(hello).
	Yes (0.00s cpu)

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

        % alias the names s and output:
        [eclipse]: open(file1,update,s), set_stream(output,s),
		   writeln(output,hi), flush(output).
	yes.
	[eclipse]: 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