.TH lseek() "" "" "System Call (libc)"
.PC "Set read/write position"
.B "#include <unistd.h>"
\fBlong lseek(\fIfd\^\fB,\fI where\^\fB,\fI how\^\fB)
\fBint\fI fd\^\fB,\fI how\^\fB; long\fI where\^\fB;\fR
.PP
\fBlseek()\fR changes the \fIseek position\fR, or the point
within a file where the next read or write operation is performed.
.I fd
is the file's file descriptor, which is returned by \fBopen()\fR.
.PP
.I where
and
.I how
describe the new seek position.
.I where
gives the number of bytes
that you wish to move the seek position.
It is measured from the beginning of the file if
.I how
equals
.B SEEK_SET
(zero), from the current seek position if
.I how
equals
.B SEEK_CUR
(one), and from the end of the file if
.I how
equals
.B SEEK_END
(two).
A successful call to
.B lseek()
returns the new seek position.
For example,
.DM
	position = lseek(fd, 100L, SEEK_SET);
.DE
.PP
moves the seek position 100 bytes past the beginning of the file;
whereas
.DM
	position = lseek(fd, 0L, SEEK_CUR);
.DE
.PP
returns the current seek position and does not change the
seek position at all.
.PP
.II "sparse file"
.II "file^sparse"
You can create a
.I "sparse file"
by seeking beyond the current size of the file and writing.
The ``hole'' between the end of the file and where the write occurs
is read as zero and will occupy no disk space.
For example, if
you \fBlseek()\fR 10,000 bytes past the current end of file and write a string,
the data will be written 10,000 bytes past the old end of file
and all intervening matter will be considered part of the file.
.PP
.B lseek()
differs from its cousin
.B fseek()
in that
.B lseek()
is a system call and uses a file descriptor, whereas
.B fseek()
is a C function and uses a
.B FILE
pointer.
.PP
If all goes well,
.B lseek()
returns the new seek position.
If an error occurs, such as seeking to a negative position,
.B lseek()
returns \-1L and sets
.B errno
to an appropriate value.
.SH "See Also"
.Xr "libc," libc
.Xr "unistd.h" unistd.h
.br
\*(PX Standard, \(sc6.5.3
.SH Notes
.B lseek()
is permitted on character-special files, but drivers do not
generally implement it.
As a result, seeking a terminal will not generate an error
but will have no discernible effect.
