87 lines
1.9 KiB
Groff
87 lines
1.9 KiB
Groff
.\" Copyright (c) 1980 Regents of the University of California.
|
|
.\" All rights reserved. The Berkeley software License Agreement
|
|
.\" specifies the terms and conditions for redistribution.
|
|
.\"
|
|
.\" @(#)lseek.2 6.3 (Berkeley) 2/24/86
|
|
.\"
|
|
.TH LSEEK 2 "February 24, 1986"
|
|
.UC 4
|
|
.SH NAME
|
|
lseek \- move read/write pointer
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <sys/types.h>
|
|
#include <unistd.h>
|
|
|
|
.ta +1.8i +0.6i
|
|
#define SEEK_SET 0 /* offset is absolute */
|
|
#define SEEK_CUR 1 /* relative to current position */
|
|
#define SEEK_END 2 /* relative to end of file */
|
|
|
|
off_t lseek(int d, off_t offset, int whence)
|
|
.fi
|
|
.ft R
|
|
.SH DESCRIPTION
|
|
The descriptor
|
|
.I d
|
|
refers to a file or device open for reading and/or writing.
|
|
.B Lseek
|
|
sets the file pointer of
|
|
.I d
|
|
as follows:
|
|
.IP
|
|
If
|
|
.I whence
|
|
is SEEK_SET, the pointer is set to
|
|
.I offset
|
|
bytes.
|
|
.IP
|
|
If
|
|
.I whence
|
|
is SEEK_CUR, the pointer is set to its current location plus
|
|
.IR offset .
|
|
.IP
|
|
If
|
|
.I whence
|
|
is SEEK_END, the pointer is set to the size of the
|
|
file plus
|
|
.IR offset .
|
|
.PP
|
|
Upon successful completion, the resulting pointer location
|
|
as measured in bytes from beginning of the file is returned.
|
|
Some devices are incapable of seeking. The value of the pointer
|
|
associated with such a device is undefined.
|
|
.SH NOTES
|
|
Seeking far beyond the end of a file, then writing,
|
|
creates a gap or \*(lqhole\*(rq, which occupies no
|
|
physical space and reads as zeros.
|
|
.SH "RETURN VALUE
|
|
Upon successful completion,
|
|
the current file pointer value is returned.
|
|
Otherwise,
|
|
a value of \-1 is returned and \fBerrno\fP is set to indicate
|
|
the error.
|
|
.SH "ERRORS
|
|
.B Lseek
|
|
will fail and the file pointer will remain unchanged if:
|
|
.TP 15
|
|
[EBADF]
|
|
.I Fildes
|
|
is not an open file descriptor.
|
|
.TP 15
|
|
[ESPIPE]
|
|
.I Fildes
|
|
is associated with a pipe or a socket.
|
|
.TP 15
|
|
[EINVAL]
|
|
.I Whence
|
|
is not a proper value.
|
|
.SH "SEE ALSO"
|
|
.BR fcntl (2),
|
|
.BR open (2).
|
|
.SH BUGS
|
|
This document's use of
|
|
.I whence
|
|
is incorrect English, but maintained for historical reasons.
|