[PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Lukas Czerner]

FALLOC_FL_ZERO_RANGE was added in Linux 3.14,
for zeroing ranges in the allocated space in a file.

Signed-off-by: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
v2: Rebase and update the description
v3: Ext4 zero range on extent based files

 man2/fallocate.2 | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/man2/fallocate.2 b/man2/fallocate.2
index 73c4f12..0ffce71 100644
--- a/man2/fallocate.2
+++ b/man2/fallocate.2
@@ -180,6 +180,48 @@ ext4 (only for extent-based files)
 .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
 and XFS.
 .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
+.SS Zeroing file space
+Specifying
+.BR FALLOC_FL_ZERO_RANGE
+flag (available since Linux 3.14) in
+.I mode
+zeroes space in the byte range starting at
+.I offset
+and continuing for
+.I len
+bytes.
+Within the specified range, blocks are preallocated for the regions
+that span the holes in the file. After a successful call, subsequent
+reads from this range will return zeroes.
+
+Zeroing is done within the file system preferably by converting range into
+unwritten extents which requires very little IO to be issued mostly for
+metadata. This means that the range will not be physically zeroed out
+on the device.
+
+If the
+.B FALLOC_FL_KEEP_SIZE
+flag is specified in
+.IR mode ,
+the behavior of the call is similar,
+but the file size will not be changed even if
+.IR offset + len
+is greater than the file size. This behaviour is the same as when
+preallocating space with
+.B FALLOC_FL_KEEP_SIZE
+specified.
+
+Not all filesystems support
+.BR FALLOC_FL_ZERO_RANGE ;
+if a filesystem doesn't support the operation, an error is returned.
+The operation is supported on at least the following filesystems
+.IP * 3
+XFS (since Linux 3.14)
+.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
+.IP *
+ext4, for extent based files (since Linux 3.14)
+.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
+
 .SH RETURN VALUE
 On success,
 .BR fallocate ()
@@ -243,7 +285,9 @@ no other flags are permitted with
 .B EINVAL
 .I mode
 is
-.BR FALLOC_FL_COLLAPSE_RANGE ,
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_ZERO_RANGE,
 but the file referred to by
 .I fd
 is not a regular file.
-- 
1.8.3.1

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Michael Kerrisk (man-pages)]

On 05/05/2014 02:04 PM, Lukas Czerner wrote:
> FALLOC_FL_ZERO_RANGE was added in Linux 3.14,
> for zeroing ranges in the allocated space in a file.
> 
> Signed-off-by: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
> v2: Rebase and update the description
> v3: Ext4 zero range on extent based files

Thank, Lukáš.

In fact I'd already merged and tweaked your previous patch into 
a branch, and the only new piece from this patch that I needed
was the piece about ext4 extent-based files.

The text now reads:

   Zeroing file space
       Specifying the FALLOC_FL_ZERO_RANGE flag (available since Linux
       3.14) in mode zeroes space in the byte range starting at offset
       and  continuing  for  len  bytes.   Within the specified range,
       blocks are preallocated for the regions that span the holes  in
       the  file.  After a successful call, subsequent reads from this
       range will return zeroes.

       Zeroing is done within the filesystem preferably by  converting
       the range into unwritten extents.  This approach means that the
       specified range will  not  be  physically  zeroed  out  on  the
       device, and I/O is required only to update file metadata.

       If  the  FALLOC_FL_KEEP_SIZE  flag is additionally specified in
       mode, the behavior of the call is similar, but  the  file  size
       will not be changed even if offset+len is greater than the file
       size.  This behaviour is the same as when  preallocating  space
       with FALLOC_FL_KEEP_SIZE specified.

       Not all filesystems support FALLOC_FL_ZERO_RANGE; if a filesys‐
       tem doesn't support the operation, an error is  returned.   The
       operation is supported on at least the following filesystems:

       *  XFS (since Linux 3.14)

       *  ext4, for extent-based files (since Linux 3.14)
   ...
   ERRORS
       EINVAL mode     is     FALLOC_FL_COLLAPSE_RANGE     or     FAL‐
              LOC_FL_ZERO_RANGE, but the file referred to by fd is not
              a regular file.

Okay?

Cheers,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Lukáš Czerner]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 2820 bytes --]

On Mon, 5 May 2014, Michael Kerrisk (man-pages) wrote:

> Date: Mon, 05 May 2014 14:44:48 +0200
> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> To: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Subject: Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE
> 
> 
> On 05/05/2014 02:04 PM, Lukas Czerner wrote:
> > FALLOC_FL_ZERO_RANGE was added in Linux 3.14,
> > for zeroing ranges in the allocated space in a file.
> > 
> > Signed-off-by: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> > ---
> > v2: Rebase and update the description
> > v3: Ext4 zero range on extent based files
> 
> Thank, Lukáš.
> 
> In fact I'd already merged and tweaked your previous patch into 
> a branch, and the only new piece from this patch that I needed
> was the piece about ext4 extent-based files.
> 
> The text now reads:
> 
>    Zeroing file space
>        Specifying the FALLOC_FL_ZERO_RANGE flag (available since Linux
>        3.14) in mode zeroes space in the byte range starting at offset
>        and  continuing  for  len  bytes.   Within the specified range,
>        blocks are preallocated for the regions that span the holes  in
>        the  file.  After a successful call, subsequent reads from this
>        range will return zeroes.
> 
>        Zeroing is done within the filesystem preferably by  converting
>        the range into unwritten extents.  This approach means that the
>        specified range will  not  be  physically  zeroed  out  on  the
>        device, and I/O is required only to update file metadata.

mostly for metadata as mentioned in my patch. Because we still need
to manually zero out partial blocks. But that's not really all that
important.

So I think it look ok.

Thanks!
-Lukas

> 
>        If  the  FALLOC_FL_KEEP_SIZE  flag is additionally specified in
>        mode, the behavior of the call is similar, but  the  file  size
>        will not be changed even if offset+len is greater than the file
>        size.  This behaviour is the same as when  preallocating  space
>        with FALLOC_FL_KEEP_SIZE specified.
> 
>        Not all filesystems support FALLOC_FL_ZERO_RANGE; if a filesys‐
>        tem doesn't support the operation, an error is  returned.   The
>        operation is supported on at least the following filesystems:
> 
>        *  XFS (since Linux 3.14)
> 
>        *  ext4, for extent-based files (since Linux 3.14)
>    ...
>    ERRORS
>        EINVAL mode     is     FALLOC_FL_COLLAPSE_RANGE     or     FAL‐
>               LOC_FL_ZERO_RANGE, but the file referred to by fd is not
>               a regular file.
> 
> Okay?
> 
> Cheers,
> 
> Michael
> 

Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Michael Kerrisk (man-pages)]

Hi Lukáš,

On Mon, May 5, 2014 at 3:06 PM, Lukáš Czerner <lczerner@redhat.com> wrote:
> On Mon, 5 May 2014, Michael Kerrisk (man-pages) wrote:
>
>> Date: Mon, 05 May 2014 14:44:48 +0200
>> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> To: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Subject: Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE
>>
>>
>> On 05/05/2014 02:04 PM, Lukas Czerner wrote:
>> > FALLOC_FL_ZERO_RANGE was added in Linux 3.14,
>> > for zeroing ranges in the allocated space in a file.
>> >
>> > Signed-off-by: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> > ---
>> > v2: Rebase and update the description
>> > v3: Ext4 zero range on extent based files
>>
>> Thank, Lukáš.
>>
>> In fact I'd already merged and tweaked your previous patch into
>> a branch, and the only new piece from this patch that I needed
>> was the piece about ext4 extent-based files.
>>
>> The text now reads:
>>
>>    Zeroing file space
>>        Specifying the FALLOC_FL_ZERO_RANGE flag (available since Linux
>>        3.14) in mode zeroes space in the byte range starting at offset
>>        and  continuing  for  len  bytes.   Within the specified range,
>>        blocks are preallocated for the regions that span the holes  in
>>        the  file.  After a successful call, subsequent reads from this
>>        range will return zeroes.
>>
>>        Zeroing is done within the filesystem preferably by  converting
>>        the range into unwritten extents.  This approach means that the
>>        specified range will  not  be  physically  zeroed  out  on  the
>>        device, and I/O is required only to update file metadata.
>
> mostly for metadata as mentioned in my patch. Because we still need
> to manually zero out partial blocks. But that's not really all that
> important.

Thanks for checking. Now I understand the "mostly"! How about we make the text:

[[
Zeroing is done within the filesystem preferably by converting the range into
unwritten extents.
This approach means that the specified range will not be physically zeroed
out on the device (except for partial blocks at the either end of the range),
and I/O is (otherwise) required only to update file metadata.
]]

?

Cheers,

Michael


>
> Thanks!
> -Lukas
>
>>
>>        If  the  FALLOC_FL_KEEP_SIZE  flag is additionally specified in
>>        mode, the behavior of the call is similar, but  the  file  size
>>        will not be changed even if offset+len is greater than the file
>>        size.  This behaviour is the same as when  preallocating  space
>>        with FALLOC_FL_KEEP_SIZE specified.
>>
>>        Not all filesystems support FALLOC_FL_ZERO_RANGE; if a filesys‐
>>        tem doesn't support the operation, an error is  returned.   The
>>        operation is supported on at least the following filesystems:
>>
>>        *  XFS (since Linux 3.14)
>>
>>        *  ext4, for extent-based files (since Linux 3.14)
>>    ...
>>    ERRORS
>>        EINVAL mode     is     FALLOC_FL_COLLAPSE_RANGE     or     FAL‐
>>               LOC_FL_ZERO_RANGE, but the file referred to by fd is not
>>               a regular file.
>>
>> Okay?
>>
>> Cheers,
>>
>> Michael
>>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Lukáš Czerner]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 4194 bytes --]

On Mon, 5 May 2014, Michael Kerrisk (man-pages) wrote:

> Date: Mon, 5 May 2014 21:46:22 +0200
> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> To: Lukáš Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> Cc: linux-man <linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org>
> Subject: Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE
> 
> Hi Lukáš,
> 
> On Mon, May 5, 2014 at 3:06 PM, Lukáš Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> > On Mon, 5 May 2014, Michael Kerrisk (man-pages) wrote:
> >
> >> Date: Mon, 05 May 2014 14:44:48 +0200
> >> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> >> To: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> >> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> >> Subject: Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE
> >>
> >>
> >> On 05/05/2014 02:04 PM, Lukas Czerner wrote:
> >> > FALLOC_FL_ZERO_RANGE was added in Linux 3.14,
> >> > for zeroing ranges in the allocated space in a file.
> >> >
> >> > Signed-off-by: Lukas Czerner <lczerner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> >> > ---
> >> > v2: Rebase and update the description
> >> > v3: Ext4 zero range on extent based files
> >>
> >> Thank, Lukáš.
> >>
> >> In fact I'd already merged and tweaked your previous patch into
> >> a branch, and the only new piece from this patch that I needed
> >> was the piece about ext4 extent-based files.
> >>
> >> The text now reads:
> >>
> >>    Zeroing file space
> >>        Specifying the FALLOC_FL_ZERO_RANGE flag (available since Linux
> >>        3.14) in mode zeroes space in the byte range starting at offset
> >>        and  continuing  for  len  bytes.   Within the specified range,
> >>        blocks are preallocated for the regions that span the holes  in
> >>        the  file.  After a successful call, subsequent reads from this
> >>        range will return zeroes.
> >>
> >>        Zeroing is done within the filesystem preferably by  converting
> >>        the range into unwritten extents.  This approach means that the
> >>        specified range will  not  be  physically  zeroed  out  on  the
> >>        device, and I/O is required only to update file metadata.
> >
> > mostly for metadata as mentioned in my patch. Because we still need
> > to manually zero out partial blocks. But that's not really all that
> > important.
> 
> Thanks for checking. Now I understand the "mostly"! How about we make the text:
> 
> [[
> Zeroing is done within the filesystem preferably by converting the range into
> unwritten extents.
> This approach means that the specified range will not be physically zeroed
> out on the device (except for partial blocks at the either end of the range),
> and I/O is (otherwise) required only to update file metadata.
> ]]

Perfect. Just get rid of "file" in the "file metadata" and I think
it's ok. The reason is that those are also file system metadata in
the case you're actually allocating blocks.

Thanks!
-Lukas

> 
> ?
> 
> Cheers,
> 
> Michael
> 
> 
> >
> > Thanks!
> > -Lukas
> >
> >>
> >>        If  the  FALLOC_FL_KEEP_SIZE  flag is additionally specified in
> >>        mode, the behavior of the call is similar, but  the  file  size
> >>        will not be changed even if offset+len is greater than the file
> >>        size.  This behaviour is the same as when  preallocating  space
> >>        with FALLOC_FL_KEEP_SIZE specified.
> >>
> >>        Not all filesystems support FALLOC_FL_ZERO_RANGE; if a filesys‐
> >>        tem doesn't support the operation, an error is  returned.   The
> >>        operation is supported on at least the following filesystems:
> >>
> >>        *  XFS (since Linux 3.14)
> >>
> >>        *  ext4, for extent-based files (since Linux 3.14)
> >>    ...
> >>    ERRORS
> >>        EINVAL mode     is     FALLOC_FL_COLLAPSE_RANGE     or     FAL‐
> >>               LOC_FL_ZERO_RANGE, but the file referred to by fd is not
> >>               a regular file.
> >>
> >> Okay?
> >>
> >> Cheers,
> >>
> >> Michael
> >>
> 
> 
> 
> 

Re: [PATCH v3] fallocate.2: Document FALLOC_FL_ZERO_RANGE

[Michael Kerrisk (man-pages)]

>> [[
>> Zeroing is done within the filesystem preferably by converting the range into
>> unwritten extents.
>> This approach means that the specified range will not be physically zeroed
>> out on the device (except for partial blocks at the either end of the range),
>> and I/O is (otherwise) required only to update file metadata.
>> ]]
> 
> Perfect. Just get rid of "file" in the "file metadata" and I think
> it's ok. The reason is that those are also file system metadata in
> the case you're actually allocating blocks.

Done! Thanks for your patient help, Lukáš.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html