The lseek callable services changes 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.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1LSK): | 31-bit |
AMODE (BPX4LSK): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4LSK with the same parameters.
The name of a fullword that contains the file descriptor for the file whose file offset is to be changed. The file descriptor is returned from open (BPX1OPN, BPX4OPN) — Open a file.
The name of a doubleword that contains a signed number. The numeric part of the value is the amount (number of bytes) by which you want to change the offset. The sign indicates whether you want the offset to be moved forward or backward in the file.
This field is a doubleword, to accommodate large files. For normal processing with a singleword value, propagate the sign bit through the second word, so that the final doubleword value has a valid sign.
On successful completion, this field returns the new file offset.
The name of a fullword that contains a value that represents an option. Reference_point indicates the point from which the offset is calculated. These values are mapped by the BPXYSEEK macro. For information on the contents of the macro, see BPXYSEEK — Constants for lseek.
The name of a fullword in which the lseek service returns 0 if the request is successful, or -1 if it is not successful. Offset returns the new file offset if the request is successful.
Return_code | Explanation |
---|---|
EBADF | The File_descriptor parameter does not specify a valid, open file. |
EINVAL | The Reference_point parameter contained something other than one of the three options; or the combination of the Offset and Reference_point parameters would have placed the file offset before the beginning of the file. The following reason codes can accompany the return code: JRLskOffsetIsInvalid, JRLskWhenceIsInvalid. |
ESPIPE | The File_descriptor refers to a pipe, a FIFO special file, or a socket. The following reason code can accompany the return code: JRLskOnPipe. |
The name of a fullword in which the lseek service stores the reason code. The lseek service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Offset specified | Reference point | New file offset | |
---|---|---|---|
80 | SEEK_CUR | 1080 | |
1200 | SEEK_SET | 1200 | |
-80 | SEEK_END | 1920 | |
132 | SEEK_END | 2132 |
Seeking itself, however, does not extend the file. Only if data is written at the new offset does the length of the file change.
For an example using this callable service, see BPX1LSK (lseek) example.