lseek(2)
lseek, lseek64 --
move read/write file pointer
Synopsis
#include <sys/types.h>
#include <unistd.h>
off_t lseek(int fildes, off_t offset, int whence);
off64_t lseek64(int fildes, off64_t offset, int whence);
Description
lseek moves a read/write file pointer.
fildes is a file descriptor returned from a
creat(2),
open(2),
dup(2),
fcntl(2),
pipe(2)
or
ioctl(2)
system call.
lseek sets the file pointer associated with
fildes
as follows:
-
If whence is SEEK_SET, the pointer is set to
offset
bytes.
-
If whence is SEEK_CUR, the pointer is set to its current
location plus offset.
-
If whence is SEEK_END, the pointer is set to the size of the
file plus offset.
On success, lseek returns the resulting pointer location,
as measured in bytes from the beginning of the file.
lseek allows the file pointer to be set beyond the existing data
in the file.
If data is later written at this point, subsequent reads
in the gap between the previous end of data and the newly written data
return bytes of value 0 until data is written into the gap.
Return values
On success, lseek and lseek64 return a
non-negative integer indicating the file pointer value.
On failure, lseek and lseek64 return -1,
set errno to identify the error,
and the file pointer remains unchanged.
Some devices are incapable of seeking.
The value of the file pointer associated with such a device
is undefined.
Errors
In the following conditions, lseek fails and sets errno to:
EOVERFLOW-
The resulting file offset would be a value which cannot be represented
correctly in an object of type off_t.
The file pointer is not moved.
In the following conditions, lseek and lseek64 fail
and set errno to:
EBADF-
fildes
is not an open file descriptor.
ESPIPE-
fildes
is associated with a pipe, fifo or socket.
EINVAL-
The resulting file pointer would be negative.
fildes is a remote file descriptor accessed using NFS,
the Network File System,
and the resulting file pointer would be negative.
ENOSYS-
The device for fstype does not support lseek or
lseek64.
References
creat(2),
dup(2),
fcntl(2),
intro(2),
open(2)
Notices
Considerations for threads programming
Open file descriptors are a process resource and available to any sibling thread;
if used concurrently, actions by one thread can interfere with
those of a sibling.
For example, the position of the file pointer is maintained per file descriptor,
not per thread.
The
pread(2)
and
pwrite(2)
system calls combine positioning
and I/O in a single operation.
Considerations for Large File Support
lseek64 supports large files, but is otherwise identical
to lseek.
For details on programming for large file capable applications, see
``Large File Support''
on intro(2).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004