Bug 12919 - posix_fallocate: what if len == 0?
posix_fallocate: what if len == 0?
Status: RESOLVED CODE_FIX
Product: Documentation
Classification: Unclassified
Component: man-pages
All Linux
: P1 low
Assigned To: documentation_man-pages@kernel-bugs.osdl.org
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2009-03-22 11:51 UTC by Eelco Dolstra
Modified: 2010-08-30 14:31 UTC (History)
1 user (show)

See Also:
Kernel Version: 2.6.28.4
Tree: Mainline
Regression: No


Attachments

Description Eelco Dolstra 2009-03-22 11:51:00 UTC
Hi,

I noticed the following in the manpage for posix_fallocate.  It currently (in man-pages 3.19) says under "Errors":

  EINVAL  offset or len was less than 0.

However, the Linux kernel also returns EINVAL if len is *equal* to 0.  (See fallocate() in http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=fs/open.c;hb=HEAD).  This follows IEEE Std 1003.1-2001, which says (http://www.opengroup.org/onlinepubs/009695399/functions/posix_fallocate.html):

[EINVAL]
    The len argument was zero or the offset argument was less than zero.

(Interestingly, this doesn't mention what should happen if len is negative...)

However POSIX.1-2008 says (http://www.opengroup.org/onlinepubs/9699919799/functions/posix_fallocate.html):

[EINVAL]
    The len argument is less than zero, or the offset argument is less than    zero, or the underlying file system does not support this operation.

Thus the manpage should probably be updated to reflect that you cannot rely on len being allowed to be 0 in portable code.
Comment 1 Michael Kerrisk 2009-03-30 01:20:18 UTC
(In reply to comment #0)

Hi,

Thanks for the great supporting info on this bug report.

> Hi,
> I noticed the following in the manpage for posix_fallocate.  It currently (in
> man-pages 3.19) says under "Errors":
>   EINVAL  offset or len was less than 0.
> However, the Linux kernel also returns EINVAL if len is *equal* to 0.  (See
> fallocate() in
> http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=fs/open.c;hb=HEAD).
>  This follows IEEE Std 1003.1-2001, which says
> (http://www.opengroup.org/onlinepubs/009695399/functions/posix_fallocate.html):
> [EINVAL]
>     The len argument was zero or the offset argument was less than zero.
> (Interestingly, this doesn't mention what should happen if len is negative...)
> However POSIX.1-2008 says
> (http://www.opengroup.org/onlinepubs/9699919799/functions/posix_fallocate.html):
> [EINVAL]
>     The len argument is less than zero, or the offset argument is less than   
> zero, or the underlying file system does not support this operation.
> Thus the manpage should probably be updated to reflect that you cannot rely on
> len being allowed to be 0 in portable code.

For man-pages-3.20, I added the words "or equal" when talking about 'len;under teh EINVAL description.  I also added text under CONFORMING TO describing the POSIX.1-* specifications for the EINVAL error.

Cheers,

Michael

PS See also:
https://www.opengroup.org/austin/interps/uploads/40/14574/AI-162.txt

Note You need to log in before you can comment on or make changes to this bug.