From owner-cvs-all@FreeBSD.ORG Thu Jun 1 15:11:23 2006 Return-Path: X-Original-To: cvs-all@freebsd.org Delivered-To: cvs-all@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id F3B5316ABA0; Thu, 1 Jun 2006 15:11:22 +0000 (UTC) (envelope-from bde@zeta.org.au) Received: from mailout1.pacific.net.au (mailout1.pacific.net.au [61.8.0.84]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6320743D7B; Thu, 1 Jun 2006 15:11:14 +0000 (GMT) (envelope-from bde@zeta.org.au) Received: from mailproxy1.pacific.net.au (mailproxy1.pacific.net.au [61.8.0.86]) by mailout1.pacific.net.au (Postfix) with ESMTP id ED60B3A7C03; Fri, 2 Jun 2006 01:11:12 +1000 (EST) Received: from katana.zip.com.au (katana.zip.com.au [61.8.7.246]) by mailproxy1.pacific.net.au (8.13.4/8.13.4/Debian-3sarge1) with ESMTP id k51FB90h005342; Fri, 2 Jun 2006 01:11:10 +1000 Date: Fri, 2 Jun 2006 01:11:09 +1000 (EST) From: Bruce Evans X-X-Sender: bde@delplex.bde.org To: Ceri Davies In-Reply-To: <20060601094950.GU21998@submonkey.net> Message-ID: <20060602000029.C34374@delplex.bde.org> References: <200605311315.k4VDFUhD093628@repoman.freebsd.org> <20060601023523.GA80617@wantadilla.lemis.com> <20060601094950.GU21998@submonkey.net> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: Greg 'groggy' Lehey , Maxim Konovalov , src-committers@freebsd.org, cvs-all@freebsd.org, cvs-src@freebsd.org Subject: Re: cvs commit: src/sys/ufs/ufs ufs_vnops.c X-BeenThere: cvs-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 Jun 2006 15:11:24 -0000 On Thu, 1 Jun 2006, Ceri Davies wrote: > On Thu, Jun 01, 2006 at 12:05:23PM +0930, Greg 'groggy' Lehey wrote: >> On Wednesday, 31 May 2006 at 13:15:29 +0000, Maxim Konovalov wrote: >>> maxim 2006-05-31 13:15:29 UTC >>> >>> FreeBSD src repository >>> >>> Modified files: >>> sys/ufs/ufs ufs_vnops.c >>> Log: >>> o According to POSIX, the result of ftruncate(2) is unspecified >>> for file types other than VREG, VDIR and shared memory objects. >>> We already handle VREG, VLNK and VDIR cases. Silently ignore >>> >>> Revision Changes Path >>> 1.276 +22 -4 src/sys/ufs/ufs/ufs_vnops.c >> >> Is this worth a man page update? Only to the extent that the man page is generally broken. It has always tried to document the behaviour now implemented in ffs but it omits some details and is not clear on the [EROFS] case. The commit makes the man page actually agree with one file system (ffs; file systems cut and pasted from ffs, e.g., ext2fs, still panic). > Undoubtedly. Does the attached look like enough? I'm not sure if we Sorry, no. > want to add a STANDARDS section for this when it's valid behaviour. > Index: src/lib/libc/sys/truncate.2 > =================================================================== > RCS file: /home/ncvs/src/lib/libc/sys/truncate.2,v > retrieving revision 1.17 > diff -u -r1.17 truncate.2 > --- src/lib/libc/sys/truncate.2 20 Jan 2005 09:17:05 -0000 1.17 > +++ src/lib/libc/sys/truncate.2 1 Jun 2006 09:47:19 -0000 > ... > @@ -69,6 +69,10 @@ > the file must be open for writing. > .Sh RETURN VALUES > .Rv -std > +If the file to be modified is not a directory or > +a regular file, the > +.Fn truncate > +call will return the value 0. > .Sh ERRORS > The > .Fn truncate The man page already says this (in standard wording in ".Rv -std" and ERRORS): % RETURN VALUES % Upon successful completion, the value 0 is returned; otherwise the ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ % value -1 is returned and the global variable errno is set to indicate the % error. % % ERRORS % The truncate() system call succeeds unless: ^^^^^^^^^^^^^^^ % [... various unrelated errors] % [EISDIR] The named file is a directory. This covers the behaviour for directories in more detail. % [EROFS] The named file resides on a read-only file system. I originally misinterpreted "resides" as strictly applying to the name of a fifo (since fifo contents don't really reside anywhere) but it obviously should only apply to the contents. open(2) uses the same wording. The actual behaviour was (and still is on some file systems containing code cut and pasted from ffs, e.g., ext2fs): - [f]truncate() of a fifo on a r/w file system (for ffs and clones) acts as if there were a resource fork of the file, with one half of the fork containing the fifo and the other half containing a irregular file, where an irregular file in this context is a regular file that is inaccessible from userland except via stat(2) and statfs(2) to see some of its side effects, and via unlink(2) to clean it up. This used to be a small problem. However, some versions of FreeBSD have debugging code that panics on attempts to truncate the irregular file. - I thinl [f]truncate() of a fifo on a r/o file system panics unless the new size is 0. % [... various unrelated errors] % % The ftruncate() system call succeeds unless: % % [EBADF] The fd argument is not a valid descriptor. % % [EINVAL] The fd argument references a socket, not a file. % % [EINVAL] The fd descriptor is not open for writing. Note that there is no !directory or r/o restrictions here. These restrictions are in in open(2). There is an additional restriction here for sockets. Either this or the lack of such a restriction for truncate(2) must be a bug, since sockets may be bound to file systems and whether truncation succeeds shouldn't depend on the syscall used to do it. % BUGS % ... % % Use of truncate() to extend a file is not portable. This can only be a bug in programs which assume that extension using [f]truncate() is portable, not in [f]truncate(). (File) extension is an XSI (specification) extension in POSIX. The main bugs here are: - truncate.2 doesn't say that except for regular files, success consists of doing nothing (even when the caller asks for something to be done). - truncate.2 doesn't say that for regular files, certain timestamps (mainly ctime) are set on successful completion (even when the caller asks for nothing to be done). It shares this bug with most or all FreeBSD man pages for fs syscalls. POSIX is much more careful about such details. POSIX may be harder to read because it is more formal, but when detail is just absent in an informal description it is impossible to recover from the description. Bruce