lseek (BPX1LSK, BPX4LSK) — Change a file's offset

Function

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.

Requirements

Parameters

File_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

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.

Offset

Parameter supplied and returned

Type:

Integer

Length:

Doubleword

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.

Reference_point

Supplied parameter

Type:

Integer

Length:

Fullword

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.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the lseek service stores the return code. The lseek service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The lseek service can return one of the following values in the Return_code parameter:

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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

Usage notes

1. The Offset parameter gives the length and direction of the offset change. Reference_point parameter 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:

   Offset specified	Reference point	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 is 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 itself, however, does not extend the file. Only if data is written at the new offset does the length of the file change.

Related services

• fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
• open (BPX1OPN, BPX4OPN) — Open a file
• read (BPX1RED, BPX4RED) — Read from a file or socket
• sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action
• write (BPX1WRT, BPX4WRT) — Write to a file or a socket

Characteristics and restrictions

When automatic conversion is enabled to ALL (that is, Unicode conversion is in effect), a lseek operation for a file containing multibyte characters can cause a subsequent read (BPX1RED/BPX4RED) or write (BPX1WRT/BPX4WRT) operation to fail due to the following cases:

1. The cursor jumps to another code page in a file tagged with a CCSID that has multiple code pages. The subsequent read will fail. However, using lseek to position the cursor to the beginning of the file is acceptable. The code page will be reset to the beginning default defined for the CCSID.
2. The previous write operation caused LFS to internally cache an incomplete multibyte character which, as a result of the lseek, is no longer convertible. The subsequent read or write will fail.
3. The cursor jumps to a position which is not on a character boundary. The subsequent read will fail.