lseek(), lseek64()
Set the current read/write file offset
Synopsis:
#include <sys/types.h>
#include <unistd.h>
off_t lseek( int filedes,
off_t offset,
int whence );
off64_t lseek64( int filedes,
off64_t offset,
int whence );
Arguments:
- filedes
- The file descriptor of the file whose position you want to set.
- offset
- The relative offset from the file position determined by the whence argument.
- whence
- The position in the file.
The possible values (defined in <unistd.h>) are:
- SEEK_CUR
- The new file position is computed relative to the current file position. The value of offset may be positive, negative or zero.
- SEEK_END
- The new file position is computed relative to the end of the file.
- SEEK_SET
- The new file position is computed relative to the start of the file. The value of offset must not be negative.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The lseek() and lseek64() functions set the current file position (i.e., the location at which the next read or write will start) for the file descriptor specified by filedes.
Classificationin
What's in a Function Description?.
An error occurs if the requested file position is before the start of the file.
If the requested file position is beyond the end of the file and data is
written at this point, subsequent reads of data in the gap will return bytes
whose value is equal to zero ('\0'
) until data is actually
written into the gap.
These functions don't extend the size of a file (see ftruncate()).
Returns:
The current file position, with 0 indicating the start of the file, or -1 if an error occurs (errno is set).
Errors:
- EBADF
- The filedes argument isn't a valid file descriptor.
- EINVAL
- The whence argument isn't a proper value, or the resulting file offset is invalid.
- ENOSYS
- The underlying device is incapable of seeking.
- EOVERFLOW
- The resulting file offset is a value that can't be represented correctly in an object of type off_t.
- ESPIPE
- The filedes argument is associated with a pipe, FIFO, or socket.
Examples:
Using the lseek() function, you can get the current file position. You can then use this value with another call to lseek() to reset the file position:
off_t file_posn;
int filedes;
/* get current file position */
file_posn = lseek( filedes, 0L, SEEK_CUR );
…
/* return to previous file position */
file_posn = lseek( filedes, file_posn, SEEK_SET );
If all records in the file are the same size, the position of the nth record can be calculated and read like this:
#include <sys/types.h>
#include <unistd.h>
int read_record( int filedes, long rec_numb,
int rec_size, char *buffer )
{
if( lseek( filedes, rec_numb * rec_size,
SEEK_SET ) == -1L ) {
return -1;
}
return( read( filedes, buffer, rec_size ) );
}
The read_record() function in this example assumes records are numbered starting with zero, and that rec_size contains the size of a record in the file, including any record-separator characters.
Classification:
lseek() is POSIX 1003.1; lseek64() is Large-file support
Safety: | |
---|---|
Cancellation point | Yes |
Signal handler | Yes |
Thread | Yes |