Re: fallocate() man page

[Michael Kerrisk <mtk-manpages@gmx.net>]

Hello Amit.

> On Mon, Jul 23, 2007 at 08:09:45AM +0200, Michael Kerrisk wrote:
>> Amit,
>>
>> I've taken the page that you sent and made various minor formatting and
>> wording fixes.  I've also added various FIXMEs to the page.  Some of these
>> ("FIXME .") are things that I need to check up later.  Some others are
>> questions for which I need input from you, David, or someone else with the
>> relevant info (I've marked these "FIXME Amit:").  Could you please review,
>> and send a new draft of the page back to me.
> 
> Thanks for going through the manpage and improving it!
> 
> My comments are below in between <Amit> ... </Amit> tags.
> 
> Thanks!
[...]

> The
> .I mode
> argument determines the operation to be performed on the given range.
> Currently only one flag is supported for
> .IR mode :
> .TP
> .B FALLOC_FL_KEEP_SIZE
> allocates and initializes to zero the disk space within the given range.
> .\" FIXME Amit: The next two sentences seem to contradict
> .\" each other somewhat.  On the one hand, later writes
> .\" are guaranteed not to fail for lack of space; on the other
> .\" hand, the file size id not changed even if it is currently
> .\" smaller than offset+len bytes.
> .\" Could you explain this a little further.  (E.g., how does
> .\" the kernel guarantee space without changing the size
> .\" of the file?)
> .\" <Amit>
> .\"     Well, this is a feature where you can allocate/reserve space for
> .\" a file without changing the file size. This is done by allocating blocks
> .\" to the file, but still not changing the size. As mentioned below, this
> .\" helps applications that use append mode a lot. These can open
> .\" a file in append mode and start writing to "preallocated" space.
> .\" So, if someone does a stat on a file after fallocate() with this mode (where
> .\" file size is not changed), he/she will see that the st_blocks
> .\" increased, but st_size did not change.
> .\" </Amit>

Okay -- I tried rewording the text here a little to make this clearer.  Can
you review the new version to see that it's okay.

[...]

> .\" FIXME Amit: Which other flags are likely to appear
> .\" for mode, and in which kernel version are they likely?
> .\" <Amit>
> .\"    There were few more flags which were discussed, but none of
> .\" them have been finalized upon. Here are these flags:
> .\" FA_FL_DEALLOC, FA_FL_DEL_DATA, FA_FL_ERR_FREE, FA_FL_NO_MTIME, FA_FL_NO_CTIME
> .\" All of the above flags were debated upon and we can not say if any/which one
> .\" of these flags will make it to the later kernels.
> .\" </Amit>

Thanks for the info.

[...]

> .\" FIXME Amit: is it worth adding a few words to the following
> .\" sentence to say why fallocate() may allocate a larger range
> .\" than specified?
> .\" <Amit>
> .\"     The preallocation is done in block size chunks. Thus, if the last
> .\" few bytes in the range falls in a new block, this entire block gets
> .\" allocated to the file. Hence we may have slightly larger range allocated.
> .\" I have tried to add one line to explain this below. Please see if it
> .\" makes sense and is understandable. Thanks!
> .\" </Amit>

Thanks.

> .PP
> .BR fallocate ()
> may allocate a larger range than that was specified.
> .\" <Amit>
> .\" This is because allocation is done in block size chunks and hence
> .\" the allocation will automatically get block aligned.
> .\" </Amit>

I made the sentence:

    Because allocation is done in block size chunks, fallocate()
    may allocate a larger range than that which was specified.

okay?

[...]

> .TP
> .B ENODEV
> .I fd
> does not refer to a regular file or a directory.
> .TP
> .B ENOSPC
> There is not enough space left on the device containing the file
> referred to by
> .IR fd .
> .TP
> .B ESPIPE
> .I fd
> refers to a pipe of file descriptor.
> .\" FIXME Amit: ENODEV says "fd is not a file or a directory";
> .\" ESPIPE says (I had to fix the text a little) "refers to a pipe".
> .\" This doesn't make sense: if fd is a pipe, then either one
> .\" of these errors could occur.  Which is it supposed to be?
> .\" <Amit>
> .\"    This is inline with posix_fallocate manpage. If it is a pipe,
> .\" user will get ESPIPE.
> .\" </Amit>

Okay -- thanks.  I reworded the text for the ESNODEV error to make this
clearer.  (Please check the wording in the next draft.)

By the way in fs/open.c I see the comment:

        /*
         * Let individual file system decide if it supports preallocation
         * for directories or not.
         */
        if (!S_ISREG(inode->i_mode) && !S_ISDIR(inode->i_mode))
                goto out_fput;

But that comment doesn't seem to accord with the line of code immediately
below it (S_ISDIR() check is doene regardles of file system type).  Do I
misunderstand something -- or is the comment wrong?

[...]

> .TP
> .B EOPNOTSUPP
> .\" FIXME Amit: can you say a little more about the following error
> .\" <Amit>
> .\" How does following sound ?
> .\" 'The specified mode is not supported on the object by the file system.'
> .\" </Amit>

I made it:

    The mode is not supported by the file system containing the file
    referred to by fd.

Okay?

[...]

New version of the page on its way soon.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.