btrfs: Doc: Fix the wrong doc about `btrfs filesystem sync`
Subsystems (2)
PATCH 1/1 btrfs: Doc: Fix the wrong doc about `btrfs filesystem sync`
Since commit ecd4bb607f35 ("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page of btrfs filesystem shows sync subcommand will wait for all existing orphan subvolumes to be dropped.
That's not true, even at that commit, btrfs fi sync only calls BTRFS_IOC_SYNC ioctl, which is not that much different from vanilla sync.
It doesn't wait for orphan subvolumes to be dropped from the very beginning.
It's btrfs subvolume sync doing the wait work.
--- Documentation/btrfs-filesystem.asciidoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/btrfs-filesystem.asciidoc +2 -3
@@ -253,9 +253,8 @@ show sizes in GiB, or GB with --si show sizes in TiB, or TB with --si *sync* <path>:: -Force a sync of the filesystem at 'path'. This is done via a special ioctl and -will also trigger cleaning of deleted subvolumes. Besides that it's equivalent -to the `sync`(1) command. +Force a sync of the filesystem at 'path'. This should be the same as vanilla +'sync' command, but only for specified btrfs. *usage* [options] <path> [<path>...]:: Show detailed information about internal filesystem usage. This is supposed to
Signature · 1 line
2.25.0
Quoted 34 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.That's not true, even at that commit,
btrfs fi synconly callsBTRFS_IOC_SYNCioctl, which is not that much different from vanilla sync.
It doesn't wait for orphan subvolumes to be dropped from the very beginning.It's
btrfs subvolume syncdoing the wait work.Reported-by Nikolay Borisov <[email protected]>Fixes ecd4bb607f35 ("btrfs-progs: docs: enhance btrfs-filesystem manual page")Signed-off-by Qu Wenruo <[email protected]>--- Documentation/btrfs-filesystem.asciidoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)Documentation/btrfs-filesystem.asciidoc +0
-1@@ -253,9 +253,8 @@ show sizes in GiB, or GB with --si show sizes in TiB, or TB with --si *sync* <path>:: -Force a sync of the filesystem at 'path'. This is done via a specialioctl and
-will also trigger cleaning of deleted subvolumes. Besides that it's equivalentDocumentation/btrfs-filesystem.asciidoc +1
-1-to the `sync`(1) command. +Force a sync of the filesystem at 'path'. This should be the same as
Quoted 1 line
vanilla
^^^^^^
As a user I don't like the use of "should" here. Can we not keep the wording of "is equivalent to the sync(1) command [but only for the specified btrfs filesystem]"?
Signature · 1 line
Steven Davies
Quoted 5 lines
+'sync' command, but only for specified btrfs.
*usage* [options] <path> [<path>...]::
Show detailed information about internal filesystem usage. This is
supposed to
Quoted 29 lines · Steven Davies
Quoted 28 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.That's not true, even at that commit,
btrfs fi synconly callsBTRFS_IOC_SYNCioctl, which is not that much different from vanilla sync.
It doesn't wait for orphan subvolumes to be dropped from the very beginning.It's
btrfs subvolume syncdoing the wait work.Reported-by Nikolay Borisov <[email protected]>Fixes ecd4bb607f35 ("btrfs-progs: docs: enhance btrfs-filesystemmanual page")
Signed-off-by Qu Wenruo <[email protected]>---
Documentation/btrfs-filesystem.asciidoc | 5 ++---1 file changed, 2 insertions(+), 3 deletions(-)Documentation/btrfs-filesystem.asciidoc +0
-0@@ -253,9 +253,8 @@ show sizes in GiB, or GB with --sishow sizes in TiB, or TB with --si
Quoted 13 lines
Quoted 8 lines
*sync* <path>::
-Force a sync of the filesystem at 'path'. This is done via a special ioctl and
-will also trigger cleaning of deleted subvolumes. Besides that it's equivalentDocumentation/btrfs-filesystem.asciidoc +1
-1-to the `sync`(1) command. +Force a sync of the filesystem at 'path'. This should be the same asvanilla
^^^^^^ As a user I don't like the use of "should" here. Can we not keep the wording of "is equivalent to the
sync(1)command [but only for the specified btrfs filesystem]"?
From the view point of code, it's a little different. It also wakes up cleaner thread.
But despite that, to end user, it's equivalent.
Thanks,
Qu
Quoted 3 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.
But this is not what the docs say, nor what the ioctl claims to do.
'trigger cleaning of deleted subvolumes' means that it just starts the process in some way (eg. by waking up the cleaner kthread that does the actual cleaning).
For waiting on the subvolumes there's 'btrfs subvol sync' and that works as expected.
Quoted 5 lines · David Sterba
Quoted 3 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.
Quoted 8 lines
But this is not what the docs say, nor what the ioctl claims to do.
'trigger cleaning of deleted subvolumes' means that it just starts the process in some way (eg. by waking up the cleaner kthread that does the actual cleaning).
For waiting on the subvolumes there's 'btrfs subvol sync' and that works as expected.
I agree. The original wording may be unclear (particularly so for users who may have limited English and be confused by the use of "trigger"), but it does seem to be different from sync(1) and the proposed change is worse.
How about:
Force a sync of the filesystem at 'path', similar to the sync(1) command. In addition, it starts cleaning of deleted subvolumes. To wait for subvolume deletion to complete use the btrfs subvolume sync command.
SEE ALSO
btrfs-subvolume(8)
Quoted 20 lines · Graham Cobb
Quoted 5 lines · David Sterba
Quoted 3 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.Quoted 8 lines
But this is not what the docs say, nor what the ioctl claims to do.
'trigger cleaning of deleted subvolumes' means that it just starts the process in some way (eg. by waking up the cleaner kthread that does the actual cleaning).
For waiting on the subvolumes there's 'btrfs subvol sync' and that works as expected.
I agree. The original wording may be unclear (particularly so for users who may have limited English and be confused by the use of "trigger"), but it does seem to be different from sync(1) and the proposed change is worse.
Quoted 8 lines
How about:
Force a sync of the filesystem at 'path', similar to the
sync(1) command. In addition, it starts cleaning of deleted subvolumes. To wait for subvolume deletion to complete use thebtrfs subvolume synccommand.SEE ALSO
btrfs-subvolume(8)
That's perfect, thanks. I'll update the docs.
Quoted 10 lines · David Sterba
Quoted 3 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.But this is not what the docs say, nor what the ioctl claims to do.
'trigger cleaning of deleted subvolumes' means that it just starts the process in some way (eg. by waking up the cleaner kthread that does the actual cleaning).
Then at least we shouldn't really confuse the end user (me included) about the cleanup.
In fact the cleaner wake up doesn't really have a user-observable impact. We should at least avoid mentioning such thing.
Thanks,
Q
Quoted 4 lines
For waiting on the subvolumes there's 'btrfs subvol sync' and that works as expected.
Quoted 8 lines · Qu Wenruo
Quoted 5 lines · David Sterba
Quoted 3 lines · Qu Wenruo
Since commit
ecd4bb607f35("btrfs-progs: docs: enhance btrfs-filesystem manual page"), the man page ofbtrfs filesystemshowssyncsubcommand will wait for all existing orphan subvolumes to be dropped.
Quoted 8 lines
Quoted 5 lines
But this is not what the docs say, nor what the ioctl claims to do.
'trigger cleaning of deleted subvolumes' means that it just starts the process in some way (eg. by waking up the cleaner kthread that does the actual cleaning).
Then at least we shouldn't really confuse the end user (me included) about the cleanup.
Yeah, documentation improvements are welcome.
Quoted 1 line
In fact the cleaner wake up doesn't really have a user-observable impact.
The observable impact is that the cleaning starts immediatelly and not after the periodic wakeup. This was the original intention behind 2fad4e83e1259 ("btrfs: wake up transaction thread from SYNC_FS ioctl"). I don't remember exactly, maybe it was on IRC somebody asking for it.
Quoted 1 line
We should at least avoid mentioning such thing.
That there's some connection between 'fi sync' and the cleaning should be IMHO mentioned in the docs. The tools provide some commands as building blocks and some as all-in-one, so there should be enough information to let user decide what to do.
It's not easy to find the balance between the level of detail and amount of related information, also to maintain consistency accross all documents. As if writing documentation is hard, idk.