lseek() — Change the offset of a file
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1 |
both |
Format
#define _POSIX_SOURCE
#include <unistd.h>
off_t lseek(int fildes, off_t offset, int pos);
General description
Changes the current file offset to a new position in a z/OS UNIX file. The new position is the given byte offset from the position specified by pos. 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 zeros. (In other words, the gap is assumed to be filled with zeros.)
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.
- int fildes;
- The file whose current file offset you want to change.
- off_t offset;
- 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).
- int pos;
- 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
Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.
Returned value
If successful, lseek() returns the new file offset, measured in bytes from the beginning of the file.
- Error Code
- Description
- EBADF
- fildes is not a valid open file descriptor.
- EINVAL
- pos contained something other than one of the three options, or the combination of the pos values would have placed the file offset before the beginning of the file.
- EOVERFLOW
- The resulting file offset would be a value which cannot be represented correctly in an object of type off_t.
- ESPIPE
- fildes is associated with a pipe or FIFO special file.
Example
lseek(fildes,-10,SEEK_END);
Related information
- unistd.h
- creat() — Create a new file or rewrite an existing one
- dup() — Duplicate an open file descriptor
- fcntl() — Control open file descriptors
- fseek() — Change file position
- fsetpos() — Set file position
- open() — Open a file
- read() — Read from a file or socket
- sigaction() — Examine or change a signal action
- write() — Write data on a file or socket