posix_fallocate.3: add note about error codes for musl.

Submitted by Érico Rolim on Sept. 13, 2020, 8:06 a.m.

Details

Message ID CAFDeuWPmWWHatxnZ9HsYN2fp3gagHOKCsKmVDj0F6us9XWKwFQ@mail.gmail.com
State New
Series "posix_fallocate.3: add note about error codes for musl."
Headers show

Commit Message

Érico Rolim Sept. 13, 2020, 8:06 a.m.
As can be seen in

https://git.musl-libc.org/cgit/musl/tree/src/fcntl/posix_fallocate.c?id=73cc775bee53300c7cf759f37580220b18ac13d3

musl returns the syscall's errors directly, which means it doesn't
perform the same emulation as glibc, and, more relevant to this change,
it can return more errors than the ones currently listed in ERRORS.
---
 man3/posix_fallocate.3 | 4 ++++
 1 file changed, 4 insertions(+)

Patch hide | download patch | download mbox

diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3
index 58338d673..2e440b3e1 100644
--- a/man3/posix_fallocate.3
+++ b/man3/posix_fallocate.3
@@ -101,6 +101,10 @@  referred to by
 .B ESPIPE
 .I fd
 refers to a pipe.
+.TP
+Libraries that don't perform the emulation shown in NOTES, such as musl libc,
+may also return the error codes listed in
+.BR fallocate (2).
 .SH VERSIONS
 .BR posix_fallocate ()
 is available since glibc 2.1.94.

Comments

Rich Felker Sept. 13, 2020, 2:18 p.m.
On Sun, Sep 13, 2020 at 05:06:25AM -0300, Érico Rolim wrote:
> As can be seen in
> 
> https://git.musl-libc.org/cgit/musl/tree/src/fcntl/posix_fallocate.c?id=73cc775bee53300c7cf759f37580220b18ac13d3
> 
> musl returns the syscall's errors directly, which means it doesn't
> perform the same emulation as glibc, and, more relevant to this change,
> it can return more errors than the ones currently listed in ERRORS.
> ---
>  man3/posix_fallocate.3 | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3
> index 58338d673..2e440b3e1 100644
> --- a/man3/posix_fallocate.3
> +++ b/man3/posix_fallocate.3
> @@ -101,6 +101,10 @@ referred to by
>  .B ESPIPE
>  .I fd
>  refers to a pipe.
> +.TP
> +Libraries that don't perform the emulation shown in NOTES, such as musl libc,
> +may also return the error codes listed in
> +.BR fallocate (2).
>  .SH VERSIONS
>  .BR posix_fallocate ()
>  is available since glibc 2.1.94.
> -- 
> 2.28.0

I think this should be documented the other way around -- adding
EOPNOTSUPP to the list of errors, with a note that applications may
not see the error due to emulation by glibc, but should be prepared to
handle it. The emulation glibc does is highly unsafe (can corrupt the
file -- see https://sourceware.org/bugzilla/show_bug.cgi?id=15661) and
the only reason it wasn't removed was that software had come to rely
on it being there, in part due to lack of documentation otherwise. If
that's fixed, it's possible that glibc could eventually fix this bug
with a new symbol version.

Rich