From owner-svn-src-head@freebsd.org Thu Feb 18 18:41:41 2016 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id C3AD1AAD495; Thu, 18 Feb 2016 18:41:41 +0000 (UTC) (envelope-from sobomax@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 mx1.freebsd.org (Postfix) with ESMTPS id 7C6081A90; Thu, 18 Feb 2016 18:41:41 +0000 (UTC) (envelope-from sobomax@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u1IIfexR065888; Thu, 18 Feb 2016 18:41:40 GMT (envelope-from sobomax@FreeBSD.org) Received: (from sobomax@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u1IIfe5Q065887; Thu, 18 Feb 2016 18:41:40 GMT (envelope-from sobomax@FreeBSD.org) Message-Id: <201602181841.u1IIfe5Q065887@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: sobomax set sender to sobomax@FreeBSD.org using -f From: Maxim Sobolev Date: Thu, 18 Feb 2016 18:41:40 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r295764 - head/lib/libc/sys X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 18 Feb 2016 18:41:41 -0000 Author: sobomax Date: Thu Feb 18 18:41:40 2016 New Revision: 295764 URL: https://svnweb.freebsd.org/changeset/base/295764 Log: Right now, the "virtual hole" API feature of lseek(2) is very vaguely documented and easy to miss. At the same time, it's pretty important for anyone who is trying to use SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that description more pronounced and also document how it affects failure codes. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D5162 Modified: head/lib/libc/sys/lseek.2 Modified: head/lib/libc/sys/lseek.2 ============================================================================== --- head/lib/libc/sys/lseek.2 Thu Feb 18 17:09:55 2016 (r295763) +++ head/lib/libc/sys/lseek.2 Thu Feb 18 18:41:40 2016 (r295764) @@ -131,8 +131,14 @@ Applications can use .Dv SEEK_HOLE to optimise their behavior for ranges of zeros, but must not depend on it to find all such ranges in a file. +Each file is presented as having a zero-size virtual hole at the very +end of the file. The existence of a hole at the end of every data region allows for easy -programming and implies that a virtual hole exists at the end of the file. +programming and also provides compatibility to the original imlementation +in Solaris. +It also causes the current file size (i.e. end-of-file offset) to be returned +to indicate that there are no more holes past the supplied +.Fa offset . Applications should use .Fn fpathconf _PC_MIN_HOLE_SIZE or @@ -176,9 +182,11 @@ be negative for a non-character special For .Dv SEEK_DATA , there are no more data regions past the supplied offset. -For -.Dv SEEK_HOLE , -there are no more holes past the supplied offset. +Due to existence of the hole at the end of the file, for +.Dv SEEK_HOLE +this error is only returned when the +.Fa offset +already points to the end-of-file position. .It Bq Er EOVERFLOW The resulting file offset would be a value which cannot be represented correctly in an object of type