seek/4

Synopsis

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

Seeks to an arbitrary byte position in Stream.

Arguments


Stream stream_object
a valid Prolog stream
Offset integer
the offset in bytes to seek relative to Method specified.
Method one of [bof,current,eof]
specifies where to start seeking. It is 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 byte 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 bytes from beginning of the file stream.
current
the new position is Offset bytes plus the current position of Stream.
eof
the new position is Offset bytes, a negative integer, plus the size of the file.

If Offset is 0, seek/4 returns the current position from the beginning of Stream and sets the position to the same location.

If Stream is an output stream permitting flushing output, the characters in the buffer of the stream are flushed before seek is performed. If the output stream Stream does not permit flushing output and there are characters remaining in the buffer, then a permission error is raised.

If Stream is an input stream, the characters in the input buffer of the stream are discarded before seek is performed. The input buffer is empty when the seek/4 call returns.

Exceptions

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


domain_error
Method is not one of bof, current or eof.

Offset is a negative value and Method is bof.

Offset is a positive value and Method is eof.

instantiation_error
Offset or Method is not instantiated.
type_error
Stream is not a stream object.

Offset is not an integer type.

Method is not an atom type.

permission_error
Stream names an open stream but the stream is not open with seek(byte) permission.

An error occurred while seeking in the file stream.

Flushing attempted but not permitted.

See Also

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