Quintus Prolog

`QP_seek()`

Synopsis

     #include <quintus/quintus.h>
     
     int QP_seek(stream, offset, whence)
     QP_stream *stream;
     long int   offset;
     int        whence;

Seeks to an arbitrary byte position on the stream.

Arguments

stream

pointer to a valid stream structure.

offset

the offset in bytes to seek relative to whence specified.

whence

specifies where to start seeking. It is one of the following.

QP_BEGINNING: seek from beginning of the file stream. The new position of the file stream is set to offset bytes.
QP_CURRENT: seek from current position of the file stream. The new position of the file stream is set to its current location plus offset.
QP_END: seek from end of the file stream. The new position of the file stream is set to the size of the file plus offset.

Description

The new position in bytes from the beginning of the file stream is stored in magic field of stream. It is stream->magic.byteno under UNIX.

If stream is an output stream permitting flushing output, the characters in the buffer of the stream is flushed through QP_flush() before seek is performed. If the stream does not permit flushing output and there are characters remaining in the output buffer, it is an error to seek. 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 QP_seek() returns.

Return Value

QP_SUCCESS: The function succeeds
QP_ERROR: There is an error in function call, the error number is stored in both QP_errno and stream->errno.

Errors

QP_E_INVAL

whence is not one of QP_BEGINNING, QP_CURRENT, or QP_END.

QP_E_CANT_SEEK

Unknown error in the bottom layer of seek function of stream

Errors from QP_flush()

Errors from host operating system

Tips

QP_seek(stream, 0L, QP_CURRENT) sets the current position to the magic field of stream. It does not change the position of stream, but the side effect of flushing output and clearing buffer also takes place.

Comments

The seek type in stream must permits seeking by bytes, i.e. the seek_type field in stream is QP_SEEK_BYTE. So stream is created by defining a private stream and setting seek_type field to QP_SEEK_BYTE, opening a Prolog stream with seek(byte) option in open/4, or opening a binary stream through QP_fopen() or QP_fdopen().

Examples

Get the current byte offset from beginning of the file stream.

     if (QP_seek(stream, 0L, QP_CURRENT) != QP_SUCCESS)
             QP_perror(stream->errno, "QP_seek");
     else
             location = stream->magic.byteno;

QP_seek()