From owner-freebsd-standards@FreeBSD.ORG Thu Jan 23 15:09:10 2014 Return-Path: Delivered-To: standards@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 10C705D9; Thu, 23 Jan 2014 15:09:10 +0000 (UTC) Received: from mail105.syd.optusnet.com.au (mail105.syd.optusnet.com.au [211.29.132.249]) by mx1.freebsd.org (Postfix) with ESMTP id 96240174F; Thu, 23 Jan 2014 15:09:09 +0000 (UTC) Received: from c122-106-144-87.carlnfd1.nsw.optusnet.com.au (c122-106-144-87.carlnfd1.nsw.optusnet.com.au [122.106.144.87]) by mail105.syd.optusnet.com.au (Postfix) with ESMTPS id 92EBE10408B6; Fri, 24 Jan 2014 02:08:59 +1100 (EST) Date: Fri, 24 Jan 2014 02:08:54 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Konstantin Belousov Subject: Re: standards/186028: incorrect return values for posix_fallocate() In-Reply-To: <20140123094017.GH24664@kib.kiev.ua> Message-ID: <20140124014043.T879@besplex.bde.org> References: <201401230858.s0N8wwQB039907@oldred.freebsd.org> <20140123094017.GH24664@kib.kiev.ua> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=Wu4Sb7vv c=1 sm=1 tr=0 a=p/w0leo876FR0WNmYI1KeA==:117 a=PO7r1zJSAAAA:8 a=1FcmvNfKhqQA:10 a=kj9zAlcOel0A:10 a=JzwRw_2MAAAA:8 a=3BHb2PuD7wgA:10 a=eKQI6xHjb1eDkzikO7sA:9 a=QAnm8XVNnMn8zPeX:21 a=cVWQ5MPqDhCTD4Dt:21 a=CjuIK1q_8ugA:10 Cc: Gennady Proskurin , mdf@FreeBSD.org, standards@FreeBSD.org X-BeenThere: freebsd-standards@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Standards compliance List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 23 Jan 2014 15:09:10 -0000 On Thu, 23 Jan 2014, Konstantin Belousov wrote: > Indeed. Linux also seems to have the conforming behaviour, according > to their man page, which also explicitely states that errno is not set. > > Try this. > > diff --git a/lib/libc/sys/posix_fallocate.2 b/lib/libc/sys/posix_fallocate.2 > index 087c68c..ee6fcc4 100644 > --- a/lib/libc/sys/posix_fallocate.2 > +++ b/lib/libc/sys/posix_fallocate.2 > @@ -83,9 +83,9 @@ that reduces the file size to a size smaller than > If successful, > .Fn posix_fallocate > returns zero. > -It returns -1 on failure, and sets > +It returns error on failure, without setting > .Va errno > -to indicate the error. > +variable. "returns error" is hard to parse. Only values can be returned. The old text would have had a style bug if it had been correct. Normal man pages use the mdoc markup ".Rv -std" instead of repeating the above boilerplate ad nauseum to describe standard error handling. In libc/sys, the macro is used in 106 man pages and the style bug is used in about 50 man pages. > .Sh ERRORS > Possible failure conditions: This section is not quite so hard to parse. It uses standard wording except for the above clause. The standard wording is adapted to returning the error code in errno. Only the above clause gives a different meaning to the markup of error codes, and it is incomplete for that. The standard wording seems to be broken too. The markup should be described in somewhere like intro(2) or errno(2) (errno(2) is just a link to intro(2)), but these man pages don't even contain a markup chracter. The markup is that square brackets around an error number EFOO normally mean that: - when the function fails for the reason given by the description at the right of [EFOO], then errno is set to EFOO This only applies for standard error handling. For posix_fallocate(), [EFOO] now means that EFOO is returned on failure under the condition described to the right of it. If [EFOO] were actually documented, then its documention would probably only apply to standard error handling so would become wrong when the markup is abused for something else. POSIX uses the following wording (in a 2001 draft): % 28228 RETURN VALUE % 28229 Upon successful completion, posix_fallocate( ) shall return zero; otherwise, an error number shall % 28230 be returned to indicate the error. This is OK. % 28231 ERRORS % 28232 The posix_fallocate( ) function shall fail if: % 28233 [EBADF] The fd argument is not a valid file descriptor. % ... This is more broken than in FreeBSD, because there is no extra clause to give a hint that the standard meaning doesn't apply. I couldn't find where POSIX defines the markup for errno numbers. It formally defines 'Brackets'. I could find where it formally defines the markup for limits. It is sloppy and uses the markup before defining it even for limits. C99 doesn't use any markup for errno numbers, but laboriously describes the setting of errno using English sentences. This is not too bad since C99 has a whole 3 error numbers (EDOM, ERANGE, and the newfangled EILSEQ) and most of its functions don't set errno. Bruce