Sets FILEHANDLE's system position in bytes using lseek(2). FILEHANDLE may
be an expression whose value gives the name of the filehandle. The values
for WHENCE are 0
to set the new position to POSITION; 1
to set the it
to the current position plus POSITION; and 2
to set it to EOF plus
POSITION, typically negative.
Note the emphasis on bytes: even if the filehandle has been set to operate
on characters (for example using the :encoding(UTF-8)
I/O layer), the
seek,
tell, and
sysseek
family of functions use byte offsets, not character offsets,
because seeking to a character offset would be very slow in a UTF-8 file.
sysseek bypasses normal buffered IO, so mixing it with reads other than sysread (for example readline or read), print, write, seek, tell, or eof may cause confusion.
For WHENCE, you may also use the constants SEEK_SET
, SEEK_CUR
,
and SEEK_END
(start of the file, current position, end of the file)
from the Fcntl module. Use of the constants is also more portable
than relying on 0, 1, and 2. For example to define a "systell" function:
Returns the new position, or the undefined value on failure. A position
of zero is returned as the string "0 but true"
; thus
sysseek returns
true on success and false on failure, yet you can still easily determine
the new position.