Explicit Input and Output Streams

The predicates below are part of the Quintus compatible stream-based I/O package. In this package streams are explicitly created using the predicate open3. The resulting stream identifier is then passed as a parameter to the reading and writing predicates to specify the source or destination of the data.

open4+SrcDest, +Mode, -Stream, +Options ISO compliant predicate to open a stream. SrcDes is either an atom, specifying a Unix file, or a term `pipe(Command)', just like see1 and tell1. Mode is one of read, write, append or update. Mode append opens the file for writing, positioning the file-pointer at the end. Mode update opens the file for writing, positioning the file-pointer at the beginning of the file without truncating the file. See also stream_position3. Stream is either a variable, in which case it is bound to an integer identifying the stream, or an atom, in which case this atom will be the stream identifier. The Options list can contain the following options:

typeType Using type text (default), Prolog will write a text-file in an operating-system compatible way. Using type binary the bytes will be read or written without any translation. Note there is no difference between the two on Unix systems.

aliasAtom Gives the stream a name. Below is an example. Be careful with this option as stream-names are global. See also set_stream2.

eof_actionAction Defines what happens if the end of the input stream is reached. Action eof_code makes get01 and friends return -1 and read1 and friends return the atom end_of_file. Repetitive reading keeps yielding the same result. Action error is like eof_code, but repetitive reading will raise an error. With action reset, Prolog will examine the file again and return more data if the file has grown.

bufferBuffering Defines output buffering. The atom fullf (default) defines full buffering, line buffering by line, and false implies the stream is fully unbuffered. Smaller buffering is useful if another process or the user is waiting for the output as it is being produced. See also flush_output[0,1]. This option is not an ISO option.

close_on_abortBool If true (default), the stream is closed on an abort (see abort0). If false, the stream is not closed. If it is an output stream, it will be flushed however. Useful for logfiles and if the stream is associated to a process (using the pipe1 construct).

The option reposition is not supported in SWI-Prolog. All streams connected to a file may be repositioned.

open3+SrcDest, +Mode, ?Stream Equivalent to open4 with an empty option-list.

open_null_stream1?Stream Open a stream that produces no output. All counting functions are enabled on such a stream. An attempt to read from a null-stream will immediately signal end-of-file. Similar to Unix /dev/null. Stream can be an atom, giving the null-stream an alias name.

close1+Stream Close the specified stream. If Stream is not open an error message is displayed. If the closed stream is the current input or output stream the terminal is made the current input or output.

close2+Stream, +Options Provides closeStream, [force(true)] as the only option. Called this way, any resource error (such as write-errors while flushing the output buffer) are ignored.

stream_property2?Stream, ?StreamProperty ISO compatible predicate for querying status of open I/O streams. StreamProperty is one of:

file_nameAtom If Stream is associated to a file, unify Atom to the name of this file. modeIOMode Unify IOMode to the mode given to open4 for opening the stream. Values are: read, write, append and the SWI-Prolog extension update. input True if Stream has mode read. output True if Stream has mode write, append or update. aliasAtom If Atom is bound, test of the stream has the specified alias. Otherwise unify Atom with the first alias of the stream.Backtracking does not give other aliases. positionTerm Unify Term with the current stream-position. A stream-position is a term of format $stream_positionCharIndex, LineNo, LinePos. See also term_position3. end_of_streamE If Stream is an input stream, unify E with one of the atoms not, at or past. See also at_end_of_stream[0,1]. eof_actionA Unify A with one of eof_code, reset or error. See open4 for details. repositionBool Unify Bool with true if the position of the stream can be set (see seek4). It is assumed the position can be set if the stream has a seek-function and is not based on a POSIX file-descriptor that is not associated to a regular file. typeT Unify Bool with text or binary. file_noInteger If the stream is associated with a POSIX file-descriptor, unify Integer with the descriptor number. SWI-Prolog extension used primarily for integration with foreign code. See also Sfileno() from SWI-Stream.h.

current_stream3?Object, ?Mode, ?Stream The predicate current_stream3 is used to access the status of a stream as well as to generate all open streams. Object is the name of the file opened if the stream refers to an open file, an integer file-descriptor if the stream encapsulates an operating-system stream or the atom [] if the stream refers to some other object. Mode is one of read or write. set_stream_position2+Stream, +Pos Set the current position of Stream to Pos. Pos is a term as returned by stream_property2 using the positionPos property. See also seek4. seek4+Stream, +Offset, +Method, -NewLocation Reposition the current point of the given Stream. Method is one of bof, current or eof, indicating positioning relative to the start, current point or end of the underlying object. NewLocation is unified with the new offset, relative to the start of the stream.

If the seek modifies the current location, the line number and character position in the line are set to 0.

If the stream cannot be repostioned, a reposition error is raised. The predicate seek4 is compatible to Quintus Prolog, though the error conditions and signalling is ISO compliant. See also stream_position3. set_stream2+Stream, +Attribute Modify an attribute of an existing stream. Attribute is in the current implemention only aliasAliasName to set the alias of an already created stream. If AliasName is the name of one of the standard streams is used, this stream is rebound. Thus, set_stream(S, current_input) is the same as set_input1 and by setting the alias of a stream to user_input, etc. all user terminal input is read from this stream. See also interactor0.