11.3.148 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, must be ground

A file specification.

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, then it adds output to the end of it. If not, then a new file is created, as for the write mode.

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.

For text streams reposition(true) affects the default eol/1 and encoding_signature/1 options, see below. Also, not all encodings supports this option (see ref-iou-sfh-enc).

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 reposition(true) is specified, then encoding_signature/1 defaults to false for both streams opened in write mode and streams opened in read mode.

If reposition(true) is not specified, and if the file is opened in mode read, then encoding_signature/1 defaults to true.

When encoding_signature/1 option is true 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: If a byte order mark is detected, then 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: 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, then 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 reposition(true) is not specified, and 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, then you can specify encoding_signature(true). Conversely, if you want to prevent an encoding signature from being output, then 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.

If reposition(true) is specified, then this uses lf for both streams opened in write mode and streams opened in read mode, on all platforms.

If reposition(true) is not specified, then 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, then 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 obtained by using stream_property(Stream, file_name(RealName)) on the resulting stream. See the example below.

With this option open/4 will never open an existing file but it may still fail to find a unique name. open/4 may fail to find a unique name if there are thousands of files with similar names. In that case open/4 behaves as if if_exists(error) had been passed.

Description

If FileSpec is a valid file specification, then 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.

On Windows, where file names are usually subject to case-normalization, the file will be created with the same case as in FileSpec. As an example, open('HelloWorld.txt', write, S), stream_property(S,file_name(Name)),close(S). will create a file with the mixed case name HelloWorld.txt whereas the stream property will reflect the case-normalized name .../helloworld.txt. Prior to release 4.3 the file would have been created in the file system with the case-normalized name helloworld.txt.

Exceptions

instantiation_error

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

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 or

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.

uninstantiation_error

Stream is not a variable

existence_error

The specified FileSpec does not exist.

permission_error

Cannot open FileSpec with specified Mode and Options.

system_error

Unexpected error detected by the operating system

Examples

The following example creates two log files, both based on 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

See Also

ref-iou-sfh.