Date: Fri, 24 Jan 2014 02:08:54 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Konstantin Belousov <kostikbel@gmail.com> Cc: Gennady Proskurin <gpr@mail.ru>, mdf@FreeBSD.org, standards@FreeBSD.org Subject: Re: standards/186028: incorrect return values for posix_fallocate() Message-ID: <20140124014043.T879@besplex.bde.org> In-Reply-To: <20140123094017.GH24664@kib.kiev.ua> References: <201401230858.s0N8wwQB039907@oldred.freebsd.org> <20140123094017.GH24664@kib.kiev.ua>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20140124014043.T879>