8.1 Input / Output

There are two sets of file manipulation predicates in SICStus Prolog. One set is inherited from DEC-10 Prolog. These predicates always refer to a file by specification. The other set of predicates is modeled after Quintus Prolog and refer to files as streams. Streams correspond to the file pointers used at the operating system level.

This second set of file manipulation predicates, the one involving streams, is supported by the ISO Prolog standard. Note that the notion of file is used here in a generalized sense; it may refer to a named file, the user's terminal, or some other device. The ISO Prolog standard refers to this generalized notion of file using the term source/sink. A stream can be opened and connected to a file specification or file descriptor for input or output by calling the predicates open/[3,4]. These predicates will return a reference to a stream, which may then be passed as an argument to various I/O predicates. Alternatively, a stream can be assigned an alias at the time of opening, and referred to by this alias afterwards. The predicate close/1 is used for closing a stream.

There are two types of streams, binary or text. Binary streams are seen as a sequence of bytes, i.e. integers in the range 0–255. Text streams, on the other hand, are considered a sequence of characters, represented by their character codes. SICStus Prolog handles wide characters, i.e. characters with codes larger than 255. The WCX (Wide Character eXtension) component of SICStus Prolog allows selecting various encoding schemes via environment variables or hook predicates; see Handling Wide Characters. The predicates current_stream/3 and stream_property/2 are used for retrieving information about a stream, and for finding the currently existing streams.

Prolog streams can be accessed from C functions as well. See SICStus Streams, for details.

The possible formats of a stream are:

A stream connected to some file. X is an integer.
A stream alias. Aliases can be associated with streams using the alias(Atom) option of open/4. There are also three predefined aliases:
An alias initially referring to the UNIX stdin stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stdin.
An alias initially referring to the UNIX stdout stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stdout.
An alias initially referring to the UNIX stderr stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stderr.

This stream is used by the Prolog top-level and debugger, and for system messages.

Certain I/O predicates manipulate streams implicitly, by maintaining the notion of a current input stream and a current output stream. The current input and output streams are set to the user_input and user_output initially and for every new break (see Nested). The predicate see/1 (tell/1) can be used for setting the current input (output) stream to newly opened streams for particular files. The predicate seen/0 (told/0) closes the current input (output) stream, and resets it to the standard input (output) stream. The predicate seeing/1 (telling/1) is used for retrieving the file name associated with the current input (output) streams.

The file specification user stands for the standard input or output stream, depending on context. Terminal output is only guaranteed to be displayed if the output stream is explicitly flushed.

A file specification FileSpec other than user must be an atom or a compound term. It is subject to syntactic rewriting. Depending on the operation, the resulting absolute filename is subject to further processing. Syntactic rewriting is performed wrt. a context directory Context, in the follows steps:

For example, asssuming the user's home directory is /users/clyde and given the clauses

     file_search_path(home, '$HOME').
     file_search_path(demo, home(prolog(demo))).
     file_search_path(prolog, prolog).

the file specification demo(mydemo) would be rewritten to '/users/clyde/prolog/demo/mydemo', since $HOME is interpreted as an environment variable (Under UNIX, this is the user's home directory).

Failure to open a file normally causes an exception to be raised. This behavior can be turned off and on by of the built-in predicates nofileerrors/0 and fileerrors/0 described below.