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

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.

Format

CALL BPX1LSK,(File_descriptor,
              Offset,
              Reference_point,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4LSK with the same parameters.

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

Start of change

Characteristics and restrictions

Start of changeWhen 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 Start of changeconvertibleEnd of change. 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.
End of change

End of change

Examples

For an example using this callable service, see BPX1LSK (lseek) example.