Scieneer Common Lisp 1.3.9 online documentation

ext:stream-file-position stream &optional position[Generic Function]

When the position is nil, returns the current position within the stream or nil if the position can not be determined. When a position is given it becomes the new file position, returning t if the position is successfully changed otherwise returning nil. The second argument may also be :start or :end for the start and end of the file, respectively.

The position is measured in units of bytes for binary streams and in units of characters for character streams, and is defined as the number of bytes or characters returned by read-byte or read-char when reading from the start of the file to the current position. The position may not be the same as the position in the underlying file due to non-unity encoding. For example: character encoding streams, compressed binary streams, or end-of-line conversion streams.

For each byte or character written the position change will typically be one but in general may be more or less than one. For example: an indenting output stream can insert characters at the start of each line resulting in a multi-character change in position when a linefeed is written; or a character conversion output stream may ignore and drop characters that can not be encoded. The caller is expected to firstly write and finish any pending buffered output so that the output can be processed and the position updated, otherwise position may not be correct and the output may be written to the wrong location. The caller is also expected to compensate for any buffered input on the stream. A default method is provided for the class stream that does nothing and returns nil.