'\"macro stdmacro
.if n .pH g2.lseek @(#)lseek	40.12 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} lseek 2 "" "\&"
.if \nX=1 .ds x} lseek 2 ""
.if \nX=2 .ds x} lseek 2 "" "\&"
.if \nX=3 .ds x} lseek "" "" "\&"
.TH \*(x}
.SH NAME
\f4lseek\f1 \- move read/write file pointer
.SH SYNOPSIS
\f4#include <sys/types.h>\f1
.br
\f4#include <unistd.h>\f1
.PP
\f4off_t lseek (int fildes, off_t offset, int whence);\f1
.SH DESCRIPTION
.I fildes\^
is a
file descriptor
returned from a
\f4creat\fP,
\f4open\fP,
\f4dup\fP,
or
\f4fcntl\fP
system call.
\f4lseek\fP
sets the file pointer associated with
.I fildes\^
as follows:
.RS
.HP 6
If
.I whence\^
is \f4SEEK_SET\fP, the pointer is set to
.I offset\^
bytes.
.HP 6
If
.I whence\^
is \f4SEEK_CUR\fP, the pointer is set to its current location plus
.IR offset .
.HP 6
If
.I whence\^
is \f4SEEK_END\fP, the pointer is set to the size of the
file plus
.IR offset .
.RE
.PP
On success, \f4lseek\fP returns the resulting pointer location,
as measured in bytes from the beginning of the file.
Note that if \f2fildes\f1 is a remote file descriptor
and \f2offset\f1 is negative, 
\f4lseek\fP returns the file pointer 
even if it is negative.
.PP
\f4lseek\fP allows the file pointer to be set beyond the existing data
in the file. If data are later written at this point, subsequent reads
in the gap between the previous end of data and the newly written data
will return bytes of value 0 until data are written into the gap.
.PP
\f4lseek\fP
fails and the file pointer remains unchanged
if one or more of the following are true:
.TP 15
\f4EBADF\fP
.I fildes\^
is not an open file descriptor.
.TP
\f4ESPIPE\fP
.I fildes\^
is associated with a pipe or fifo.
.TP
\f4EINVAL\fP
.I whence\^
is not \f4SEEK_SET\fP, \f4SEEK_CUR\fP, or \f4SEEK_END\fP.
The process also gets a \f4SIGSYS\fP signal.
.TP
\f4EINVAL\fP
\f2fildes\f1 is not a remote file descriptor, and
the resulting file pointer would be negative.
.PP
Some devices are incapable of seeking.
The value of the file pointer associated with such a device
is undefined.
.SH "SEE ALSO"
\f4creat\fP(2), \f4dup\fP(2), \f4fcntl\fP(2), \f4open\fP(2).
.SH "DIAGNOSTICS"
Upon successful completion, a non-negative integer
indicating the file pointer value
is returned.
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)lseek.2	6.2 of 9/6/83
.Ee
