[PATCH v3 1/8] Btrfs-progs: add missing man page information for btrfsck

[PATCH v3 1/8] Btrfs-progs: add missing man page information for btrfsck

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: availiable parts is not true anymore,remove it.
v1->v2: remove wrong copyrights.
---
 man/btrfsck.8.in | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/man/btrfsck.8.in b/man/btrfsck.8.in
index 5004ba0..bf65e3c 100644
--- a/man/btrfsck.8.in
+++ b/man/btrfsck.8.in
@@ -1,16 +1,29 @@
 .TH BTRFSCK 8
 .SH NAME
-btrfsck \- check a btrfs filesystem
+btrfsck \- check and repair of a Btrfs filesystem
 .SH SYNOPSIS
-.B btrfsck \fI device\fP
+.B btrfsck [\fIoptions\fP] \fI<device>\fP
 .SH DESCRIPTION
-\fBbtrfsck\fP is used to check a btrfs filesystem.
-\fIdevice\fP is the device file where the filesystem is stored.
-.SH AVAILABILITY
-.B btrfsck
-is part of btrfs-progs. Btrfs is currently under heavy development,
-and not suitable for any uses other than benchmarking and review.
-Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
-further details.
+\fBbtrfsck\fP is used to check and optionally repair of a Btrfs filesystem. Now, it can only be run on an unmounted FS. Considering it is not well-tested
+in real-life situations yet. if you have a broken Btrfs filesystem, btrfsck may not repair but cause aditional damages. \fI<device>\fP is the device file
+where the filesystem is stored.
+
+\fIOptions\fP
+.IP "\fB-s,--super \fI<superblock>\fP" 5
+specify which superblock copy that you want to use.
+.IP "\fB--repair\fP" 5
+try to repair the filesystem.
+.IP "\fB--init-csum-tree\fP" 5
+create a new CRC tree.
+.IP "\fB--init-extent-tree\fP" 5
+create a new extent tree.
+
+.SH EXIT CODE
+\fBbtrfsck\fR will return 0 exit code if no error happened.
+Other exit code means some problems happened.
+
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
 .SH SEE ALSO
-.BR mkfs.btrfs (8)
+.BR mkfs.btrfs (8),
+.BR btrfs (8)
-- 
1.8.0.1

[PATCH v3 2/8] Btrfs-progs: add missing man information for btrfs-debug-tree

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts.
v1->v2: GPLv3->GPLv2
---
 btrfs-debug-tree.c        |  2 +-
 man/Makefile              |  3 ++-
 man/btrfs-debug-tree.8.in | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 man/btrfs-debug-tree.8.in

diff --git a/btrfs-debug-tree.c b/btrfs-debug-tree.c
index bae7f94..dc912f1 100644
--- a/btrfs-debug-tree.c
+++ b/btrfs-debug-tree.c
@@ -195,7 +195,7 @@ int main(int ac, char **av)
 		if (!leaf) {
 			fprintf(stderr, "failed to read %llu\n",
 				(unsigned long long)block_only);
-			return 0;
+			exit(1);
 		}
 		btrfs_print_tree(root, leaf, 0);
 		return 0;
diff --git a/man/Makefile b/man/Makefile
index 1ba23b5..e5c1f7c 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -11,7 +11,8 @@ man8dir = $(mandir)/man8
 # list only those we use
 .SUFFIXES: .in .gz
 
-MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz
+MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
+	   btrfs-debug-tree.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-debug-tree.8.in b/man/btrfs-debug-tree.8.in
new file mode 100644
index 0000000..9b0420b
--- /dev/null
+++ b/man/btrfs-debug-tree.8.in
@@ -0,0 +1,35 @@
+.TH BTRFS-DEBUG-TREE 8
+.SH NAME
+btrfs-debug-tree \- dump Btrfs filesystem metadata into stdout.
+.SH SYNOPSIS
+.B btrfs-debug-tree [\fIoptions\fP] \fI<device>\fP
+.SH DESCRIPTION
+\fBbtrfs-debug-tree\fP is used to dump the whole tree of the given device.
+This is maybe useful for analyzing filesystem state or inconsistence and has
+a positive educational effect on understanding the internal structure.
+\fIdevice\fP is the device file where the filesystem is stored.
+
+\fIOptions\fP
+.IP "\fB-e\fP" 5
+print detailed extents info.
+.IP "\fB-d\fP" 5
+print info of btrfs device and root tree dirs only.
+.IP "\fB-r\fP" 5
+print info of roots only.
+.IP "\fB-b \fI<block_num>\fP" 5
+print info of the specified block only.
+
+.SH EXIT CODE
+\fBbtrfs-debug-tree\fP will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 3/8] Btrfs-progs: add missing man page for btrfs-show-super

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts
v1->v2: GPLv3->GPLv2
---
 man/Makefile              |  2 +-
 man/btrfs-show-super.8.in | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfs-show-super.8.in

diff --git a/man/Makefile b/man/Makefile
index e5c1f7c..b1d3645 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -12,7 +12,7 @@ man8dir = $(mandir)/man8
 .SUFFIXES: .in .gz
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
-	   btrfs-debug-tree.8.gz
+	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-show-super.8.in b/man/btrfs-show-super.8.in
new file mode 100644
index 0000000..ad04a42
--- /dev/null
+++ b/man/btrfs-show-super.8.in
@@ -0,0 +1,30 @@
+.TH BTRFS-SHOW-SUPER 8
+.SH NAME
+btrfs-show-super \- show btrfs superblock information stored in devices
+.SH SYNOPSIS
+.B btrfs-show-super [\fIoptions\fP] \fI<dev>\fP [\fI<dev>...\fP]
+.SH DESCRIPTION
+\fBbtrfs-show-super\fP is used to print the information of superblock,
+you can specify which mirror to print out. In default, every device's
+first superblock will be printed out.
+
+\fIOptions\fP
+.IP "\fB-a\fP" 5
+print all the superblock information, if this option is given, '\fB-i\fP' option will be ignored.
+.IP "\fB-i \fI<super_mirror>\fP" 5
+specify which mirror to print out. \fI<super_mirror>\fP is between 0 and 2. if several '\fB-i \fI<super_mirror>\fP'\fR are given, only the last one is valid.
+
+.SH EXIT CODE
+\fBbtrfs-show-super\fR will return 0 exit code if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 4/8] Btrfs-progs: add man page information for btrfs-find-root

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts
v1->v2: GPLv3->GPLv2
---
 man/Makefile             |  2 +-
 man/btrfs-find-root.8.in | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfs-find-root.8.in

diff --git a/man/Makefile b/man/Makefile
index b1d3645..3d2e3ba 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -12,7 +12,7 @@ man8dir = $(mandir)/man8
 .SUFFIXES: .in .gz
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
-	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz
+	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-find-root.8.in b/man/btrfs-find-root.8.in
new file mode 100644
index 0000000..398aa41
--- /dev/null
+++ b/man/btrfs-find-root.8.in
@@ -0,0 +1,30 @@
+.TH BTRFS-FIND-ROOT 8
+.SH NAME
+btrfs-find-root \- filter to find btrfs root.
+.SH SYNOPSIS
+.B btrfs-find-root [\fIoptions\fP] \fI<dev>\fP
+.SH DESCRIPTION
+\fBbtrfs-find-root\fP is used to find the satisfied root, you can filter by root tree's objectid, generation, level.
+
+\fIOptions\fP
+.IP "\fB-g \fI<generation>\fP" 5
+filter root tree by it's original transaction id, tree root's generation in default.
+.IP "\fB-o \fI<objectid>\fP" 5
+filter root tree by it's objectid,tree root's objectid in default.
+.IP "\fB-l \fI<level>\fP" 5
+filter root tree by B-+ tree's level, level 0 in default.
+
+.SH EXIT CODE
+\fBbtrfs-find-root\fP will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 5/8] Btrfs-progs: add man page information for btrfs-convert

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts.
v1->v2: GPLv3->GPLv2
---
 man/Makefile           |  3 ++-
 man/btrfs-convert.8.in | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfs-convert.8.in

diff --git a/man/Makefile b/man/Makefile
index 3d2e3ba..a2201e8 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -12,7 +12,8 @@ man8dir = $(mandir)/man8
 .SUFFIXES: .in .gz
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
-	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz
+	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz \
+	   btrfs-convert.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-convert.8.in b/man/btrfs-convert.8.in
new file mode 100644
index 0000000..9d4c642
--- /dev/null
+++ b/man/btrfs-convert.8.in
@@ -0,0 +1,33 @@
+.TH BTRFS-CONVERT 8
+.SH NAME
+btrfs-convert \- convert ext2/3/4 to btrfs.
+.SH SYNOPSIS
+.B btrfs-convert [\fIoptions\fP] \fI<dev>\fP
+.SH DESCRIPTION
+\fBbtrfs-convert\fP is used to convert existed ext2/3/4 to btrfs filesystem, and the original filesystem image is accessible as from separate subvolume named ext2_subvol as file image.
+
+\fIOptions\fP
+.IP "\fB-d\fP" 5
+disable data checksum.
+.IP "\fB-i\fP" 5
+ignore xattrs and ACLs.
+.IP "\fB-n\fP" 5
+disable packing of small files.
+.IP "\fB-r\fP" 5
+roll back to ext2fs.
+
+.SH EXIT CODE
+\fBbtrfs-convert\fP will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 6/8] Btrfs-progs: add missing man page for btrfstune

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts.
v1->v2: GPLv3->GPLv2
---
 man/Makefile       |  2 +-
 man/btrfstune.8.in | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfstune.8.in

diff --git a/man/Makefile b/man/Makefile
index a2201e8..e1246db 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -13,7 +13,7 @@ man8dir = $(mandir)/man8
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
 	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz \
-	   btrfs-convert.8.gz
+	   btrfs-convert.8.gz btrfstune.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfstune.8.in b/man/btrfstune.8.in
new file mode 100644
index 0000000..d4b2b7c
--- /dev/null
+++ b/man/btrfstune.8.in
@@ -0,0 +1,31 @@
+.TH BTRFSTUNE 8
+.SH NAME
+btrfstune \- tune various filesystem parameters.
+.SH SYNOPSIS
+.B btrfstune [\fIoptions\fP] \fI<mnt>\fP
+.SH DESCRIPTION
+\fBbtrfstune\fP is used to tune various filesystem parameters,you can
+enable/disable some extended features for btrfs.
+
+\fIOptions\fP
+.IP "\fB-S \fI<value>\fP" 5
+updates the seeding value, it forces a fs readonly so that you can use it to build other filesystems.
+.IP "\fB-r\fP" 5
+enable extended inode refs.
+.IP "\fB-x\fP" 5
+enable skinny metadata extent refs.
+
+.SH EXIT CODE
+\fBbtrfstune\fP will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 7/8] Btrfs-progs: add missing man page information for btrfs-zero-log

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts.
v1->v2: GPLv3->GPLv2
---
 man/Makefile            |  2 +-
 man/btrfs-zero-log.8.in | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfs-zero-log.8.in

diff --git a/man/Makefile b/man/Makefile
index e1246db..5ccb60a 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -13,7 +13,7 @@ man8dir = $(mandir)/man8
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
 	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz \
-	   btrfs-convert.8.gz btrfstune.8.gz
+	   btrfs-convert.8.gz btrfstune.8.gz btrfs-zero-log.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-zero-log.8.in b/man/btrfs-zero-log.8.in
new file mode 100644
index 0000000..80aaa9a
--- /dev/null
+++ b/man/btrfs-zero-log.8.in
@@ -0,0 +1,23 @@
+.TH BTRFS-ZERO-LOG 8
+.SH NAME
+btrfs-zero-log \- clear out log tree.
+.SH SYNOPSIS
+.B btrfs-zero-log \fI <dev>\fP
+.SH DESCRIPTION
+\fBbtrfs-zero-log\fP will remove the log tree if log tree is corrupt, which will allow you to mount the filesystem again. The common case where this
+happens has been fixed a long time ago, so it is unlikely that you will see this particular problem.
+
+.SH EXIT CODE
+\fBbtrfs-zero-log\fR will return 0 exit code if no error happened.
+Other exit code means some problems happened.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

[PATCH v3 8/8] Btrfs-progs: add missing man page for btrfs-map-logical

[Wang Shilong]

Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2->v3: remove 'AVAILIABLE' parts.
v1->v2: GPLv3->GPLv2
---
 man/Makefile               |  2 +-
 man/btrfs-map-logical.8.in | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 man/btrfs-map-logical.8.in

diff --git a/man/Makefile b/man/Makefile
index 5ccb60a..690fa65 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -13,7 +13,7 @@ man8dir = $(mandir)/man8
 
 MANPAGES = mkfs.btrfs.8.gz btrfsck.8.gz btrfs-image.8.gz btrfs.8.gz \
 	   btrfs-debug-tree.8.gz btrfs-show-super.8.gz btrfs-find-root.8.gz \
-	   btrfs-convert.8.gz btrfstune.8.gz btrfs-zero-log.8.gz
+	   btrfs-convert.8.gz btrfstune.8.gz btrfs-zero-log.8.gz btrfs-map-logical.8.gz
 INFILES = ${MANPAGES:.in=.gz}
 
 all: $(MANPAGES)
diff --git a/man/btrfs-map-logical.8.in b/man/btrfs-map-logical.8.in
new file mode 100644
index 0000000..d50ac96
--- /dev/null
+++ b/man/btrfs-map-logical.8.in
@@ -0,0 +1,33 @@
+.TH BTRFS-MAP-LOGICAL 8
+.SH NAME
+btrfs-map-logical \- map btrfs logical extent to physical extent
+.SH SYNOPSIS
+.B btrfs-map-logical [\fIoptions\fP] \fI<device>\fP
+.SH DESCRIPTION
+\fBbtrfs-map-logical\fP can be used to find out what the physical offsets are
+on the mirrors, the result is dumped into stdout in default.
+
+\fIOptions\fP
+.IP "\fB-l|--logical \fI<logical_num>\fP" 5
+Logical extent to map.
+.IP "\fB-c|--copy \fI<copy>\fP" 5
+Copy of the extent to read(usually 1 or 2).
+.IP "\fB-o|--output \fI<filename>\fP" 5
+Output file to hold the extent.
+.IP "\fB-b|--bytes \fI<bytes>\fP" 5
+Number of bytes to read.
+
+.SH EXIT CODE
+\fBbtrfs-map-logical\fP will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+.SH AUTHOR
+Written by Shilong Wang and Wenruo Qu.
+
+.SH COPYRIGHT
+Copyright \(co 2013 Fujitsu, Inc.
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.btrfs (8)
-- 
1.8.0.1

Re: [PATCH v3 1/8] Btrfs-progs: add missing man page information for btrfsck

[David Sterba]

On Wed, Aug 14, 2013 at 12:29:10PM +0800, Wang Shilong wrote:
> Signed-off-by: Wang Shilong <wangsl.fnst@cn.fujitsu.com>
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
> ---
> v2->v3: availiable parts is not true anymore,remove it.
> v1->v2: remove wrong copyrights.

Thanks for the updates, I've put the series into integration.

Note for future:

The manpages document the current state, ie. there are numerous separate
utilities which we would like to move under the main tool. When it
happens the man contents shall be moved as well.

david