Repositions a read/write file offset.
Syntax |
 |
#include <sys/types.h>
#include <unistd.h>
off_t lseek (int fildes, off_t offset, int whence);
|
Parameters |
|
- fildes
An open file descriptor.
- offset
The number of bytes for the new offset. The application of this value is defined by whence.
- whence
A value specifying how offset is to be applied to calculate the resultant offset. Following are valid values and their meanings (defined in <unistd.h>).
- SEEK_SET
Set new offset to offset.
- SEEK_CUR
Set new offset to offset plus the current offset.
- SEEK_END
Set new offset to offset plus the current file size.
Return Values |
|
- >=0
Success. The new file offset position is returned.
- -1
An error occurred. The current offset is not changed, and errno is set to indicate the error condition.
Description |
|
The lseek() function sets the file offset for the open
file description associated with fildes to a new position defined by both the offset and whence parameters. The file offset is the number of bytes from the beginning of the file (where the beginning of the file is file offset 0).
The lseek() function allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads of data in the gap return bytes with the value zero until data is actually written into the gap; however, the lseek() function cannot, by itself, extend the size of a file.
Implementation Considerations |
|
Refer to the ESEEK and ESYSERR error descriptions below.
Pipes (or FIFOs) and device special files are not supported.
Errors |
|
If an error occurs, errno is set to one of the following values:
| EBADF | CAUSE | The fildes parameter is not a valid open file descriptor. |
| | ACTION | Check to see if fildes has been altered or is not initialized. |
| EINVAL | CAUSE | The whence parameter is not a valid value, or the resulting
file offset would be invalid. |
| | ACTION | Check if value contained by whence exceeds the file limit or is a negative value. |
| ESEEK | CAUSE | The fildes parameter does not refer to a file that supports seeking. |
| | ACTION | Certain files or devices do not support seeking. Make sure that the program is not attempting to seek on those files. |
| ESYSERR | CAUSE | An operating system error has occurred that does not map directly to any of the above errors. |
| | ACTION | Examine the MPE/iX error stack for the type of system error. |
See Also |
|
creat(), dup(), open(), read(), sigaction(), write(), <unistd.h>, POSIX.1 (Section 6.5.3)
