[PATCH 0/1] man2/fallocate.2: Fix documentation of shared blocks

[PATCH 0/1] man2/fallocate.2: Fix documentation of shared blocks

[Dan Robertson]

While doing some work on fallocate for bcachefs I think I stumbled on a
typo in the fallocate man page. FALLOC_FL_UNSHARE should be
FALLOC_FL_UNSHARE_RANGE. I believe this is a typo instead of an update
as a brief look at git history in the kernel seems to indicate that the
flag was never previously FALLOC_FL_UNSHARE.

If I missed something in my review of history, please let me know. Any
feedback would be welcome :)

Dan Robertson (1):
  man2/fallocate.2: tfix documentation of shared blocks

 man2/fallocate.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

[PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Dan Robertson]

Fix a typo in the documentation of using fallocate to allocate shared
blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
FALLOC_FL_UNSHARE_RANGE.

Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
Signed-off-by: Dan Robertson <dan@dlrobertson.com>
---
 man2/fallocate.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man2/fallocate.2 b/man2/fallocate.2
index a62706193..b4cb3516f 100644
--- a/man2/fallocate.2
+++ b/man2/fallocate.2
@@ -81,7 +81,7 @@ Preallocating zeroed blocks beyond the end of the file in this manner
 is useful for optimizing append workloads.
 .PP
 If the
-.B FALLOC_FL_UNSHARE
+.B FALLOC_FL_UNSHARE_RANGE
 flag is specified in
 .IR mode ,
 shared file data extents will be made private to the file to guarantee

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Darrick J. Wong]

On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
> Fix a typo in the documentation of using fallocate to allocate shared
> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
> FALLOC_FL_UNSHARE_RANGE.
> 
> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
> Signed-off-by: Dan Robertson <dan@dlrobertson.com>

Definitely an artifact of unshare being added and removed repeatedly
during the development of XFS reflink.  Thanks for fixing this...

Reviewed-by: Darrick J. Wong <djwong@kernel.org>

--D

> ---
>  man2/fallocate.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/fallocate.2 b/man2/fallocate.2
> index a62706193..b4cb3516f 100644
> --- a/man2/fallocate.2
> +++ b/man2/fallocate.2
> @@ -81,7 +81,7 @@ Preallocating zeroed blocks beyond the end of the file in this manner
>  is useful for optimizing append workloads.
>  .PP
>  If the
> -.B FALLOC_FL_UNSHARE
> +.B FALLOC_FL_UNSHARE_RANGE
>  flag is specified in
>  .IR mode ,
>  shared file data extents will be made private to the file to guarantee

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Dan Robertson]

[-- Attachment #1: Type: text/plain, Size: 663 bytes --]

On Sun, Jun 20, 2021 at 09:25:50PM -0700, Darrick J. Wong wrote:
> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
> > Fix a typo in the documentation of using fallocate to allocate shared
> > blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
> > FALLOC_FL_UNSHARE_RANGE.
> > 
> > Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
> > Signed-off-by: Dan Robertson <dan@dlrobertson.com>
> 
> Definitely an artifact of unshare being added and removed repeatedly
> during the development of XFS reflink.  Thanks for fixing this...

Yeah, that makes sense. Thanks for checking this!

 - Dan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Alejandro Colomar (man-pages)]

Hi Darrick,

On 6/21/21 6:25 AM, Darrick J. Wong wrote:
> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
>> Fix a typo in the documentation of using fallocate to allocate shared
>> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
>> FALLOC_FL_UNSHARE_RANGE.
>>
>> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
>> Signed-off-by: Dan Robertson <dan@dlrobertson.com>
> 
> Definitely an artifact of unshare being added and removed repeatedly
> during the development of XFS reflink.  Thanks for fixing this...
> 
> Reviewed-by: Darrick J. Wong <djwong@kernel.org>

Thanks for the review!  "Reviewed-by" added.

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Alejandro Colomar (man-pages)]

Hi Dan,

> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
>> Fix a typo in the documentation of using fallocate to allocate shared
>> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
>> FALLOC_FL_UNSHARE_RANGE.
>>
>> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")

BTW, I can't find that commit hash in git.  I have that commit as
63a599c657d8.

However, git doesn't fail...  It's weird.  Could you confirm that?

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Dan Robertson]

[-- Attachment #1: Type: text/plain, Size: 1005 bytes --]

On Sat, Jul 03, 2021 at 08:26:26PM +0200, Alejandro Colomar (man-pages) wrote:
> Hi Dan,
> 
> > On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
> >> Fix a typo in the documentation of using fallocate to allocate shared
> >> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
> >> FALLOC_FL_UNSHARE_RANGE.
> >>
> >> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
> 
> BTW, I can't find that commit hash in git.  I have that commit as
> 63a599c657d8.
> 
> However, git doesn't fail...  It's weird.  Could you confirm that?

Gah! You are correct. My bad. I used copied the commit hash for the commit in
the kernel that introduced the FALLOC_FL_UNSHARE_RANGE flag. My bad. I can
submit a second version of the patch with the correct commit hash if you'd like.

> 
> Thanks,
> 
> Alex
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Alejandro Colomar (man-pages)]

Hi Dan,

On 7/3/21 10:09 PM, Dan Robertson wrote:
> On Sat, Jul 03, 2021 at 08:26:26PM +0200, Alejandro Colomar (man-pages) wrote:
>> Hi Dan,
>>
>>> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
>>>> Fix a typo in the documentation of using fallocate to allocate shared
>>>> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
>>>> FALLOC_FL_UNSHARE_RANGE.
>>>>
>>>> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
>>
>> BTW, I can't find that commit hash in git.  I have that commit as
>> 63a599c657d8.
>>
>> However, git doesn't fail...  It's weird.  Could you confirm that?
> 
> Gah! You are correct. My bad. I used copied the commit hash for the commit in
> the kernel that introduced the FALLOC_FL_UNSHARE_RANGE flag. My bad.

I thought so, but I couldn't find that commit in Linus' tree either :/

[
.../linux$ git log -1 07c7a6a35497
fatal: ambiguous argument '07c7a6a35497': unknown revision or path not
in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
.../linux$ git log -1 07c7a6a35497 --
fatal: bad revision '07c7a6a35497'
.../linux$ cd ../man-pages/
.../man-pages$ git log -1 07c7a6a35497
.../man-pages$ git log -1 07c7a6a35497 --
.../man-pages$
]

I can't understand that.  It fails in the kernel tree, but not in the
man-pages tree.  But it doesn't find it in either.

It doesn't matter, but I'm curious...

> I can
> submit a second version of the patch with the correct commit hash if you'd like.

No, don't worry; I fixed it.

> 
>>
>> Thanks,
>>
>> Alex
>>
>> -- 
>> Alejandro Colomar
>> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
>> http://www.alejandro-colomar.es/

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Dan Robertson]

[-- Attachment #1: Type: text/plain, Size: 1950 bytes --]

Alex,

On Sat, Jul 03, 2021 at 11:31:32PM +0200, Alejandro Colomar (man-pages) wrote:
> >>> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
> >>>> Fix a typo in the documentation of using fallocate to allocate shared
> >>>> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
> >>>> FALLOC_FL_UNSHARE_RANGE.
> >>>>
> >>>> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
> >>
> >> BTW, I can't find that commit hash in git.  I have that commit as
> >> 63a599c657d8.
> >>
> >> However, git doesn't fail...  It's weird.  Could you confirm that?
> > 
> > Gah! You are correct. My bad. I used copied the commit hash for the commit in
> > the kernel that introduced the FALLOC_FL_UNSHARE_RANGE flag. My bad.
> 
> I thought so, but I couldn't find that commit in Linus' tree either :/
> 
> [
> .../linux$ git log -1 07c7a6a35497
> fatal: ambiguous argument '07c7a6a35497': unknown revision or path not
> in the working tree.
> Use '--' to separate paths from revisions, like this:
> 'git <command> [<revision>...] -- [<file>...]'
> .../linux$ git log -1 07c7a6a35497 --
> fatal: bad revision '07c7a6a35497'
> .../linux$ cd ../man-pages/
> .../man-pages$ git log -1 07c7a6a35497
> .../man-pages$ git log -1 07c7a6a35497 --
> .../man-pages$
> ]
> 
> I can't understand that.  It fails in the kernel tree, but not in the
> man-pages tree.  But it doesn't find it in either.
> 
> It doesn't matter, but I'm curious...

Ah! Got it! 07c7a6a35497 is the tree hash for 63a599c657d8 in the man-pages
repo.

.../man-pages$ git rev-parse --short=12 63a599c657d8:
07c7a6a35497

I bet I copied the wrong hash from git blame in vim-fugitive when trying to
find the commit that first contained the typo.

> 
> > I can
> > submit a second version of the patch with the correct commit hash if you'd like.
> 
> No, don't worry; I fixed it.

Thanks!

 - Dan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/1] man2/fallocate.2: tfix documentation of shared blocks

[Alejandro Colomar (man-pages)]

Dan,

On 7/4/21 12:55 AM, Dan Robertson wrote:
> Alex,
> 
> On Sat, Jul 03, 2021 at 11:31:32PM +0200, Alejandro Colomar (man-pages) wrote:
>>>>> On Sun, Jun 20, 2021 at 08:44:53PM -0400, Dan Robertson wrote:
>>>>>> Fix a typo in the documentation of using fallocate to allocate shared
>>>>>> blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
>>>>>> FALLOC_FL_UNSHARE_RANGE.
>>>>>>
>>>>>> Fixes: 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")
>>>>
>>>> BTW, I can't find that commit hash in git.  I have that commit as
>>>> 63a599c657d8.
>>>>
>>>> However, git doesn't fail...  It's weird.  Could you confirm that?
>>>
>>> Gah! You are correct. My bad. I used copied the commit hash for the commit in
>>> the kernel that introduced the FALLOC_FL_UNSHARE_RANGE flag. My bad.
>>
>> I thought so, but I couldn't find that commit in Linus' tree either :/
>>
>> [
>> .../linux$ git log -1 07c7a6a35497
>> fatal: ambiguous argument '07c7a6a35497': unknown revision or path not
>> in the working tree.
>> Use '--' to separate paths from revisions, like this:
>> 'git <command> [<revision>...] -- [<file>...]'
>> .../linux$ git log -1 07c7a6a35497 --
>> fatal: bad revision '07c7a6a35497'
>> .../linux$ cd ../man-pages/
>> .../man-pages$ git log -1 07c7a6a35497
>> .../man-pages$ git log -1 07c7a6a35497 --
>> .../man-pages$
>> ]
>>
>> I can't understand that.  It fails in the kernel tree, but not in the
>> man-pages tree.  But it doesn't find it in either.
>>
>> It doesn't matter, but I'm curious...
> 
> Ah! Got it! 07c7a6a35497 is the tree hash for 63a599c657d8 in the man-pages
> repo.
> 
> .../man-pages$ git rev-parse --short=12 63a599c657d8:
> 07c7a6a35497
> 
> I bet I copied the wrong hash from git blame in vim-fugitive when trying to
> find the commit that first contained the typo.

Hmm, interesting.  I didn't knew about tree hashes (well, I guessed
there was something like that, but I had never seen them).  I learnt
something new today :)

Cheers,

Alex

> 
>>
>>> I can
>>> submit a second version of the patch with the correct commit hash if you'd like.
>>
>> No, don't worry; I fixed it.
> 
> Thanks!
> 
>  - Dan
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 0/1] man2/fallocate.2: Fix documentation of shared blocks

[Alejandro Colomar (man-pages)]

Hi Dan,

On 6/21/21 2:44 AM, Dan Robertson wrote:
> While doing some work on fallocate for bcachefs I think I stumbled on a
> typo in the fallocate man page. FALLOC_FL_UNSHARE should be
> FALLOC_FL_UNSHARE_RANGE. I believe this is a typo instead of an update
> as a brief look at git history in the kernel seems to indicate that the
> flag was never previously FALLOC_FL_UNSHARE.
> 
> If I missed something in my review of history, please let me know. Any
> feedback would be welcome :)

You seem to be correct.  There are 2 commits that talk about
FALLOC_FL_UNSHARE, but it seems that they do so for simplicity, and the
code only contains FALLOC_FL_UNSHARE_RANGE.

I applied the patch.

Thanks,

Alex

> 
> Dan Robertson (1):
>   man2/fallocate.2: tfix documentation of shared blocks
> 
>  man2/fallocate.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/