True when SrcDest can be opened in Mode and Stream
is an I/O stream to/from the object. SrcDest is normally the
name of a file, represented as an atom or string. 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. 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.99New
code should use the alias(Alias)
option for compatibility
with the ISO standard.
SWI-Prolog also allows SrcDest to be a term pipe(Command)
.
In this form, Command is started as a child process and if
Mode is write
, output written to Stream
is sent to the standard input of Command. Vice versa, if Mode
is
read
, data written by Command to the standard
output can 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 and therefore shell syntax such as redirecting
(using e.g., >
file) does not work. Use of
the
pipe(Command)
feature is deprecated. The predicate
process_create/3
from library(process)
provides a richer and more portable
alternative for interacting with processes including handling all three
standard streams.
If SrcDest is an IRI, i.e., starts with
<scheme>://
, where <scheme>
is a non-empty sequence of lowercase ASCII letters open/3,4
calls hooks registered by register_iri_scheme/3.
Currently the only predefined IRI scheme is res
, providing
access to the resource database. See
section 14.4.
The following Options are recognised by open/4:
- alias(Atom)
- Gives the stream a name and unifies Stream with Atom. Below is an
example. Be careful with this option as stream names are global. See
also set_stream/2.
?- open(data, read, Fd, [alias(input)]).
...,
read(input, Term),
...
- bom(Bool)
- Check for a BOM (Byte Order Marker) or write one. If omitted,
the default is
true
for mode read
and
false
for mode write
. See also stream_property/2
and especially section
2.18.1.1 for a discussion of this feature.
- buffer(Buffering)
- Defines output buffering. The atom
full
(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_abort(Bool)
- If
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 pipe/1
construct).
- create(+List)
- Specifies how a new file is created when opening in
write
,
append
or update
mode. Currently, List
is a list of atoms that describe the permissions of the created file.100Added
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.
- read
- Allow read access to the file.
- write
- Allow write access to the file.
- execute
- Allow execution access to the file.
- default
- Allow read and write access to the file.
- all
- Allow any access provided by the OS.
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, write
to 0222 and execute
to 0111. On POSIX systems, the final
permission is defined as (mode & ~
umask).
- encoding(Encoding)
- Define the encoding used for reading and writing text to this stream.
The default encoding for type
text
is derived from the
Prolog flag encoding.
For binary
streams the default encoding is octet
.
For details on encoding issues, see section
2.18.1.
- eof_action(Action)
- Defines what happens if the end of the input stream is reached. The
default value for Action is
eof_code
, which makes 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 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.
- locale(+Locale)
- Set the locale that is used by notably format/2
for output on this stream. See section
4.23.
- lock(LockingMode)
- Try to obtain a lock on the open file. Default is
none
,
which does not lock the file. The value read
or shared
means other processes may read the file, but not write it. The value
write
or exclusive
means no other process may
read or write the file.
Locks are acquired through the POSIX function fcntl() using
the command
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!
The lock
option is a SWI-Prolog extension.
- newline(Mode)
- Set end-of-line processing for the stream. Mode is one of
posix
, dos
or detect
. This option
is ignored for binary streams. Using detect
on an output
stream raises an exception. See also set_stream/2.
- reposition(+Bool)
- If
false
(default true
), drop the position
tracking logic from the stream. This disables the use of stream_position/3
on this stream.
- type(Type)
- 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. See also the
option encoding
.
- wait(Bool)
- This option can be combined with the
lock
option. If
false
(default 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)
.