glk_stream_set_position ()

void
glk_stream_set_position (strid_t str,
                         glsi32 pos,
                         glui32 seekmode);

Sets the position of the read/write mark in str . The position is controlled by pos , and the meaning of pos is controlled by seekmode . See the seekmode_ constants below.

It is illegal to specify a position before the beginning or after the end of the file.

In binary files, the mark position is exact — it corresponds with the number of characters you have read or written. In text files, this mapping can vary, because of linefeed conventions or other character-set approximations. See Streams. glk_stream_set_position() and glk_stream_get_position() measure positions in the platform's native encoding — after character cookery. Therefore, in a text stream, it is safest to use glk_stream_set_position() only to move to the beginning or end of a file, or to a position determined by glk_stream_get_position().

Again, in Latin-1 streams, characters are bytes. In Unicode streams, characters are 32-bit words, or four bytes each.

A window stream doesn't have a movable mark, so calling glk_stream_set_position() has no effect.

glk_stream_get_position ()

glui32
glk_stream_get_position (strid_t str);

Returns the position of the read/write mark in str . For memory streams and binary file streams, this is exactly the number of characters read or written from the beginning of the stream (unless you have moved the mark with glk_stream_set_position().) For text file streams, matters are more ambiguous, since (for example) writing one byte to a text file may store more than one character in the platform's native encoding. You can only be sure that the position increases as you read or write to the file.

Additional complication: for Latin-1 memory and file streams, a character is a byte. For Unicode memory and file streams (those created by glk_stream_open_file_uni() and glk_stream_open_memory_uni()), a character is a 32-bit word. So in a binary Unicode file, positions are multiples of four bytes.

glk_stream_get_position() on a window stream will always return zero.

seekmode_Start

#define seekmode_Start (0)

In glk_stream_set_position(), signifies that pos is counted in characters after the beginning of the file.

seekmode_Current

#define seekmode_Current (1)

In glk_stream_set_position(), signifies that pos is counted in characters after the current position (moving backwards if pos is negative.)

seekmode_End

#define seekmode_End (2)

In glk_stream_set_position(), signifies that pos is counted in characters after the end of the file. (pos should always be zero or negative, so that this will move backwards to a position within the file.