xnu-6153.11.26.tar.gz

[apple/xnu.git] / bsd / man / man2 / lseek.2

diff --git a/bsd/man/man2/lseek.2 b/bsd/man/man2/lseek.2
index 09374f7641927970f9440811be68aeaf83d64e0b..d5bea0b6220e716127a36a38bd51ed87b68fc0da 100644 (file)
--- a/bsd/man/man2/lseek.2
+++ b/bsd/man/man2/lseek.2
@@ -42,7 +42,11 @@
 .Sh SYNOPSIS
 .Fd #include <unistd.h>
 .Ft off_t
-.Fn lseek "int fildes" "off_t offset" "int whence"
+.Fo lseek
+.Fa "int fildes"
+.Fa "off_t offset"
+.Fa "int whence"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn lseek
@@ -50,14 +54,14 @@ function repositions the offset of the file descriptor
 .Fa fildes
 to the
 argument
-.Fa offset
+.Fa offset ,
 according to the directive
-.Fa whence.
+.Fa whence .
 The argument
 .Fa fildes
 must be an open
 file descriptor.
-.Fn Lseek
+.Fn lseek
 repositions the file pointer
 .Fa fildes
 as follows:
@@ -87,6 +91,23 @@ the offset is set to the size of the
 file plus
 .Fa offset
 bytes.
+.It
+If
+.Fa whence
+is
+.Dv SEEK_HOLE ,
+the offset is set to the start of the next hole greater than or equal
+to the supplied
+.Fa offset .
+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
@@ -98,6 +119,39 @@ 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.
+Each file is presented as having a zero-size virtual hole at the very
+end of the file.
+The existence of a hole at the end of every data region allows for easy
+programming and also provides compatibility to the original implementation
+in Solaris.
+It also causes the current file size (i.e., end-of-file offset) to be returned
+to indicate that there are no more holes past the supplied
+.Fa offset .
+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
@@ -109,18 +163,41 @@ a value of -1 is returned and
 is set to indicate
 the error.
 .Sh ERRORS
-.Fn Lseek
+.Fn lseek
 will fail and the file pointer will remain unchanged if:
 .Bl -tag -width Er
+.\" ==========
 .It Bq Er EBADF
 .Em Fildes
 is not an open file descriptor.
-.It Bq Er ESPIPE
-.Em Fildes
-is associated with a pipe, socket, or FIFO.
+.\" ==========
 .It Bq Er EINVAL
 .Fa Whence
 is not a proper value.
+.\" ==========
+.It Bq Er EINVAL
+The seek location (calculated from
+.Fa offset
+and
+.Fa whence )
+is negative.
+.\" ==========
+.It Bq Er ENXIO
+For
+.Dv SEEK_DATA ,
+there are no more data regions past the supplied offset.
+Due to existence of the hole at the end of the file, for
+.Dv SEEK_HOLE
+this error is only returned when the
+.Fa offset
+already points to the end-of-file position.
+.It Bq Er EOVERFLOW
+The seek location is too large to be stored
+in an object of type off_t.
+.\" ==========
+.It Bq Er ESPIPE
+.Em Fildes
+is associated with a pipe, socket, or FIFO.
 .El
 .Sh SEE ALSO
 .Xr dup 2 ,