11.3.200 seek/4

Synopsis

seek(+Stream, +Offset, +Method, -NewLocation)

Seeks to an arbitrary position in Stream.

Arguments

Stream

stream_object, must be ground

A valid Prolog stream.

Offset

integer, must be nonvar

The offset, in items, to seek relative to the specified Method. Items are bytes for binary streams, characters for text streams.

Method

one of [bof,current,eof], must be nonvar

Where start seeking, one of the following:

bof

Seek from beginning of the file stream.

current

Seek from current position of the file stream.

eof

Seek from end of the file stream.

NewLocation

integer

The offset from beginning of the file after seeking operation.

Description

Sets the current position of the file stream Stream to a new position according to Offset and Method. If Method is:

bof

the new position is set to Offset items from beginning of the file stream.

current

the new position is Offset plus the current position of Stream.

eof

the new position is Offset, plus the current size of the stream.

Avoid using this Method. Determining the size of the stream may be expensive or unsupported for some streams.

Positions and offsets are measured in items, bytes for binary streams and characters for text streams. Note that there may not be any simple relationship between the number of characters read and the byte offset of a text file.

After applying this operation on a text stream, the line counts and line position aspects of the stream position of Stream will be undefined.

The term “file” above is used even though the stream may be connected to other seekable objects that are not files, e.g. an in-memory buffer.

Exceptions

Stream errors (see ref-iou-sfh-est), plus:

instantiation_error

Offset or Method is not instantiated.

type_error

Stream is not a stream object, or Offset is not an integer, or Method is not an atom.

domain_error

Method is not one of bof, current or eof, or the resulting position would refer to an unsupported location. Some streams supports setting the position past the current end of the stream, in this case the stream is padded with zero bytes or characters as soon as an item is written to the new location.

permission_error

Seeking was not possible. Common reasons include: the stream has not been opened with reposition(true), the stream is a text stream that does not implement seeking, or an I/O error happened during seek.

See Also

stream_position/2, set_stream_position/2, open/[3,4], byte_count/2, character_count/2, line_count/2, line_position/2, ref-iou-sfh.