LinuxLists.cc - [PATCH v3] manpage: update FALLOC_FL_INSERT

2015-05-08 05:28:50

Subject: [PATCH v3] manpage: update FALLOC_FL_INSERT_RANGE flag in fallocate

Update FALLOC_FL_INSERT_RANGE flag in fallocate.

Signed-off-by: Namjae Jeon <[email protected]>
Signed-off-by: Ashish Sangwan <[email protected]>
---
man2/fallocate.2 | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 84 insertions(+), 5 deletions(-)

diff --git a/man2/fallocate.2 b/man2/fallocate.2
index 0cc1a00..0d31027 100644
--- a/man2/fallocate.2
+++ b/man2/fallocate.2
@@ -228,6 +228,59 @@ ext4, for extent-based files (since Linux 3.15)
.IP *
SMB3 (since Linux 3.17)
.\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
+.SS Increasing file space
+flag (available since Linux 4.1)
+.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
+Specifying the
+.BR FALLOC_FL_INSERT_RANGE
+flag in
+.I mode
+will increase the file space by inserting a hole within the file size without
+overwriting any existing data.
+The hole will start at
+.I offset
+and continue for
+.I len
+bytes.
+For inserting hole inside file, the contents of the file starting at
+.I offset
+will be shifted towards right by
+.I len
+bytes.
+Inserting a hole inside the file will increase the file size by
+.I len
+bytes.
+
+This mode has the same limitation as
+.BR FALLOC_FL_COLLAPSE_RANGE
+regarding the
+granularity of the operation.
+If the granularity requirements are not met,
+.BR fallocate ()
+will fail with the error
+.BR EINVAL.
+If the
+.I offset
+is greater than or equal to the end of file, an error is
+returned.
+For such type of operations, i.e. inserting a hole at the end of file,
+.BR ftruncate(2)
+should be used.
+In case
+.IR offset + len
+exceeds the maximum file size, errno will be set to
+.B EFBIG.
+
+No other flags may be specified in
+.IR mode
+in conjunction with
+.BR FALLOC_FL_INSERT_RANGE .
+
+As of Linux 4.1,
+.B FALLOC_FL_INSERT_RANGE
+is supported by
+XFS.
+.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
.SH RETURN VALUE
On success,
.BR fallocate ()
@@ -245,6 +298,12 @@ is not a valid file descriptor, or is not opened for writing.
.IR offset + len
exceeds the maximum file size.
.TP
+.B EFBIG
+.I mode
+is
+.BR FALLOC_FL_INSERT_RANGE ,
+the current file size+len exceeds the maximum file size.
+.TP
.B EINTR
A signal was caught during execution.
.TP
@@ -273,7 +332,17 @@ reaches or passes the end of the file.
.B EINVAL
.I mode
is
-.BR FALLOC_FL_COLLAPSE_RANGE ,
+.BR FALLOC_FL_INSERT_RANGE
+and the range specified by
+.I offset
+reaches or passes the end of the file.
+.TP
+.B EINVAL
+.I mode
+is
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE ,
but either
.I offset
or
@@ -282,18 +351,24 @@ is not a multiple of the filesystem block size.
.TP
.B EINVAL
.I mode
-contains both
+contains either of
.B FALLOC_FL_COLLAPSE_RANGE
+or
+.B FALLOC_FL_INSERT_RANGE
and other flags;
no other flags are permitted with
-.BR FALLOC_FL_COLLAPSE_RANGE .
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE .
.TP
.B EINVAL
.I mode
is
.BR FALLOC_FL_COLLAPSE_RANGE
or
-.BR FALLOC_FL_ZERO_RANGE ,
+.BR FALLOC_FL_ZERO_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE ,
but the file referred to by
.I fd
is not a regular file.
@@ -345,6 +420,8 @@ specifies
.BR FALLOC_FL_PUNCH_HOLE
or
.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE
and
the file referred to by
.I fd
@@ -363,7 +440,9 @@ refers to a pipe or FIFO.
.B ETXTBSY
.I mode
specifies
-.BR FALLOC_FL_COLLAPSE_RANGE ,
+.BR FALLOC_FL_COLLAPSE_RANGE
+or
+.BR FALLOC_FL_INSERT_RANGE ,
but the file referred to by
.IR fd
is currently being executed.
--
1.8.5.5

2015-05-08 09:40:26

by Michael Kerrisk (man-pages)

[permalink] [raw]

Subject: Re: [PATCH v3] manpage: update FALLOC_FL_INSERT_RANGE flag in fallocate

Hi Namjae,

> Update FALLOC_FL_INSERT_RANGE flag in fallocate.

Sorry -- I should have said that I already applied your V2
patch and made the fix we discussed (and that you add below).
I just hadn't pushed to Git yet. Done now.

Cheers,

Michael

On 05/08/2015 07:28 AM, Namjae Jeon wrote:
> Signed-off-by: Namjae Jeon <[email protected]>
> Signed-off-by: Ashish Sangwan <[email protected]>
> ---
> man2/fallocate.2 | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
> 1 file changed, 84 insertions(+), 5 deletions(-)
>
> diff --git a/man2/fallocate.2 b/man2/fallocate.2
> index 0cc1a00..0d31027 100644
> --- a/man2/fallocate.2
> +++ b/man2/fallocate.2
> @@ -228,6 +228,59 @@ ext4, for extent-based files (since Linux 3.15)
> .IP *
> SMB3 (since Linux 3.17)
> .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
> +.SS Increasing file space
> +flag (available since Linux 4.1)
> +.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
> +Specifying the
> +.BR FALLOC_FL_INSERT_RANGE
> +flag in
> +.I mode
> +will increase the file space by inserting a hole within the file size without
> +overwriting any existing data.
> +The hole will start at
> +.I offset
> +and continue for
> +.I len
> +bytes.
> +For inserting hole inside file, the contents of the file starting at
> +.I offset
> +will be shifted towards right by
> +.I len
> +bytes.
> +Inserting a hole inside the file will increase the file size by
> +.I len
> +bytes.
> +
> +This mode has the same limitation as
> +.BR FALLOC_FL_COLLAPSE_RANGE
> +regarding the
> +granularity of the operation.
> +If the granularity requirements are not met,
> +.BR fallocate ()
> +will fail with the error
> +.BR EINVAL.
> +If the
> +.I offset
> +is greater than or equal to the end of file, an error is
> +returned.
> +For such type of operations, i.e. inserting a hole at the end of file,
> +.BR ftruncate(2)
> +should be used.
> +In case
> +.IR offset + len
> +exceeds the maximum file size, errno will be set to
> +.B EFBIG.
> +
> +No other flags may be specified in
> +.IR mode
> +in conjunction with
> +.BR FALLOC_FL_INSERT_RANGE .
> +
> +As of Linux 4.1,
> +.B FALLOC_FL_INSERT_RANGE
> +is supported by
> +XFS.
> +.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
> .SH RETURN VALUE
> On success,
> .BR fallocate ()
> @@ -245,6 +298,12 @@ is not a valid file descriptor, or is not opened for writing.
> .IR offset + len
> exceeds the maximum file size.
> .TP
> +.B EFBIG
> +.I mode
> +is
> +.BR FALLOC_FL_INSERT_RANGE ,
> +the current file size+len exceeds the maximum file size.
> +.TP
> .B EINTR
> A signal was caught during execution.
> .TP
> @@ -273,7 +332,17 @@ reaches or passes the end of the file.
> .B EINVAL
> .I mode
> is
> -.BR FALLOC_FL_COLLAPSE_RANGE ,
> +.BR FALLOC_FL_INSERT_RANGE
> +and the range specified by
> +.I offset
> +reaches or passes the end of the file.
> +.TP
> +.B EINVAL
> +.I mode
> +is
> +.BR FALLOC_FL_COLLAPSE_RANGE
> +or
> +.BR FALLOC_FL_INSERT_RANGE ,
> but either
> .I offset
> or
> @@ -282,18 +351,24 @@ is not a multiple of the filesystem block size.
> .TP
> .B EINVAL
> .I mode
> -contains both
> +contains either of
> .B FALLOC_FL_COLLAPSE_RANGE
> +or
> +.B FALLOC_FL_INSERT_RANGE
> and other flags;
> no other flags are permitted with
> -.BR FALLOC_FL_COLLAPSE_RANGE .
> +.BR FALLOC_FL_COLLAPSE_RANGE
> +or
> +.BR FALLOC_FL_INSERT_RANGE .
> .TP
> .B EINVAL
> .I mode
> is
> .BR FALLOC_FL_COLLAPSE_RANGE
> or
> -.BR FALLOC_FL_ZERO_RANGE ,
> +.BR FALLOC_FL_ZERO_RANGE
> +or
> +.BR FALLOC_FL_INSERT_RANGE ,
> but the file referred to by
> .I fd
> is not a regular file.
> @@ -345,6 +420,8 @@ specifies
> .BR FALLOC_FL_PUNCH_HOLE
> or
> .BR FALLOC_FL_COLLAPSE_RANGE
> +or
> +.BR FALLOC_FL_INSERT_RANGE
> and
> the file referred to by
> .I fd
> @@ -363,7 +440,9 @@ refers to a pipe or FIFO.
> .B ETXTBSY
> .I mode
> specifies
> -.BR FALLOC_FL_COLLAPSE_RANGE ,
> +.BR FALLOC_FL_COLLAPSE_RANGE
> +or
> +.BR FALLOC_FL_INSERT_RANGE ,
> but the file referred to by
> .IR fd
> is currently being executed.
>

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

2015-05-08 09:42:31

by Namjae Jeon

[permalink] [raw]

Subject: RE: [PATCH v3] manpage: update FALLOC_FL_INSERT_RANGE flag in fallocate

> Hi Namjae,
Hi Michael,

>
> > Update FALLOC_FL_INSERT_RANGE flag in fallocate.
>
> Sorry -- I should have said that I already applied your V2
> patch and made the fix we discussed (and that you add below).
> I just hadn't pushed to Git yet. Done now.
Okay :)
Thanks very much!!
>
> Cheers,
>
> Michael
>
> On 05/08/2015 07:28 AM, Namjae Jeon wrote:
> > Signed-off-by: Namjae Jeon <[email protected]>
> > Signed-off-by: Ashish Sangwan <[email protected]>
> > ---
> > man2/fallocate.2 | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
> > 1 file changed, 84 insertions(+), 5 deletions(-)
> >
> > diff --git a/man2/fallocate.2 b/man2/fallocate.2
> > index 0cc1a00..0d31027 100644
> > --- a/man2/fallocate.2
> > +++ b/man2/fallocate.2
> > @@ -228,6 +228,59 @@ ext4, for extent-based files (since Linux 3.15)
> > .IP *
> > SMB3 (since Linux 3.17)
> > .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556
> > +.SS Increasing file space
> > +flag (available since Linux 4.1)
> > +.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
> > +Specifying the
> > +.BR FALLOC_FL_INSERT_RANGE
> > +flag in
> > +.I mode
> > +will increase the file space by inserting a hole within the file size without
> > +overwriting any existing data.
> > +The hole will start at
> > +.I offset
> > +and continue for
> > +.I len
> > +bytes.
> > +For inserting hole inside file, the contents of the file starting at
> > +.I offset
> > +will be shifted towards right by
> > +.I len
> > +bytes.
> > +Inserting a hole inside the file will increase the file size by
> > +.I len
> > +bytes.
> > +
> > +This mode has the same limitation as
> > +.BR FALLOC_FL_COLLAPSE_RANGE
> > +regarding the
> > +granularity of the operation.
> > +If the granularity requirements are not met,
> > +.BR fallocate ()
> > +will fail with the error
> > +.BR EINVAL.
> > +If the
> > +.I offset
> > +is greater than or equal to the end of file, an error is
> > +returned.
> > +For such type of operations, i.e. inserting a hole at the end of file,
> > +.BR ftruncate(2)
> > +should be used.
> > +In case
> > +.IR offset + len
> > +exceeds the maximum file size, errno will be set to
> > +.B EFBIG.
> > +
> > +No other flags may be specified in
> > +.IR mode
> > +in conjunction with
> > +.BR FALLOC_FL_INSERT_RANGE .
> > +
> > +As of Linux 4.1,
> > +.B FALLOC_FL_INSERT_RANGE
> > +is supported by
> > +XFS.
> > +.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b
> > .SH RETURN VALUE
> > On success,
> > .BR fallocate ()
> > @@ -245,6 +298,12 @@ is not a valid file descriptor, or is not opened for writing.
> > .IR offset + len
> > exceeds the maximum file size.
> > .TP
> > +.B EFBIG
> > +.I mode
> > +is
> > +.BR FALLOC_FL_INSERT_RANGE ,
> > +the current file size+len exceeds the maximum file size.
> > +.TP
> > .B EINTR
> > A signal was caught during execution.
> > .TP
> > @@ -273,7 +332,17 @@ reaches or passes the end of the file.
> > .B EINVAL
> > .I mode
> > is
> > -.BR FALLOC_FL_COLLAPSE_RANGE ,
> > +.BR FALLOC_FL_INSERT_RANGE
> > +and the range specified by
> > +.I offset
> > +reaches or passes the end of the file.
> > +.TP
> > +.B EINVAL
> > +.I mode
> > +is
> > +.BR FALLOC_FL_COLLAPSE_RANGE
> > +or
> > +.BR FALLOC_FL_INSERT_RANGE ,
> > but either
> > .I offset
> > or
> > @@ -282,18 +351,24 @@ is not a multiple of the filesystem block size.
> > .TP
> > .B EINVAL
> > .I mode
> > -contains both
> > +contains either of
> > .B FALLOC_FL_COLLAPSE_RANGE
> > +or
> > +.B FALLOC_FL_INSERT_RANGE
> > and other flags;
> > no other flags are permitted with
> > -.BR FALLOC_FL_COLLAPSE_RANGE .
> > +.BR FALLOC_FL_COLLAPSE_RANGE
> > +or
> > +.BR FALLOC_FL_INSERT_RANGE .
> > .TP
> > .B EINVAL
> > .I mode
> > is
> > .BR FALLOC_FL_COLLAPSE_RANGE
> > or
> > -.BR FALLOC_FL_ZERO_RANGE ,
> > +.BR FALLOC_FL_ZERO_RANGE
> > +or
> > +.BR FALLOC_FL_INSERT_RANGE ,
> > but the file referred to by
> > .I fd
> > is not a regular file.
> > @@ -345,6 +420,8 @@ specifies
> > .BR FALLOC_FL_PUNCH_HOLE
> > or
> > .BR FALLOC_FL_COLLAPSE_RANGE
> > +or
> > +.BR FALLOC_FL_INSERT_RANGE
> > and
> > the file referred to by
> > .I fd
> > @@ -363,7 +440,9 @@ refers to a pipe or FIFO.
> > .B ETXTBSY
> > .I mode
> > specifies
> > -.BR FALLOC_FL_COLLAPSE_RANGE ,
> > +.BR FALLOC_FL_COLLAPSE_RANGE
> > +or
> > +.BR FALLOC_FL_INSERT_RANGE ,
> > but the file referred to by
> > .IR fd
> > is currently being executed.
> >
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/