Skip to contentSkip to conversation

man2/fallocate.2: Fix documentation of shared blocks

PATCH In review Dan Robertson 3 participants 11 messages Jun 21, 2021 – Jul 4, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

cover man2/fallocate.2: Fix documentation of shared blocks

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(-)
#1 lore raw

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

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")
---
 man2/fallocate.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/fallocate.2 +1 -1
index a62706193..b4cb3516f 100644
@@ -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
Reviewed-by on v1 1/1
#2 lore raw

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

Quoted 6 lines · 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")

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

--D

Quoted 17 lines
---
 man2/fallocate.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/fallocate.2 +1 -1
index a62706193..b4cb3516f 100644
@@ -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
#3 lore raw

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

Quoted 10 lines · Darrick J. Wong
Quoted 6 lines · 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")

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

#4 lore raw

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

In reply to Darrick J. Wong

Hi Darrick,

Quoted 5 lines · Darrick J. Wong
Quoted 4 lines · 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.

Quoted 7 lines
Quoted 2 lines
Fixes 07c7a6a35497 ("man2/fallocate.2: Document behavior with shared blocks")

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

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

Cheers,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#5 lore raw

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

In reply to Darrick J. Wong

Hi Dan,

Quoted 6 lines · Dan Robertson
Quoted 5 lines

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#6 lore raw

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

Quoted 7 lines · Alejandro Colomar (man-pages)

Hi Dan,

Quoted 5 lines · Dan Robertson
Quoted 4 lines

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.

Quoted 6 lines
Quoted 1 line
Quoted 1 line
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.

Quoted 9 lines

Thanks,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#7 lore raw

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

Hi Dan,

Quoted 10 lines · Dan Robertson
Quoted 9 lines · Alejandro Colomar (man-pages)

Hi Dan,

Quoted 6 lines · Dan Robertson
Quoted 5 lines

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")
Quoted 7 lines
Quoted 4 lines

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...

Quoted 2 lines

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.

Quoted 10 lines
Quoted 10 lines

Thanks,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#8 lore raw

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

Alex,

Quoted 31 lines · Alejandro Colomar (man-pages)
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines · Dan Robertson
Quoted 5 lines

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")
Quoted 7 lines
Quoted 4 lines

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$
]

Quoted 4 lines

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.

Quoted 5 lines
Quoted 3 lines

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

#9 lore raw

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

Dan,

Quoted 39 lines · Dan Robertson

Alex,

Quoted 31 lines · Alejandro Colomar (man-pages)
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines · Dan Robertson
Quoted 5 lines

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")
Quoted 7 lines
Quoted 4 lines

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$
]

Quoted 4 lines

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...

Quoted 8 lines

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

Quoted 11 lines
Quoted 6 lines
Quoted 4 lines

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#10 lore raw
In reply to Dan Robertson

Hi Dan,

Quoted 8 lines · 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 :)

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

Quoted 7 lines

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

 man2/fallocate.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/