From owner-svn-src-all@freebsd.org Mon Jul 13 15:52:58 2020 Return-Path: Delivered-To: svn-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id A20CB367E30; Mon, 13 Jul 2020 15:52:58 +0000 (UTC) (envelope-from gbe@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4B57TQ3qklz472f; Mon, 13 Jul 2020 15:52:58 +0000 (UTC) (envelope-from gbe@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 66B3217BD9; Mon, 13 Jul 2020 15:52:58 +0000 (UTC) (envelope-from gbe@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 06DFqwcU034047; Mon, 13 Jul 2020 15:52:58 GMT (envelope-from gbe@FreeBSD.org) Received: (from gbe@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 06DFqwoq034046; Mon, 13 Jul 2020 15:52:58 GMT (envelope-from gbe@FreeBSD.org) Message-Id: <202007131552.06DFqwoq034046@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: gbe set sender to gbe@FreeBSD.org using -f From: Gordon Bergling Date: Mon, 13 Jul 2020 15:52:58 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r363156 - head/lib/libc/sys X-SVN-Group: head X-SVN-Commit-Author: gbe X-SVN-Commit-Paths: head/lib/libc/sys X-SVN-Commit-Revision: 363156 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 13 Jul 2020 15:52:58 -0000 Author: gbe (doc committer) Date: Mon Jul 13 15:52:57 2020 New Revision: 363156 URL: https://svnweb.freebsd.org/changeset/base/363156 Log: 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 Modified: head/lib/libc/sys/lseek.2 Modified: head/lib/libc/sys/lseek.2 ============================================================================== --- head/lib/libc/sys/lseek.2 Mon Jul 13 15:41:55 2020 (r363155) +++ head/lib/libc/sys/lseek.2 Mon Jul 13 15:52:57 2020 (r363156) @@ -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.