btrfs-progs: random fixes of btrfs-filesystem documentation

PATCH Superseded Satoru Takeuchi 4 participants 13 messages Aug 11, 2014 – Aug 20, 2014

Subsystems (2)

Documentation Btrfs file system

lore

Share & tools

lore

Satoru Takeuchi

author

2014-08-11 09:11 UTC #0 lore raw

PATCH 1/3 btrfs-progs: random fixes of btrfs-filesystem documentation

From: Satoru Takeuchi <[email protected]>

- Simplify and unify the description of both man and usage.
- Fix to show -m and -d is not exclusive
with "<path>|<uuid>|<device>|<label>".
- Add the description about short options for "--mounted" and "--all-devices", "-m" and "-d" respectively.
- Move the descriptions of options to "Options" section.

Signed-off-by Satoru Takeuchi <[email protected]>

---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)

Documentation/btrfs-filesystem.txt +14 -8

index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
++
+`Options`
++
+-d|--alldevices::::
+scan all the devices under /dev
+-m|--mounted:::: 
+scan only mounted filesystems
 
 *sync* <path>::
 Force a sync for the filesystem identified by <path>.

cmds-filesystem.c +10 -5

index 38011e5..5a80a98 100644
@@ -578,11 +578,16 @@ out:
 }
 
 static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows",
+	"information of all the btrfs filesystems both mounted and unmounted.",
+	"",
+	"The show command finds btrfs filesystems by scanning all the devices",
+	"in /proc/partitions by default.",
+	"",
+	"-d|--all-devices   scan all the devices under /dev",
+	"-m|--mounted       scan only mounted filesystems",
 	NULL
 };

Signature · 1 line

1.9.3

Eric Sandeen

2014-08-11 17:05 UTC #1 lore raw

Quoted 28 lines · Satoru Takeuchi

From: Satoru Takeuchi <[email protected]>
- Simplify and unify the description of both man and usage.
- Fix to show -m and -d is not exclusive
with "<path>|<uuid>|<device>|<label>".
- Add the description about short options for "--mounted" and "--all-devices", "-m" and "-d" respectively.
- Move the descriptions of options to "Options" section.
Signed-off-by Satoru Takeuchi <[email protected]>
---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)
Documentation/btrfs-filesystem.txt +2 -2
index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).

Documentation/btrfs-filesystem.txt SUBCOMMAND · line 28

Quoted 10 lines

Documentation/btrfs-filesystem.txt +2 -6

 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
 
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.

that doesn't seem quite correct;

# btrfs filesystem show -m

does not specify '<path>|<uuid>|<device>|<label>' but it only shows mounted filesystems, not all filesystems.

As I understand it, the -d and -m options control how the command finds devices; the '<path>|<uuid>|<device>|<label>' argument is used as a filter for what is found.

Documentation/btrfs-filesystem.txt SUBCOMMAND · line 30

Quoted 3 lines

Documentation/btrfs-filesystem.txt +3 -0

++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.

I think I would document it something like this:

show [-m|-d] [<path>|<uuid>|<device>|<label>]
Show the structure of btrfs filesystem(s).

By default, the show command scans all devices found in /proc/partitions. If [-d|--all-devices] is specified, all devices found under /dev are scanned. If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.

By default, the structure of all discovered filesystems is shown. If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems matching that identifier are shown.

(What seems to be missing, though, is why would the user ever choose to use '-d?')

-Eric

Eric Sandeen

2014-08-11 17:14 UTC #2 lore raw

Quoted 64 lines · Eric Sandeen

Quoted 28 lines · Satoru Takeuchi
From: Satoru Takeuchi <[email protected]>
- Simplify and unify the description of both man and usage.
- Fix to show -m and -d is not exclusive
with "<path>|<uuid>|<device>|<label>".
- Add the description about short options for "--mounted" and "--all-devices", "-m" and "-d" respectively.
- Move the descriptions of options to "Options" section.
Signed-off-by Satoru Takeuchi <[email protected]>
---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)
Documentation/btrfs-filesystem.txt +2 -2
index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
Documentation/btrfs-filesystem.txt SUBCOMMAND · line 28
Quoted 10 lines
Documentation/btrfs-filesystem.txt +2 -6
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
 
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
that doesn't seem quite correct;
# btrfs filesystem show -m
does not specify '<path>|<uuid>|<device>|<label>' but it only shows mounted filesystems, not all filesystems.
As I understand it, the -d and -m options control how the command finds devices; the '<path>|<uuid>|<device>|<label>' argument is used as a filter for what is found.
Documentation/btrfs-filesystem.txt SUBCOMMAND · line 30
Quoted 3 lines
Documentation/btrfs-filesystem.txt +3 -0
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
I think I would document it something like this:
show [-m|-d] [<path>|<uuid>|<device>|<label>]
Show the structure of btrfs filesystem(s).
By default, the show command scans all devices found in /proc/partitions. If [-d|--all-devices] is specified, all devices found under /dev are scanned. If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.

Quoted 5 lines

By default, the structure of all discovered filesystems is shown. If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems matching that identifier are shown.
(What seems to be missing, though, is why would the user ever choose to use '-d?')

Incidentally, there is some strange behavior here when looking for multiple filesystems which match.

Make 2 filesystems w/ the same label:

[root@bp-05 tmp]# btrfs filesystem label /dev/sdc1 testlabel2 [root@bp-05 tmp]# btrfs filesystem label /dev/sdc5 testlabel2

Show matching filesytems:

[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
Total devices 1 FS bytes used 112.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc5

Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1

Btrfs v3.14.2

That works fine, but if one is mounted:

[root@bp-05 tmp]# mount /dev/sdc1 /mnt/test

only the mounted filesystem is shown:

[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1

Btrfs v3.14.2

That's unexpected.

Mount the other fs, and both are shown again:

[root@bp-05 tmp]# mount /dev/sdc5 /mnt/scratch [root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1

Label: 'testlabel2' uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc5

Btrfs v3.14.2

-Eric

Satoru Takeuchi

author

2014-08-11 23:55 UTC #3 lore raw

Hi Eric,

Quoted 114 lines · Eric Sandeen

Quoted 64 lines · Eric Sandeen
Quoted 28 lines · Satoru Takeuchi
From: Satoru Takeuchi <[email protected]>
- Simplify and unify the description of both man and usage.
- Fix to show -m and -d is not exclusive
    with "<path>|<uuid>|<device>|<label>".
  - Add the description about short options for "--mounted" and
    "--all-devices", "-m" and "-d" respectively.
- Move the descriptions of options to "Options" section.
Signed-off-by Satoru Takeuchi <[email protected]>
---
  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
  cmds-filesystem.c                  | 15 ++++++++++-----
  2 files changed, 24 insertions(+), 13 deletions(-)
Documentation/btrfs-filesystem.txt +2 -2
index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
  *df* <path> [<path>...]::
  Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
Documentation/btrfs-filesystem.txt SUBCOMMAND · line 28
Quoted 10 lines
Documentation/btrfs-filesystem.txt +2 -6
  +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
 
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
that doesn't seem quite correct;
# btrfs filesystem show -m
does not specify '<path>|<uuid>|<device>|<label>' but it only shows mounted filesystems, not all filesystems.
As I understand it, the -d and -m options control how the command finds devices; the '<path>|<uuid>|<device>|<label>' argument is used as a filter for what is found.
Documentation/btrfs-filesystem.txt SUBCOMMAND · line 30
Quoted 3 lines
Documentation/btrfs-filesystem.txt +3 -0
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
I think I would document it something like this:
show [-m|-d] [<path>|<uuid>|<device>|<label>]
Show the structure of btrfs filesystem(s).
By default, the show command scans all devices found in /proc/partitions. If [-d|--all-devices] is specified, all devices found under /dev are scanned. If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.
Quoted 5 lines
By default, the structure of all discovered filesystems is shown. If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems matching that identifier are shown.
(What seems to be missing, though, is why would the user ever choose to use '-d?')
Incidentally, there is some strange behavior here when looking for multiple filesystems which match.
Make 2 filesystems w/ the same label:
[root@bp-05 tmp]# btrfs filesystem label /dev/sdc1 testlabel2 [root@bp-05 tmp]# btrfs filesystem label /dev/sdc5 testlabel2
Show matching filesytems:
[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
Total devices 1 FS bytes used 112.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc5
Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1
Btrfs v3.14.2
That works fine, but if one is mounted:
[root@bp-05 tmp]# mount /dev/sdc1 /mnt/test
only the mounted filesystem is shown:
[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1
Btrfs v3.14.2
That's unexpected.
Mount the other fs, and both are shown again:
[root@bp-05 tmp]# mount /dev/sdc5 /mnt/scratch [root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2' uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc1

Quoted 5 lines

Label: 'testlabel2' uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
Total devices 1 FS bytes used 384.00KiB
devid 1 size 30.00GiB used 2.04GiB path /dev/sdc5
Btrfs v3.14.2

I'll dig into it. Thank you for let me know.

Satoru

Quoted 8 lines

-Eric
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

Satoru Takeuchi

author

2014-08-11 23:51 UTC #4 lore raw

In reply to Eric Sandeen

Hi Eric,

Quoted 42 lines · Eric Sandeen

Quoted 28 lines · Satoru Takeuchi

From: Satoru Takeuchi <[email protected]>

- Simplify and unify the description of both man and usage.
- Fix to show -m and -d is not exclusive

    with "<path>|<uuid>|<device>|<label>".
  - Add the description about short options for "--mounted" and
    "--all-devices", "-m" and "-d" respectively.

- Move the descriptions of options to "Options" section.

Signed-off-by Satoru Takeuchi <[email protected]>

---
  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
  cmds-filesystem.c                  | 15 ++++++++++-----
  2 files changed, 24 insertions(+), 13 deletions(-)

Documentation/btrfs-filesystem.txt +2 -2

index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
  *df* <path> [<path>...]::
  Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).

Documentation/btrfs-filesystem.txt SUBCOMMAND · line 28

Quoted 10 lines

Documentation/btrfs-filesystem.txt +2 -6

  +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
 
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.

that doesn't seem quite correct;

Quoted 4 lines

# btrfs filesystem show -m
does not specify '<path>|<uuid>|<device>|<label>' but it only shows mounted filesystems, not all filesystems.

Oh, I forgot to add "[" and "]".

Quoted 4 lines

As I understand it, the -d and -m options control how the command finds devices; the '<path>|<uuid>|<device>|<label>' argument is used as a filter for what is found.

Yes, my understanding is so too.

Quoted 10 lines

Documentation/btrfs-filesystem.txt SUBCOMMAND · line 30
Quoted 4 lines
Documentation/btrfs-filesystem.txt +3 -0
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
I think I would document it something like this:
show [-m|-d] [<path>|<uuid>|<device>|<label>]
Show the structure of btrfs filesystem(s).

Quoted 7 lines

By default, the show command scans all devices found in /proc/partitions. If [-d|--all-devices] is specified, all devices found under /dev are scanned. If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.
By default, the structure of all discovered filesystems is shown. If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems matching that identifier are shown.

OK, I'll fix my patch based on your comment.
# Of course, I'll replace "(btrfs?)" with something proper words.

Can I add your "Signed-off-by" to my v2 patch?

Quoted 2 lines

(What seems to be missing, though, is why would the user ever choose to use '-d?')

I'm not sure. I guess, for example, in large systems, -d takes too many times for scanning all devices under /dev or something?

Thank you for your comments!

Satoru

Quoted 3 lines

-Eric

Eric Sandeen

2014-08-12 00:07 UTC #5 lore raw

Quoted 6 lines · Satoru Takeuchi

Hi Eric,

...

Quoted 4 lines

OK, I'll fix my patch based on your comment.
# Of course, I'll replace "(btrfs?)" with something proper words.

I assumed it only scans btrfs but didn't know for sure :)

Quoted 1 line

Can I add your "Signed-off-by" to my v2 patch?

Oh, sure, if you use my text, that makes sense.

thanks,
-Eric

Quoted 13 lines

Quoted 2 lines
(What seems to be missing, though, is why would the user ever choose to use '-d?')
I'm not sure. I guess, for example, in large systems, -d takes too many times for scanning all devices under /dev or something?
Thank you for your comments!
Satoru
Quoted 2 lines
-Eric

Satoru Takeuchi

author

2014-08-12 07:25 UTC #6 lore raw

PATCH v2 1/3 btrfs-progs: random fixes of btrfs-filesystem documentation

From: Satoru Takeuchi <[email protected]>

- Simplify the description of both man and usage.
- Add the description about short options for '--all-devices and '--mounted', '-d' and '-m' respectively.
- Fix to show -d and -m is not exclusive
with '<path>|<uuid>|<device>|<label>'.
- Move the descriptions of options to "Options" section in manpage.

Signed-off-by Satoru Takeuchi <[email protected]>

Signed-off-by Eric Sandeen <[email protected]>

---
changelog:
- v2: Fix the description based on Eric's comment

---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)

Documentation/btrfs-filesystem.txt +14 -8

index c9c0b00..fe68496 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
++
+`Options`
++
+-d|--alldevices::::
+scan all the devices under /dev
+-m|--mounted::::
+scan only mounted filesystems
 
 *sync* <path>::
 Force a sync for the filesystem identified by <path>.

cmds-filesystem.c +10 -5

index 38011e5..3e9f33b 100644
@@ -578,11 +578,16 @@ out:
 }
 
 static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
 	NULL
 };

Signature · 1 line

1.9.3

Satoru Takeuchi

author

2014-08-12 07:46 UTC #7 lore raw

PATCH v3 1/3 btrfs-progs: random fixes of btrfs-filesystem documentation

Oops, I sent a wrong patch. Here is the correct one.

===
From: Satoru Takeuchi <[email protected]>

- Simplify the description of both man and usage.
- Add the description about short options for '--all-devices' and '--mounted', '-d' and '-m' respectively.
- Fix to show -d and -m is not exclusive
with '<path>|<uuid>|<device>|<label>'.
- Move the descriptions of options to "Options" section in manpage.

Signed-off-by Satoru Takeuchi <[email protected]>

Signed-off-by Eric Sandeen <[email protected]>

---
changelog:
- v2: Fix the description based on Eric's comment
- v3: Fix the incomplete update of btrfs-filesystem.txt

---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 Documentation/btrfs-replace.txt    |  1 +
 cmds-filesystem.c                  | 15 ++++++++++-----
 3 files changed, 25 insertions(+), 13 deletions(-)

Documentation/btrfs-filesystem.txt +14 -8

index c9c0b00..63cb91e 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+By default, the show command scans all devices found in /proc/partitions.
++
+By default, the structure of all discovered filesystems is shown.
+If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
+matching that identifier are shown.
++
+`Options`
++
+-d|--all-devices::::
+all devices found under /dev are scanned
+-m|--mounted::::
+only mounted btrfs devices are scanned
 
 *sync* <path>::
 Force a sync for the filesystem identified by <path>.

Documentation/btrfs-replace.txt +1 -0

index eecf9b0..476e351 100644
@@ -49,6 +49,7 @@ containing a valid btrfs filesystem.
 A valid filesystem is assumed if a btrfs superblock is found which contains a
 correct checksum. Devices which are currently mounted are
 never allowed to be used as the <targetdev>.
++
 -B::::
 no background replace.

cmds-filesystem.c +10 -5

index 38011e5..3e9f33b 100644
@@ -578,11 +578,16 @@ out:
 }
 
 static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
 	NULL
 };

Signature · 1 line

1.9.3

Satoru Takeuchi

author

2014-08-12 08:06 UTC #8 lore raw

PATCH v4 1/3 btrfs-progs: random fixes of btrfs-filesystem documentation

Here is the *really* correct one. I seems to need a break ;-(

===
From: Satoru Takeuchi <[email protected]>

Signed-off-by Satoru Takeuchi <[email protected]>

Signed-off-by Eric Sandeen <[email protected]>

---
changelog:
- v2: Fix the description based on Eric's comment.
- v3: Fix the incomplete update of btrfs-filesystem.txt.
- v4: Remove a unnecessary change about btrfs-replace documentation.

---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)

Documentation/btrfs-filesystem.txt +14 -8

index c9c0b00..63cb91e 100644
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+By default, the show command scans all devices found in /proc/partitions.
++
+By default, the structure of all discovered filesystems is shown.
+If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
+matching that identifier are shown.
++
+`Options`
++
+-d|--all-devices::::
+all devices found under /dev are scanned
+-m|--mounted::::
+only mounted btrfs devices are scanned
 
 *sync* <path>::
 Force a sync for the filesystem identified by <path>.

cmds-filesystem.c +10 -5

index 38011e5..3e9f33b 100644
@@ -578,11 +578,16 @@ out:
 }
 
 static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
 	NULL
 };

Signature · 1 line

1.9.3

David Sterba

2014-08-19 15:07 UTC #9 lore raw

Quoted 1 line · Satoru Takeuchi

+By default, the show command scans all devices found in /proc/partitions.

The default scanning method is blkid, /proc/partitions used to be the default before that. Scanning /proc/partitions is not done through the 'show' command, only during open_ctree afaics.

David Sterba

2014-08-19 15:10 UTC #10 lore raw

In reply to Eric Sandeen

Quoted 1 line · Eric Sandeen

(What seems to be missing, though, is why would the user ever choose to use '-d?')

That's a fallback method if blkid or udev are not available. We've had reports in the past that this functionality should not be dropped.

Eric Sandeen

2014-08-19 15:33 UTC #11 lore raw

Quoted 5 lines · David Sterba

Quoted 1 line · Eric Sandeen
(What seems to be missing, though, is why would the user ever choose to use '-d?')
That's a fallback method if blkid or udev are not available. We've had reports in the past that this functionality should not be dropped.

Seems like using /proc/partitions would make more sense in that case than a recursive scan of every file under /dev, wouldn't it? Any details on those reports?

I'm just wondering when you might possibly have success looking deep into the /dev tree if you didn't have success in /proc/partitions.

It looks like the functionality was added with:

commit 0dbd99fb3e117cd5f87eda492b6b4fab1b5bea23

Author: Goffredo Baroncelli <[email protected]>
Date:   Wed Jun 15 21:55:25 2011 +0200

Scan the devices listed in /proc/partitions

During the commands:
- btrfs filesystem show
- btrfs device scan
the devices "scanned" are extracted from /proc/partitions. This should avoid to scan devices not suitable for a btrfs filesystem like cdrom and floppy or to scan not existant devices.
The old behavior (scan all the block devices under /dev) may be forced passing the "--all-devices" switch.

but I'm not sure why it was preserved.

It just seems a bit bizarre to have so many ways to get the same info.

Thanks,
-Eric

David Sterba

2014-08-20 13:22 UTC #12 lore raw

Quoted 3 lines · Eric Sandeen

Seems like using /proc/partitions would make more sense in that case than a recursive scan of every file under /dev, wouldn't it? Any details on those reports?

It does make sense.

Quoted 2 lines

I'm just wondering when you might possibly have success looking deep into the /dev tree if you didn't have success in /proc/partitions.

I haven't figured out any advantage of /dev.

Quoted 1 line

It just seems a bit bizarre to have so many ways to get the same info.

I think keeping blkid as default and /proc/filesystems as fallback should cover the usecases. This meanas that the option -d stays, and the scanning method can be changed to BTRFS_SCAN_PROC (fi show and dev scan).