binio-fseek


Synopsis

(binio-fseek <stream> <pos> [start-from])

Description

Moves the file pointer of stream to the given position. If the optional argument start-from is given, it may have the values 0, 1 or 2:

0 (the default value) counts the position absolutely from the start of the file.

1 counts the position absolutely from the end of the file.

2 counts the position relatively from the actual file position.

Those values are defined keywords, symbols which evaluate to themselves, so you don't necessarily need to quote them.

If the file is open for write (mode "w") or append (mode "a") the position must not be advanced forwards beyond the actual filesize! Otherwise an error is thrown.

Dependant on an external library: so far only binio.fas for ViLL or vlisp.

Examples

(binio-fseek f 0) ; moves the filepointer to the start of the file, same as (binio-frewind f)

(binio-fseek f 10 0) ; moves the filepointer to the 10th byte.

(binio-fseek f 1 1) ; moves the filepointer to the last byte of the file. The next (binio-fgetc f) will return the integer value of the last byte.

(binio-fseek f 4 2) ; advances the filepointer by 4 byte.

(binio-fseek f -1 2) ; moves the filepointer back by 1 byte. Same as the function unread-char on certain systems.

Arguments

stream: internal object representation of a opened binary file.

pos: either a integer or a floating point number which is converted to a integer.

start-from: optional argument introduced with version 2.1. The default value is 0. Accepted values are 0, 1 or 2 (or to stay incompatible in VL only as well the symbols :START, :END or :RELATIVE)

Return Value

Either the new file pointer position as integer. Or a real number if the number is too large for the current AutoLISP integer representation. Or nil on any non-serious error. (when nil?)

Side Effects

Moves the actual file pointer position of the open stream so that the next binio-fget or binio-fput function reads from or writes to the new position.

Module

(std-require-external 'BINIO)

Defined in BINIO