|Did you know ...||Search Documentation:|
|ISO Input and Output Streams|
The predicates described in this section provide ISO compliant I/O, where streams are explicitly created using the predicate open/3. 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.
This schema is not vulnerable to filename and stream ambiguities as well as changes to the working directory. On the other hand, using the notion of current-I/O simplifies reusability of code without the need to pass arguments around. E.g., see with_output_to/2.
SWI-Prolog streams are, compatible with the ISO standard, either input or output streams. To accommodate portability to other systems, a pair of streams can be packed into a stream-pair. See stream_pair/3 for details.
SWI-Prolog stream handles are unique symbols that have no syntactical
representation. They are written as
which is not valid input for read/1.
They are realised using a blob of type
stream (see blob/2
and section 11.4.7).
appendopens the file for writing, positioning the file pointer at the end. Mode
updateopens the file for writing, positioning the file pointer at the beginning of the file without truncating the file. 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.80New code should use the
alias(Alias)option for compatibility with the ISO standard.
SWI-Prolog also allows SrcDest to be a term
In this form, Command is started as a child process and if
write, output written to Stream
is sent to the standard input of Command. Viso versa, if Mode
read, data written by Command to the standard
output may be read from Stream. On Unix systems, Command
is handed to popen() which hands it to the Unix shell. On Windows, Command
is executed directly. See also process_create/3
The following Options are recognised by open/4:
?- open(data, read, Fd, [alias(input)]). ..., read(input, Term), ...
write. See also stream_property/2 and especially section 126.96.36.199 for a discussion of this feature.
full(default) defines full buffering,
linebuffering by line, and
falseimplies 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.
true(default), the stream is closed on an abort (see abort/0). If
false, the stream is not closed. If it is an output stream, however, it will be flushed. Useful for logfiles and if the stream is associated to a process (using the
updatemode. Currently, List is a list of atoms that describe the permissions of the created file.81Added after feedback from Joachim Shimpf and Per Mildner. Defined values are below. Not recognised values are silently ignored, allowing for adding platform specific extensions to this set.
Note that if List is empty, the created file has no
associated access permissions. The create options map to the POSIX mode
option of open(), where
read map to 0444,
to 0222 and
execute to 0111. On POSIX systems, the final
permission is defined as (mode &
textis derived from the Prolog flag encoding. For
binarystreams the default encoding is
octet. For details on encoding issues, see section 2.19.1.
eof_codemakes get0/1 and friends return -1, and read/1 and friends return the atom
end_of_file. Repetitive reading keeps yielding the same result. Action
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.
none, which does not lock the file. The value
sharedmeans other processes may read the file, but not write it. The value
exclusivemeans no other process may read or write the file.
Locks are acquired through the POSIX function fcntl() using the
F_SETLKW, which makes a blocked call wait for the lock to
be released. Please note that fcntl() locks are advisory and
therefore only other applications using the same advisory locks honour
your lock. As there are many issues around locking in Unix, especially
related to NFS (network file system), please study the fcntl() manual
page before trusting your locks!
lock option is a SWI-Prolog extension.
text(default), Prolog will write a text file in an operating system compatible way. Using type
binarythe bytes will be read or written without any translation. See also the option
true), the open call returns immediately with an exception if the file is locked. The exception has the format
permission_error(lock, source_sink, SrcDest).
reposition is not supported in SWI-Prolog.
All streams connected to a file may be repositioned.
/dev/null) or exploit the counting properties. The initial encoding of Stream is
utf8, enabling arbitrary Unicode output. The encoding can be changed to determine byte counts of the output in a particular encoding or validate if output is possible in a particular encoding. For example, the code below determines the number of characters emitted when writing Term.
write_length(Term, Len) :- open_null_stream(Out), write(Out, Term), character_count(Out, Len0), close(Out), Len = Len0.
If the closed stream is the current input, output or error stream, the stream alias is bound to the initial standard I/O streams of the process. Calling close/1 on the initial standard I/O streams of the process is a no-op for an input stream and flushes an output stream without closing it.82This behaviour was defined with purely interactive usage of Prolog in mind. Applications should not count on this behaviour. Future versions may allow for closing the initial standard I/O streams.
close(Stream, [force(true)])as the only option. Called this way, any resource errors (such as write errors while flushing the output buffer) are ignored.
false. See also open/4.
true, a BOM (Byte Order Mark) was detected while opening the file for reading, or a BOM was written while opening the stream. See section 188.8.131.52 for details.
F_SETFDusing the flag
FD_CLOEXECon Unix and (negated)
past. See also at_end_of_stream/[0,1].
error. See open/4 for details.
appendand the SWI-Prolog extension
dos, text streams will emit
\rfrom input streams. Default depends on the operating system.
error(throw an I/O error exception),
\...\escape code) or
&#...;XML character entity). The initial mode is
prologfor the user streams and
errorfor all other streams. See also section 2.19.1 and set_stream/2.
trueif the stream is associated with a terminal. See also set_stream/2.
ignore. The latter is intended to deal with service processes for which the standard output handles are not connected to valid streams. In these cases write errors may be ignored on
if the stream refers to some other object. Mode is one of
Stream-pairs can be used by all I/O operations on streams, where the operation selects the appropriate member of the pair. The predicate close/1 closes the still open streams of the pair.83As of version 7.1.19, it is allowed to close one of the members of the stream directly and close the pair later. The output stream is closed before the input stream. If closing the output stream results in an error, the input stream is still closed. Success is only returned if both streams were closed successfully.
position(Pos)property. See also seek/4.
position(Pos)property. Field is one of
byte_count. See also line_count/2, line_position/2, character_count/2 and byte_count/2.84Introduced in version 5.6.4 after extending the position term with a byte count. Compatible with SICStus Prolog.
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.
Positions are counted in `units'. A unit is 1 byte, except for text files using 2-byte Unicode encoding (2 bytes) or wchar encoding (sizeof(wchar_t)). The latter guarantees comfortable interaction with wide-character text objects. Otherwise, the use of seek/4 on non-binary files (see open/4) is of limited use, especially when using multi-byte text encodings (e.g. UTF-8) or multi-byte newline files (e.g. DOS/Windows). On text files, SWI-Prolog offers reliable backup to an old position using stream_property/2 and set_stream_position/2. Skipping N character codes is achieved calling get_code/2 N times or using copy_stream_data/3, directing the output to a null stream (see open_null_stream/1). 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 repositioned, a
is raised. If applying the offset would result in a file position less
than zero, a
domain_error is raised. Behaviour when seeking
to positions beyond the size of the underlying object depend on the
object and possibly the operating system. The predicate seek/4
is compatible with Quintus Prolog, though the error conditions and
signalling is ISO compliant. See also stream_property/2
eof_actiononly applies to the read stream,
representation_errorsonly applies to the write stream and trying to set
line_positionon a pair results in a
permission_errorexception. See also stream_property/2 and open/4.
set_stream(S, current_input)is the same as set_input/1, and by setting the alias of a stream to
user_input, etc., all user terminal input is read from this stream. See also interactor/0.
close_on_execproperty. See stream_property/2.
bomcauses the stream to check whether the current character is a Unicode BOM marker. If a BOM marker is found, the encoding is set accordingly and the call succeeds. Otherwise the call fails.
detect. It will be set to
\rcharacter was removed.
timeout_error(read, Stream), _)
binary. See also open/4 and the
encodingproperty of streams. Switching to
binarysets the encoding to
octet. Switching to
textsets the encoding to the default text encoding.
set_stream(S, record_position(true))resets the position the start of line 1.
current_inputof the calling thread. Out becomes
current_output. If Error equals Out an unbuffered stream is associated to the same destination and linked to
user_error. Otherwise Error is used for
user_error. Output buffering for Out is set to
lineand buffering on Error is disabled. See also prolog/0 and set_stream/2. The clib package provides the library
library(prolog_server), creating a TCP/IP server for creating an interactive session to Prolog.