diff options
Diffstat (limited to 'lib/libc/sys/lseek.2')
-rw-r--r-- | lib/libc/sys/lseek.2 | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 new file mode 100644 index 0000000..874c523 --- /dev/null +++ b/lib/libc/sys/lseek.2 @@ -0,0 +1,209 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)lseek.2 8.3 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd April 5, 2007 +.Dt LSEEK 2 +.Os +.Sh NAME +.Nm lseek +.Nd reposition read/write file offset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft off_t +.Fn lseek "int fildes" "off_t offset" "int whence" +.Sh DESCRIPTION +The +.Fn lseek +system call repositions the offset of the file descriptor +.Fa fildes +to the +argument +.Fa offset +according to the directive +.Fa whence . +The argument +.Fa fildes +must be an open +file descriptor. +The +.Fn lseek +system call +repositions the file position pointer associated with the file +descriptor +.Fa fildes +as follows: +.Bl -item -offset indent +.It +If +.Fa whence +is +.Dv SEEK_SET , +the offset is set to +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_CUR , +the offset is set to its current location plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_END , +the offset is set to the size of the +file plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_HOLE , +the offset of the start of the next hole greater than or equal to the supplied +.Fa offset +is returned. +The definition of a hole is provided below. +.It +If +.Fa whence +is +.Dv SEEK_DATA , +the offset is set to the start of the next non-hole file region greater +than or equal to the supplied +.Fa offset . +.El +.Pp +The +.Fn lseek +system call allows the file offset to be set beyond the end +of the existing end-of-file of the file. +If data is later written +at this point, subsequent reads of the data in the gap return +bytes of zeros (until data is actually written into the gap). +.Pp +Some devices are incapable of seeking. +The value of the pointer +associated with such a device is undefined. +.Pp +A +.Qq hole +is defined as a contiguous range of bytes in a file, all having the value of +zero, but not all zeros in a file are guaranteed to be represented as holes +returned with +.Dv SEEK_HOLE . +File systems are allowed to expose ranges of zeros with +.Dv SEEK_HOLE , +but not required to. +Applications can use +.Dv SEEK_HOLE +to optimise their behavior for ranges of zeros, but must not depend on it to +find all such ranges in a file. +The existence of a hole at the end of every data region allows for easy +programming and implies that a virtual hole exists at the end of the file. +Applications should use +.Fn fpathconf _PC_MIN_HOLE_SIZE +or +.Fn pathconf _PC_MIN_HOLE_SIZE +to determine if a file system supports +.Dv SEEK_HOLE . +See +.Xr pathconf 2 . +.Pp +For file systems that do not supply information about holes, the file will be +represented as one entire data region. +.Sh RETURN VALUES +Upon successful completion, +.Fn lseek +returns the resulting offset location as measured in bytes from the +beginning of the file. +Otherwise, +a value of -1 is returned and +.Va errno +is set to indicate +the error. +.Sh ERRORS +The +.Fn lseek +system call +will fail and the file position pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument +is not an open file descriptor. +.It Bq Er EINVAL +The +.Fa whence +argument +is not a proper value +or the resulting file offset would +be negative for a non-character special file. +.It Bq Er ENXIO +For +.Dv SEEK_DATA , +there are no more data regions past the supplied offset. +For +.Dv SEEK_HOLE , +there are no more holes past the supplied offset. +.It Bq Er EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.Fa off_t . +.It Bq Er ESPIPE +The +.Fa fildes +argument +is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr open 2 , +.Xr pathconf 2 +.Sh STANDARDS +The +.Fn lseek +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn lseek +function appeared in +.At v7 . +.Sh BUGS +This document's use of +.Fa whence +is incorrect English, but is maintained for historical reasons. |