svn commit: r363370 - stable/12/lib/libc/sys
Gordon Bergling
gbe at FreeBSD.org
Mon Jul 20 16:48:47 UTC 2020
Author: gbe (doc committer)
Date: Mon Jul 20 16:48:46 2020
New Revision: 363370
URL: https://svnweb.freebsd.org/changeset/base/363370
Log:
MFC r363156: lseek(2): Document the seek behavior better and update the POSIX compliance
PR: 162765
Submitted by: arundel@
Reported by: arundel@
Reviewed by: bcr (mentor)
Approved by: bcr (mentor)
MFC after: 1 week
Differential Revision: https://reviews.freebsd.org/D25646
Modified:
stable/12/lib/libc/sys/lseek.2
Directory Properties:
stable/12/ (props changed)
Modified: stable/12/lib/libc/sys/lseek.2
==============================================================================
--- stable/12/lib/libc/sys/lseek.2 Mon Jul 20 16:45:44 2020 (r363369)
+++ stable/12/lib/libc/sys/lseek.2 Mon Jul 20 16:48:46 2020 (r363370)
@@ -28,7 +28,7 @@
.\" @(#)lseek.2 8.3 (Berkeley) 4/19/94
.\" $FreeBSD$
.\"
-.Dd February 18, 2016
+.Dd July 13, 2020
.Dt LSEEK 2
.Os
.Sh NAME
@@ -113,11 +113,10 @@ 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).
+However, the
+.Fn lseek
+system call does not, by itself, extend the size of a file.
.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
@@ -205,13 +204,43 @@ is associated with a pipe, socket, or FIFO.
The
.Fn lseek
system call is expected to conform to
-.St -p1003.1-90 .
+.St -p1003.1-2008 .
+.Pp
+The
+.Dv SEEK_HOLE
+and
+.Dv SEEK_DATA
+directives, along with the
+.Er ENXIO
+error, are extensions to that specification.
.Sh HISTORY
The
.Fn lseek
function appeared in
.At v7 .
.Sh BUGS
+If the
+.Fn lseek
+system call is operating on a device which is incapable of seeking,
+it will request the seek operation and return successfully,
+even though no seek was performed.
+Because the
+.Ar offset
+argument will be stored unconditionally in the file descriptor of that device,
+there is no way to confirm if the seek operation succeeded or not
+(e.g. using the
+.Fn ftell
+function).
+Device types which are known to be incapable of seeking include
+tape drives.
+.Pp
+The
+.Fn lseek
+system call will not detect whether media are present in changeable
+media devices such as DVD or Blu-ray devices.
+A requested seek operation will therefore return sucessfully when no
+medium is present.
+.Pp
This document's use of
.Fa whence
is incorrect English, but is maintained for historical reasons.
More information about the svn-src-all
mailing list