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.


Send feedback on this subject.