11.3.141 open/[3,4] [ISO]

Synopsis

open(+FileSpec, +Mode, -Stream)

open(+FileSpec, +Mode, -Stream, +Options)

Creates a Prolog stream by opening the file FileSpec in mode Mode with options Options.

Arguments

FileSpec

file_spec or integer, must be ground

A file specification or file descriptor.

Mode

one of [read,write,append], must be nonvar

An atom specifying the open mode of the target file. One of:

read

open FileSpec for input.

write

open FileSpec for output. A new file is created if FileSpec does not exist. If the file already exists, then it is set to empty and its previous contents are lost.

append

opens FileSpec for output. If FileSpec already exists, adds output to the end of it. If not, a new file is created.

Options

list of term, must be ground

A list of zero or more of the following.

type(+T)

Specifies whether the stream is a text or binary stream. Default is text.

reposition(+Boolean)

Specifies whether repositioning is required for the stream (true), or not (false). The latter is the default.

alias(+A)

Specifies that the atom A is to be an alias for the stream.

eof_action(+Action)

Specifies what action is to be taken when the end of stream has already been reported (by returning -1 or end_of_file), and a further attempt to input is made. Action can have the following values:

error

An exception is raised. This is the default.

eof_code

An end of stream indicator (-1 or end_of_file) is returned again.

reset

The stream is considered not to be past end of stream and another attempt is made to input from it.

encoding(Encoding)

Specifies the encoding to use if the stream is opened in text mode, as an atom. The default is 'ISO-8859-1', the 8 bit subset of UNICODE, i.e. “ISO 8859/1” (Latin 1) (see ref-iou-sfh-enc).

Overridden by the encoding_signature/1 option, see below.

encoding_signature(+Boolean)

Specifies whether an encoding signature should be used (true), or not (false). An encoding signature is a special byte sequence that identifies the encoding used in the file. The most common case is one of the Unicode signatures, often called “byte order mark” (BOM).

A Unicode signature is a special byte sequence that can be used to distinguish between several UTF encoding variants, such as “UTF-8”, “UTF-16-BE” and “UTF-16-LE”.

If the file is opened in mode read then encoding_signature/1 defaults to true. When encoding_signature(true) is specified additional heuristics will be used if no Unicode signature is detected. Only if neither a Unicode signature nor these heuristics specifies a character encoding will the encoding/1 option, if any, be used.

The method used for selecting character encoding when a text file is opened in mode read is the first applicable item in the following list:

1. If the encoding_signature/1 option is true (the default): If a byte order mark is detected it will be used to select between the encodings “UTF-8”, “UTF-16” or “UTF-32” with suitable endianess.
2. If the encoding_signature/1 option is true (the default): If an Emacs style `-*- coding: coding-system-*-' is present on the first non-empty line of the file then it will be used.
3. If an option encoding(ENCODING) is supplied, the specified encoding will be used.
4. As a final fallback, “ISO 8859/1” (Latin 1) will be used.

the character encoding selected in this way will be used if it is recognized, otherwise an error exception is raised.

If the file is opened in mode write then it depends on the character encoding whether an encoding signature will be output by default or not. If you want to force an encoding signature to be output for those encodings that supports it you can specify encoding_signature(true). Conversely, if you want to prevent an encoding signature from being output you can explicitly specify encoding_signature(false).

All UTF encodings supports an encoding signature in the form of a BOM. “UTF-8” does not write a BOM unless you explicitly specify encoding_signature(true), the 16 and 32 bit UTF encodings, e.g. “UTF-16 BE”, “UTF-32 LE” writes a BOM unless explicitly requested not to with encoding_signature(false).

If the file is opened in mode append then encoding_signature/1 defaults to false.

eol(Eol)

Specifies how line endings in the file should be handled if the stream is opened in text mode.

In Prolog code, end of line is always represented by the character '\n', which has character code 10, i.e. the same as ASCII Line Feed (<LFD>). The representation in the file may be different, however.

Eol can have the following values:

lf

Line Feed (LF, character code 10) is used to specify a end of line. This can be used for both read mode and write mode streams.

crlf

A two character sequence Carriage Return (CR, character code 13) followed by Line Feed (LF, character code 10) is used to specify a end of line. This can be used for both read mode and write mode streams.

auto

Translate both the two character sequence CR LF and single CR or LF into an end of line character. This can be used only for read mode streams.

default

Use a default end of line convention. This is the default.

Under UNIX, this uses lf for streams opened in write mode and auto for streams opened in read mode. Under Windows, this uses crlf for streams opened in write mode and auto for streams opened in read mode. This can be used for both read mode and write mode streams.

if_exists(+Action)

Specifies what should happen if the file already exists. Only valid if Mode is write or append. Action can have the following values:

default

The file is overwritten or appended to, according to the Mode argument. This is the default.

error

An exception is raised.

generate_unique_name

If a file named FileSpec already exists, FileSpec is rewritten so that it refers to a non-existing file. FileSpec is rewritten by adding digits at the end of the file name (but before any extension). The generated name, RealName can be obtain by using stream_property(Stream, file_name(RealName)) on the resulting stream. See the example below.

Description

If FileSpec is a valid file specification, the file that it denotes is opened in mode Mode.

The resulting stream is unified with Stream.

Stream is used as an argument to Prolog input and output predicates.

Stream can also be converted to the corresponding foreign representation through stream_code/2 and used in foreign code to perform input/output operations.

The following example creates two log files, both based on the the base name my.log. The files will be written to a directory suitable for temporary files (see ref-fdi-fsp-pre).

     open(temp('my.log'), write, S1, [if_exists(generate_unique_name)]),
     open(temp('my.log'), write, S2, [if_exists(generate_unique_name)]),
     stream_property(S1, file_name(N1)),
     stream_property(S2, file_name(N2)),
     format('Logging to ~a and ~a~n', [N1, N2]),
     ...

Under UNIX this would produce something like:

     Logging to /tmp/my.log and /tmp/my1886415233.log

Exceptions

instantiation_error

FileSpec or Mode is not instantiated. Options argument is not ground.

type_error

FileSpec or Mode is not an atom type. Options is not a list type or an element in Options is not a correct type for open options.

domain_error

Mode is not one of read, write or append. Options has an undefined option or an element in Options is out of the domain of the option.

existence_error

The specified FileSpec does not exist.

permission_error

Can not open FileSpec with specified Mode and Options.

resource_error

There are too many files opened.

See Also

ref-iou-sfh.