xfs
[Top] [All Lists]

Re: [PATCH v10 12/12] manpage: update FALLOC_FL_INSERT_RANGE flag in fal

To: Namjae Jeon <linkinjeon@xxxxxxxxx>, david@xxxxxxxxxxxxx, tytso@xxxxxxx
Subject: Re: [PATCH v10 12/12] manpage: update FALLOC_FL_INSERT_RANGE flag in fallocate
From: "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx>
Date: Wed, 06 May 2015 14:43:25 +0200
Cc: mtk.manpages@xxxxxxxxx, linux-fsdevel@xxxxxxxxxxxxxxx, linux-kernel@xxxxxxxxxxxxxxx, linux-ext4@xxxxxxxxxxxxxxx, xfs@xxxxxxxxxxx, a.sangwan@xxxxxxxxxxx, bfoster@xxxxxxxxxx, linux-man@xxxxxxxxxxxxxxx, linux-api@xxxxxxxxxxxxxxx, Namjae Jeon <namjae.jeon@xxxxxxxxxxx>
Delivered-to: xfs@xxxxxxxxxxx
Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; bh=TIynK9IvaEj63xjT7Tv2f0ZXq/ELfGxu2DHJ44rdw9g=; b=R9ks+QkZCZF5zpE+qBOG6diH0w+5n7Vdn4NVd91BK+9PwUS2HvC90xGc2EntwkCSof waWLRlGpJghiNZ5JuI2NwcGALPq5sJunlr0MyaBBCRNPfi2jg8dmiR6JhKMEV8NvSYAj DdO0R5WkL5wF8775aw/9jP9ydU1CKxB71X1iYh4h857VDbpAaKM04F+Ly4rEXONK9vl5 A2Wd3L+c4tv6pKI+SH7QKNXrj7+njIQxVvTTeL22jm/MSUoBRQS49dsn2zEElAGT8bHg kwFTOYyQ2IdyRxx7zKPNltpv6Kpe3X1JBht79lyoGnqsA11JCcuJk+qjwqlhGoHM2ynH 11FQ==
In-reply-to: <1424533554-28024-13-git-send-email-linkinjeon@xxxxxxxxx>
References: <1424533554-28024-1-git-send-email-linkinjeon@xxxxxxxxx> <1424533554-28024-13-git-send-email-linkinjeon@xxxxxxxxx>
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.5.0
Hello Namjae Jeon,

I see that FALLOC_FL_INSERT_RANGE has hit mainline. Could I ask you refresh 
this patch, please? (Against latest man-pages Git, please, since the current
patch does not apply cleanly).

See some comments below.

On 02/21/2015 04:45 PM, Namjae Jeon wrote:
> From: Namjae Jeon <namjae.jeon@xxxxxxxxxxx>
> 
> Update FALLOC_FL_INSERT_RANGE flag in fallocate.
> 
> Signed-off-by: Namjae Jeon <namjae.jeon@xxxxxxxxxxx>
> Signed-off-by: Ashish Sangwan <a.sangwan@xxxxxxxxxxx>
> ---
>  man2/fallocate.2 |   88 
> ++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 82 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/fallocate.2 b/man2/fallocate.2
> index adf42db..9b3c460 100644
> --- a/man2/fallocate.2
> +++ b/man2/fallocate.2
> @@ -8,7 +8,7 @@
>  .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
>  .\" 2011-09-19: Substantial restructuring of the page
>  .\"
> -.TH FALLOCATE 2 2015-01-22 "Linux" "Linux Programmer's Manual"
> +.TH FALLOCATE 2 2015-02-14 "Linux" "Linux Programmer's Manual"

No need to update the timestamp on the page. I have scripts
that do this automatically.

>  .SH NAME
>  fallocate \- manipulate file space
>  .SH SYNOPSIS
> @@ -225,6 +225,56 @@ XFS (since Linux 3.14)
>  .IP *
>  ext4, for extent-based files (since Linux 3.14)
>  .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
> +.SS Increasing file space
> +.\" TODO: Mention commit id and supporting Linux version

Yes, please add the commit ID and "Linux 4.1".

> +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
                                  ^
Please start new sentences on new source lines. (Same thing at various 
lines below.)

> +.I offset
> +and continue for
> +.I len
> +bytes. For inserting hole inside file, the contents of the file starting at

Please start new sentences on new source lines.

> +.I offset
> +will be shifted towards right by
> +.I len
> +bytes. Inserting a hole inside the file will increase the file size by

Please start new sentences on new source lines.

> +.I len
> +bytes.
> +
> +This mode has the same limitation as
> +.BR FALLOC_FL_COLLAPSE_RANGE
> +regarding the
> +granularity of the operation.
> +If the granulrity requirements are not met,

Spelling: "granularity"

> +.BR fallocate ()
> +will fail with the error
> +.BR EINVAL.
> +If the
> +.I offset
> +overlaps with end of file OR if it is greater than end of file, an error is
> +returned. For such type of operations, i.e. inserting a hole at the end of

Please start new sentences on new source lines.

> +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 XXXX,
> +.\" TODO: Mention commit id and supporting Linux version
> +.B FALLOC_FL_INSERT_RANGE
> +is supported by
> +ext4 (only for extent-based files) and XFS.

Is the ext4 support really there? Grep Linus's current Git, it appears
that only XFS support is currently there?

> +
>  .SH RETURN VALUE
>  On success,
>  .BR fallocate ()
> @@ -242,6 +292,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 excceds the maximum file size.

"exceeds"

> +.TP
>  .B EINTR
>  A signal was caught during execution.
>  .TP
> @@ -270,7 +326,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
> @@ -279,18 +345,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.
> @@ -342,6 +414,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
> @@ -360,7 +434,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.
> 

Thanks,

Michael


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

<Prev in Thread] Current Thread [Next in Thread>