Function

lseek invokes the lseek callable service to change the file offset of a file to a new position. The file offset is the position in a file from which data is next read or to which data is next written.

Refer to z/OS UNIX System Services Programming: Assembler Callable Services Reference for restrictions when running in a conversion environment.

Parameters

fd

The file descriptor (a number) for the file whose offset you want to change. The file descriptor is returned when the file is opened.

position

A number indicating the number of bytes by which you want to change the offset. If the number is unsigned, the offset is moved forward that number of bytes; if the number is preceded by a - (minus sign), the offset is moved backward that number of bytes.

whence

A numeric value that indicates the point from which the offset is calculated. You can specify a numeric value (see REXX predefined variables) or the predefined variable beginning with SEEK_ used to derive the appropriate numeric value:

Variable	Description
SEEK_CUR	Set the file offset to current offset plus the specified offset.
SEEK_END	Set the file offset to EOF plus the specified offset.
SEEK_SET	Set the file offset to the specified offset.

Usage notes

1. position gives the length and direction of the offset change. whence states where the change is to start. For example, assume that a file is 2000 bytes long, and that the current file offset is 1000:

   Position specified	Whence	New file offset
   80	SEEK_CUR	1080
   1200	SEEK_SET	1200
   -80	SEEK_END	1920
   132	SEEK_END	2132

2. The file offset can be moved beyond the end of the file. If data is written at the new file offset, there will be a gap between the old end of the file and the start of the new data. A request to read data from anywhere within that gap completes successfully, and returns bytes with the value of zero in the buffer and the actual number of bytes read.

   Seeking alone, however, does not extend the file. Only if data is written at the new offset does the length of the file change.