LDP: Update original to LDP v3.79

[linuxjm/LDP_man-pages.git] / original / man2 / lseek.2

diff --git a/original/man2/lseek.2 b/original/man2/lseek.2
index 9a59fa6..eb83e37 100644 (file)
--- a/original/man2/lseek.2
+++ b/original/man2/lseek.2
@@ -3,6 +3,7 @@
 .\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com>
 .\" All rights reserved.
 .\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -30,6 +31,7 @@
 .\" 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.
+.\" %%%LICENSE_END
 .\"
 .\"     @(#)lseek.2    6.5 (Berkeley) 3/10/91
 .\"
@@ -42,7 +44,7 @@
 .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
 .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE
 .\"
-.TH LSEEK 2 2011-09-20 "Linux" "Linux Programmer's Manual"
+.TH LSEEK 2 2014-06-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
 lseek \- reposition read/write file offset
 .SH SYNOPSIS
@@ -128,19 +130,18 @@ if they have a mechanism for discovering holes.
 
 For the purposes of these operations, a hole is a sequence of zeros that
 (normally) has not been allocated in the underlying file storage.
-However, a file system is not obliged to report holes,
+However, a filesystem is not obliged to report holes,
 so these operations are not a guaranteed mechanism for
 mapping the storage space actually allocated to a file.
 (Furthermore, a sequence of zeros that actually has been written
 to the underlying storage may not be reported as a hole.)
 In the simplest implementation,
-a file system can support the operations by making
+a filesystem can support the operations by making
 .BR SEEK_HOLE
 always return the offset of the end of the file,
 and making
 .BR SEEK_DATA
 always return
-return
 .IR offset
 (i.e., even if the location referred to by
 .I offset
@@ -149,7 +150,33 @@ it can be considered to consist of data that is a sequence of zeros).
 .\" https://lkml.org/lkml/2011/4/22/79
 .\" http://lwn.net/Articles/440255/
 .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
-.SH "RETURN VALUE"
+
+The
+.BR _GNU_SOURCE
+feature test macro must be defined in order to obtain the definitions of
+.BR SEEK_DATA
+and
+.BR SEEK_HOLE
+from
+.IR <unistd.h> .
+
+The
+.BR SEEK_HOLE
+and
+.BR SEEK_DATA
+operations are supported for the following filesystems:
+.IP * 3
+Btrfs (since Linux 3.1)
+.IP * 3
+OCFS (since Linux 3.2)
+.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1
+.IP *
+XFS (since Linux 3.5)
+.IP *
+ext4 (since Linux 3.8)
+.IP *
+tmpfs (since Linux 3.8)
+.SH RETURN VALUE
 Upon successful completion,
 .BR lseek ()
 returns the resulting offset location as measured in bytes from the
@@ -169,7 +196,7 @@ is not valid.
 Or: the resulting file offset would be negative,
 or beyond the end of a seekable device.
 .\" Some systems may allow negative offsets for character devices
-.\" and/or for remote file systems.
+.\" and/or for remote filesystems.
 .TP
 .B EOVERFLOW
 .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
@@ -187,23 +214,29 @@ is
 or
 .BR SEEK_HOLE ,
 and the current file offset is beyond the end of the file.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 SVr4, 4.3BSD, POSIX.1-2001.
 
 .BR SEEK_DATA
 and
 .BR SEEK_HOLE
-are nonstandard extensions also present in Solaris;
+are nonstandard extensions also present in Solaris,
+FreeBSD, and DragonFly BSD;
 they are proposed for inclusion in the next POSIX revision (Issue 8).
 .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future
 .SH NOTES
+See
+.BR open (2)
+for a discussion of the relationship between file descriptors,
+open file descriptions, and files.
+
 Some devices are incapable of seeking and POSIX does not specify which
 devices must support
 .BR lseek ().
 
 On Linux, using
 .BR lseek ()
-on a tty device returns
+on a terminal device returns
 \fBESPIPE\fP.
 .\" Other systems return the number of written characters,
 .\" using SEEK_SET to set the counter. (Of written characters.)
@@ -231,10 +264,19 @@ or
 .BR fork (2)
 share the current file position pointer, so seeking on such files may be
 subject to race conditions.
-.SH "SEE ALSO"
+.SH SEE ALSO
 .BR dup (2),
 .BR fork (2),
 .BR open (2),
 .BR fseek (3),
 .BR lseek64 (3),
 .BR posix_fallocate (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.