From e7677232d6eed5f5cae80c1d5968eea5b9266b59 Mon Sep 17 00:00:00 2001
From: Gordon Bergling <gbe@FreeBSD.org>
Date: Mon, 13 Jul 2020 15:52:57 +0000
Subject: [PATCH] lseek(2): Document the seek behavior better and update the
 POSIX compliance

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
---
 lib/libc/sys/lseek.2 | 41 +++++++++++++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2
index 6c6c721990c8..57cb11af2e79 100644
--- a/lib/libc/sys/lseek.2
+++ b/lib/libc/sys/lseek.2
@@ -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.