d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

lseek(2): Document the seek behavior better and update the POSIX compliance

Browse Source 
In certain situations lseek(2) will return successful although if no seek
was performed. This can happen when operating on devices that don't support
seeking (older tape drives) or when operating on changeable media devices
(such as DVD or Blu-ray devices) without a medium inserted.

Document this within the man page and update the POSIX compliance while here.

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
This commit is contained in:
Gordon Bergling 2020-07-13 15:52:57 +00:00
parent e4d47f45eb
commit e7677232d6
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=363156
1 changed files with 35 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
lib/libc/sys/lseek.2
View File

@ -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,10 +113,9 @@ 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.
However, the
.Fn lseek
system call does not, by itself, extend the size of a file.
.Pp
A
.Qq hole
@ -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.