Streams

Input and output in ECLiPSe is done via communication channels called streams. They are usually associated with either a file, a terminal, a socket, a pipe, or in-memory queues and buffers. The streams may be opened for input only (read mode), output only (write mode), or for both input and output (update mode).

Predefined Streams

Every ECLiPSe session has 4 predefined system streams:

stdin

The standard input stream.

stdout

The standard output stream.

stderr

The standard error stream.

null

A dummy stream, output to it is discarded, on input it always gives end of file.

In a stand-alone ECLiPSe stdin, stdout and stderr are connected to the corresponding standard I/O descriptors of the process. In an embedded ECLiPSe, the meaning of stdin, stdout and stderr is determined by the ECLiPSe initialisation options.

Moreover, every ECLiPSe session defines the following symbolic stream names, which are used for certain categories of input/output:

input

Used by the input predicates that do not have an explicit stream argument, e.g. read/1. This is by default the same as stdin, but can be redirected.

output

Used by the output predicates that do not have an explicit stream argument, e.g. write/1. This is by default the same as stdout, but can be redirected.

error

Output for error messages and all messages about exceptional states. This is by default the same as stderr, but can be redirected.

warning_output

Used by the system to output warning messages. This is by default the same as stdout, but can be redirected.

log_output

Used by the system to output log messages, e.g. messages about garbage collection activity. This is by default the same as stdout, but can be redirected.

user

This identifier is provided for compatibility with Prolog systems and it is identical with stdin and stdout depending on the context where it is used.

Symbolic Stream	System Stream
input	0 (stdin)
output	1 (stdout)
warning_output	1 (stdout)
log_output	1 (stdout)
error	2 (stderr)
	3 (null)

Initial assignment of symbolic stream names

Stream Identifiers and Aliases

Every stream is identified by a small integer^10.1, but it can have several symbolic names (aliases), which are atoms. Most of the built-in predicates that require a stream to be specified have a stream argument at the first position, e.g. write(Stream, Term). This argument can be either the stream number or a symbolic stream name.

An alias name can be given to a stream either when it is created or explicitly by invoking set_stream/2:

set_stream(Alias, Stream)

To find the corresponding stream number, use get_stream/2:

get_stream(StreamOrAlias, StreamNr)

get_stream/2 can also be used to check whether two stream names are aliases of each other.

Opening New Streams

Streams provide a uniform interface to a variety of I/O devices and pseudo-devices. The following table gives an overview of how streams on the different devices are opened.

I/O device	How to open
tty	implicit (stdin,stdout,stderr) or open/3 of a device file
file	open(FileName, Mode, Stream)
string	open(string(String), Mode, Stream)
queue	open(queue(String), Mode, Stream)
pipe	exec/2, exec/3 and exec_group/3
socket	socket/3 and accept/3
null	implicit (null stream)

How to open streams onto the different I/O devices

Most streams are opened for input or output by means of the open/3 or open/4 predicate. The goals

open(SourceSink, Mode, Stream)
open(SourceSink, Mode, Stream, Options)

open a communication channel with SourceSink.

If SourceSink is an atom or a string, a file is being opened and SourceSink takes the form of a file name in the host machine environment. ECLiPSe uses an operating system independent path name syntax, where the components are separated by forward slashes. The following forms are possible:

• absolute path name, e.g. /usr/peter/prolog/file.pl
• relative to the current directory, e.g. prolog/file.pl
• relative to the own home directory, e.g. ~/prolog/file.pl
• start with an environment variable, e.g. $HOME/prolog/file.pl
• relative to a user's home directory, e.g. ~peter/prolog/file.pl (UNIX only)
• specifying a drive name, e.g. //C/prolog/file.pl (Windows only)

Note that path names usually have to be quoted (in single or double quotes) because they contain non-alphanumeric characters.

If SourceSink is of the form string(InitString) a pseudo-file in memory is opened, see section 10.3.1.

If SourceSink is of the form queue(InitString) a pseudo-pipe in memory is opened, see section 10.3.2.

Mode must be one of the atoms read, write, append or update, which means that the stream is to be opened for input, output, output at the end of the existing stream, or both input and output, respectively. Opening a file in write mode will create it if it does not exist, and erase the previous contents if it does exist. Opening a file in append mode will keep the current contents of the file and start writing at its end.

Stream is a symbolic stream identifier or an uninstantiated variable. If it is uninstantiated, the system will bind it to an identifier (the stream number):

[eclipse 1]: open(new_file, write, Stream).
Stream = 6
yes.

If the stream argument is an atomic name, this name becomes an alias for the (hidden) stream number:

[eclipse 1]: open(new_file, write, new_stream).
yes.

The stream identifier (symbolic or numeric) may then be used in predicates which have a named stream as one of their arguments. For example

open("foo", update, Stream), write(Stream, subject), close(Stream).

will write the atom subject to the file `foo' and close the stream subsequently.

It is recommended style not to use symbolic stream names in code that is meant to be reused. This is because the stream names are global, there is the possibility of name clashes, and the code will not be reentrant. It is cleaner to open streams with a variable for the stream identifier and pass the identifier as an argument wherever it is needed.

Socket streams are not opened with open/3, but with the special primitives socket/3 and accept/3. More details are in chapter 21.

A further group of primitives which open streams implicitly is exec/2, exec/3 and and exec_group/3. They open pipes which connect directly to the I/O channels of the executed process. See chapter 20 for details.

Closing Streams

The predicate

close(Stream)

is used to close an open stream. If a stream has several alias names, closing any of them will close the actual stream. All the other aliases should be closed as well (or redirected to streams that are still open), because otherwise they will continue to refer to the number of the already closed stream.

When an attempt is made to close a redirected system stream (e.g. output), the stream is closed, but the system stream is reset to its default setting.

Redirecting Streams

The set_stream/2 primitive can be used to redirect an already existing symbolic stream to a new actual stream. This is particularly useful to redirect e.g. the default output stream

set_stream(output, MyStream)

so that all standard output is redirected to some other destination (e.g. an opened file instead of the terminal). Note that the stream modes (read/write) must be compatible. The redirection is terminated by calling

close(output)

which will reestablish the original meaning of the output stream.

Finding Streams

The predicate

current_stream(?Stream)

can be used to backtrack over all the currently opened stream indentifiers (but not their aliases).

Stream Properties

A stream's properties can be accessed using get_stream_info/3

get_stream_info(+Stream, +Property, -Value)

e.g. its mode, line number, file name etc. Some stream properties can be modified using set_stream_property/3

set_stream_property(+Stream, +Property, +Value)

e.g. the end-of-line sequence used, the flushing behaviour, the event-raising behaviour, the prompt etc.