open/[3,4]

Synopsis

open(+FileSpec, +Mode, -Stream)

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

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

Arguments

FileSpec file_spec

a file specification (see ref-fdi).

Mode one of [read,write,append]

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

a list of zero or more of the following.

text

Specifies that the file stream is a text stream. This sets the line border code to <LFD>, the file border code to -1, and turns on trimming. This is the default.

binary

Specifies that the file stream is a binary stream. This sets the line border code to none, the file border code to -1, the format to variable, and turns off trimming.

record(Size)

Size is an integer value to specify the maximum record (line) size in the file. This also sets the internal buffer size to be used for input/output options on the stream to Size. If Size is 0, the opened stream operates in non-buffered mode. The value of Size should be greater than or equal to 0.

Under UNIX, the default is 256 for tty streams and 8192 for other stream.

end_of_line(EolCode)

EolCode is an integer value to specify the line (record) border code for the stream. EolCode is

-1

Indicates there is no line border code.

Charcode

ASCII code for EOL character. Default = <LFD> (ASCII code for <LFD>).

If an output predicate writes out the character whose code is the line border code of the stream, the Prolog system terminates the output record according to the format of the stream.

end_of_file(EofCode)

EofCode is an integer value to specify the file border code for an input stream.

-2

Indicates there is no file border code for the stream. Reading at the end of file is same as reading past end of file.

The file border code is the value to be returned to an input predicate when an input stream reaches the end of file. The default file border code is -1.

eof_action(Action)

Specifies what to do for reading past end of file. This option has no effect on an output stream. Action is one of the following.

error

It's an error to read past end of file. This is the default for text binary streams.

eof_code

Return file border code as set in end_of_file option for reading past end of file.

reset

Reset the stream and make an attempt to read for input past end of file. This is the default for tty stream.

overflow(OvAction)

Specifies what to do when output overflows the current record size. This option has no effect on an input stream. OvAction is one of the following.

error

It's an error.

truncate

Discard the overflow characters.

flush

Write out the overflow partial record (line). No characters are discarded. This is the default under UNIX and Windows.

seek(SeekOption)

Request seeking method that will be performed on the file. SeekOption is defined as follows:

error

It's an error to issue a seeking command on the stream. This is the default for a tty stream.

previous

The seeking request will be made only to a previous input/output position. stream_position/3 is the only predicate that can be used to seek on the stream. This is the default for both text and binary streams.

byte

Seeking to an arbitrary byte position on the stream. This option also permits seek(previous). Both stream_position/3 and seek/4 work on the stream.

record

Seeking to the beginning of an arbitrary record in the file stream. This option is not available under UNIX or Windows.

flush(FlushType)

Request flushing method for an output stream. This option has no effect on an input stream. It can be one of the following.

error

It's an error to try to flush an output stream.

flush

Write out all the characters buffered. This is the default under UNIX and Windows.

trim

Turns on the trimming on the file stream. Trimming means that trailing blanks are deleted in input records. The default is no trimming. See format below.

system(SysAttrs)

This option is provided to allow extensions.

SysAttrs

must be an atom and is passed to the QU_open() function, which can be redefined by the user. The default version of QU_open() will report an error, causing a permission_error to be raised, if system(SysAttrs) is specified.

format(Format)

Specifies the file format (see fli-ios-sst-fmt). For Prolog running under UNIX and Windows, the default format is format(delimited(lf)) for text stream, format(variable) for binary stream, and format(delimited(tty)) for tty file. Users will not normally need to use the format(Format) options directly. Format is one of:

variable

Each record in the file has its own length. There are no delimiter characters between records. The Prolog system removes the trailing blank characters for each input record it reads if the trim option is set.

delimited(lf)

For an application program's point of view, a single <LFD> (ASCII code 10) terminates each record in the file. Under Windows, however, what's actually stored in the file is the sequence <RET><LFD>.

delimited(tty)

FileSpec is a terminal device, a pseudo-terminal device, or a terminal emulator. The Prolog input/output system treats this format like QP_DELIM_LF as far as record termination is concerned.

If one of these delimiters is specified, the Prolog system removes the delimiter characters at the end of record for input. The line border code (specified by end_of_line option) is returned instead as the character code at the end of the record. Prolog system also puts delimiter characters at the end of record when a record is written out.

When no format has been specified, the format is decided as follows: if there is no line border code and trimming is off, then format(variable) is used; otherwise format(delimited(lf)) is used.

Stream

stream_object the resulting opened Prolog stream.

Description

open/3 is equivalent to open/4 with Options=[].

open/4 is designed to work on various file systems under different operating systems.

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.

Exceptions

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.

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.

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.

Comments

If an option is specified more than once the rightmost option takes precedence.

Prolog streams are in general classified as tty streams, text streams, or binary streams. A Prolog stream is a tty stream if the format of the stream is set to format(delimited(tty)), or if no format is specified and FileSpec refers to a terminal (decided by the function isatty(3)). Prolog provides a special service to print prompts for a tty input stream. A text stream corresponds to a text file. The Prolog system removes the control characters of the text stream. A binary stream is a stream of bytes; the Prolog system returns the actual characters stored in the file. Specifying binary or text along with trim and end_of_line options will result in a hybrid of binary and text streams.

Defaults are provided for Options in QU_stream_param() function. This description is based on those input/output defaults.

Format is seldom set by the user. It is only useful in case the user has redefined QU_open().

Examples

1. Opening a stream that behaves like a C standard I/O stream without maintaining correct line count and line position.

             open(FileSpec, Mode, [binary, seek(byte),
                     eof_action(eof_code)], Stream).
             

2. Opening a non-buffered stream

                  open(FileSpec, Mode, [record(0)], Stream).
             

3. On UNIX systems, if FileSpec is /dev/tty, it means that the file is the default tty for the Prolog system. Terminal is used interactively.

See Also

open_null_stream/1, close/1, QP_prepare_stream/[3,4] QP_fopen(), QP_fdopen(), QU_open() fli-emb-how-iou