lseek()--Set File Read/Write Offset

 #include <unistd.h>

 off_t lseek(int file_descriptor, off_t offset, int whence);  

The lseek() function changes the current file offset to a new position in the file. The new position is the given byte offset from the position specified by whence. After you have used lseek() to seek to a new location, the next I/O operation on the file begins at that location.

lseek() lets you specify new file offsets past the current end of the file. If data is written at such a point, read operations in the gap between this data and the old end of the file will return bytes containing binary zeros (or bytes containing blanks in the QSYS.LIB and independent ASP QSYS.LIB file systems). In other words, the gap is assumed to be filled with zeros (or with blanks in the QSYS.LIB and independent ASP QSYS.LIB file systems). Seeking past the end of a file, however, does not automatically extend the length of the file. There must be a write operation before the file is actually extended.

There are some important considerations for lseek() if the O_TEXTDATA and O_CCSID flags were specified on the open(), the file CCSID and open CCSID are not the same, and the converted data could expand or contract:

• Making assumptions about data size and the current file offset is extremely dangerous. For example, a file might have a physical size of 100 bytes, but after an application has read 100 bytes from the file, the current file offset may be only 50. To read the whole file, the application might have to read 200 bytes or more, depending on the CCSIDs involved. Therefore, lseek() will only be allowed to change the current file offset to:
  
  
  • The start of the file (offset 0, whence SEEK_SET)
    
  • The end of the file (offset 0, whence SEEK_END). In this case, the function will return a calculated value based on the physical size of the file, the CCSID of the file, and the CCSID of the open instance. This may be different than the actual file offset.

  If any other combination of values is specified, lseek() fails and errno is set to ENOTSUP.

• Internally-buffered data from a read or write operation is discarded. See read()--Read from Descriptor and write()--Write to Descriptor for more information concerning internal buffering of text data.
  
  
• The expected state for the current text conversion is reset to the initial state. This consideration applies only when using a CCSID that can represent data using more than one graphic character set or containing characters of different byte lengths. Some CCSIDs require an escape or shift sequence to signify a state change from one character set or byte length to another. Failing to account for this consideration could lead to incorrect text conversion if, for instance, a double-byte character at the new file offset was treated as two single-byte characters by the conversion function.
  
  
• The fcntl() API supports F_GETCVT and F_SETCVT which allow the saving and restoring of the file offset and conversion information. See the fcntl() API for more details.
  
  

In the QSYS.LIB file and independent ASP QSYS.LIB file systems, while in text mode, you can only seek to the beginning of a member; otherwise, error [EINVAL] will be returned.

Parameters

file_descriptor

(Input) The file whose current file offset you want to change.

offset

(input) The amount (positive or negative) the byte offset is to be changed. The sign indicates whether the offset is to be moved forward (positive) or backward (negative).

whence

(Input) One of the following symbols (defined in the <unistd.h> header file):

SEEK_SET

The start of the file

SEEK_CUR

The current file offset in the file

SEEK_END

The end of the file

If bits in whence are set to values other than those defined above, lseek() fails with the [EINVAL] error.

Authorities

No authorization is required. Authorization is verified during open() or creat().

Return Value

value

lseek() was successful. The value returned is the new file offset, measured in bytes from the beginning of the file.

-1

lseek() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If lseek() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. Network File System Differences

   Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations (several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data).

3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   This function is not supported for save files and will fail with error code [ENOTSUP].

4. This function will fail with the [EOVERFLOW] error if the resulting file offset would be a value that cannot be represented correctly in a variable of type off_t (the offset is greater than 2 GB minus 2 bytes).
   
   
5. When you develop in C-based languages and an application is compiled with the _LARGE_FILES macro defined, the lseek() API will be mapped to a call to the lseek64() API. Additionally, the data type off_t will be mapped to the type off64_t.
   
   
6. Using this function with the write(), pwrite(), and pwrite64() functions on the /dev/null or /dev/zero character special file will not result in the file data size changing from zero.
   
   

Related Information

• The <unistd.h> file (see Header Files for UNIX^®-Type Functions)
  
• creat()--Create or Rewrite File
  
• dup()--Duplicate Open File Descriptor
  
• fclear()--Write (Binary Zeros) to Descriptor
  
• fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
  
• fcntl()--Perform File Control Command
  
• lseek64()--Set File Read/Write Offset (Large File Enabled)
  
• open()--Open File
  
• pread()--Read from Descriptor with Offset
  
• pread64()--Read from Descriptor with Offset (large file enabled)
  
• pwrite()--Write to Descriptor with Offset
  
• pwrite64()--Write to Descriptor with Offset (large file enabled)
  
• read()--Read from Descriptor
  
• write()--Write to Descriptor

Example

The following example positions a file (that has at least 11 bytes) to an offset of 10 bytes before the end of the file.

lseek(file_descriptor,-10,SEEK_END);

[ Back to top | UNIX-Type APIs | APIs by category ]