diff options
Diffstat (limited to 'Documentation/btrfs-inspect-internal.8')
-rw-r--r-- | Documentation/btrfs-inspect-internal.8 | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/Documentation/btrfs-inspect-internal.8 b/Documentation/btrfs-inspect-internal.8 new file mode 100644 index 00000000..3cd467ac --- /dev/null +++ b/Documentation/btrfs-inspect-internal.8 @@ -0,0 +1,355 @@ +'\" t +.\" Title: btrfs-inspect-internal +.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 12/05/2018 +.\" Manual: Btrfs Manual +.\" Source: Btrfs v4.19.1 +.\" Language: English +.\" +.TH "BTRFS\-INSPECT\-INTE" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +btrfs-inspect-internal \- query various internal information +.SH "SYNOPSIS" +.sp +\fBbtrfs inspect\-internal\fR \fI<subcommand>\fR \fI<args>\fR +.SH "DESCRIPTION" +.sp +This command group provides an interface to query internal information\&. The functionality ranges from a simple UI to an ioctl or a more complex query that assembles the result from several internal structures\&. The latter usually requires calls to privileged ioctls\&. +.SH "SUBCOMMAND" +.PP +\fBdump\-super\fR [options] \fI<device>\fR [device\&...] +.RS 4 +(replaces the standalone tool +\fBbtrfs\-show\-super\fR) +.sp +Show btrfs superblock information stored on given devices in textual form\&. By default the first superblock is printed, more details about all copies or additional backup data can be printed\&. +.sp +Besides verification of the filesystem signature, there are no other sanity checks\&. The superblock checksum status is reported, the device item and filesystem UUIDs are checked and reported\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +the meaning of option +\fI\-s\fR +has changed in version 4\&.8 to be consistent with other tools to specify superblock copy rather the offset\&. The old way still works, but prints a warning\&. Please update your scripts to use +\fI\-\-bytenr\fR +instead\&. The option +\fI\-i\fR +has been deprecated\&. +.sp .5v +.RE +\fBOptions\fR +.PP +\-f|\-\-full +.RS 4 +print full superblock information, including the system chunk array and backup roots +.RE +.PP +\-a|\-\-all +.RS 4 +print information about all present superblock copies (cannot be used together with +\fI\-s\fR +option) +.RE +.PP +\-i \fI<super>\fR +.RS 4 +(deprecated since 4\&.8, same behaviour as +\fI\-\-super\fR) +.RE +.PP +\-\-bytenr \fI<bytenr>\fR +.RS 4 +specify offset to a superblock in a non\-standard location at +\fIbytenr\fR, useful for debugging (disables the +\fI\-f\fR +option) +.sp +If there are multiple options specified, only the last one applies\&. +.RE +.PP +\-F|\-\-force +.RS 4 +attempt to print the superblock even if a valid BTRFS signature is not found; the result may be completely wrong if the data does not resemble a superblock +.RE +.PP +\-s|\-\-super \fI<bytenr>\fR +.RS 4 +(see compatibility note above) +.sp +specify which mirror to print, valid values are 0, 1 and 2 and the superblock must be present on the device with a valid signature, can be used together with +\fI\-\-force\fR +.RE +.RE +.PP +\fBdump\-tree\fR [options] \fI<device>\fR +.RS 4 +(replaces the standalone tool +\fBbtrfs\-debug\-tree\fR) +.sp +Dump tree structures from a given device in textual form, expand keys to human readable equivalents where possible\&. This is useful for analyzing filesystem state or inconsistencies and has a positive educational effect on understanding the internal filesystem structure\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +contains file names, consider that if you\(cqre asked to send the dump for analysis\&. Does not contain file data\&. +.sp .5v +.RE +\fBOptions\fR +.PP +\-e|\-\-extents +.RS 4 +print only extent\-related information: extent and device trees +.RE +.PP +\-d|\-\-device +.RS 4 +print only device\-related information: tree root, chunk and device trees +.RE +.PP +\-r|\-\-roots +.RS 4 +print only short root node information, ie\&. the root tree keys +.RE +.PP +\-R|\-\-backups +.RS 4 +same as \-\-roots plus print backup root info, ie\&. the backup root keys and the respective tree root block offset +.RE +.PP +\-u|\-\-uuid +.RS 4 +print only the uuid tree information, empty output if the tree does not exist +.RE +.PP +\-b \fI<block_num>\fR +.RS 4 +print info of the specified block only +.RE +.PP +\-\-follow +.RS 4 +use with +\fI\-b\fR, print all children tree blocks of +\fI\fI<block_num>\fR\fR +.RE +.PP +\-\-dfs +.RS 4 +use depth\-first search to print trees\&. (default) the nodes and leaves are intermixed in the output +.RE +.PP +\-\-bfs +.RS 4 +use breadth\-first search to print trees\&. the nodes are printed before all leaves +.RE +.PP +\-t \fI<tree_id>\fR +.RS 4 +print only the tree with the specified ID, where the ID can be numerical or common name in a flexible human readable form +.sp +The tree id name recognition rules: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +case does not matter +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +the C source definition, eg\&. BTRFS_ROOT_TREE_OBJECTID +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, eg\&. ROOT_TREE, ROOT +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +convenience aliases, eg\&. DEVICE for the DEV tree, CHECKSUM for CSUM +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +unrecognized ID is an error +.RE +.RE +.RE +.PP +\fBinode\-resolve\fR [\-v] \fI<ino>\fR \fI<path>\fR +.RS 4 +(needs root privileges) +.sp +resolve paths to all files with given inode number +\fIino\fR +in a given subvolume at +\fIpath\fR, ie\&. all hardlinks +.sp +\fBOptions\fR +.PP +\-v +.RS 4 +verbose mode, print count of returned paths and ioctl() return value +.RE +.RE +.PP +\fBlogical\-resolve\fR [\-Pv] [\-s \fI<bufsize>\fR] \fI<logical>\fR \fI<path>\fR +.RS 4 +(needs root privileges) +.sp +resolve paths to all files at given +\fIlogical\fR +address in the linear filesystem space +.sp +\fBOptions\fR +.PP +\-P +.RS 4 +skip the path resolving and print the inodes instead +.RE +.PP +\-v +.RS 4 +verbose mode, print count of returned paths and all ioctl() return values +.RE +.PP +\-s \fI<bufsize>\fR +.RS 4 +set internal buffer for storing the file names to +\fIbufsize\fR, default is 4096, maximum 64k +.RE +.RE +.PP +\fBmin\-dev\-size\fR [options] \fI<path>\fR +.RS 4 +(needs root privileges) +.sp +return the minimum size the device can be shrunk to, without performing any resize operation, this may be useful before executing the actual resize operation +.sp +\fBOptions\fR +.PP +\-\-id \fI<id>\fR +.RS 4 +specify the device +\fIid\fR +to query, default is 1 if this option is not used +.RE +.RE +.PP +\fBrootid\fR \fI<path>\fR +.RS 4 +for a given file or directory, return the containing tree root id, but for a subvolume itself return its own tree id (ie\&. subvol id) +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +The result is undefined for the so\-called empty subvolumes (identified by inode number 2), but such a subvolume does not contain any files anyway +.sp .5v +.RE +.RE +.PP +\fBsubvolid\-resolve\fR \fI<subvolid>\fR \fI<path>\fR +.RS 4 +(needs root privileges) +.sp +resolve the absolute path of the subvolume id +\fIsubvolid\fR +.RE +.PP +\fBtree\-stats\fR [options] \fI<device>\fR +.RS 4 +(needs root privileges) +.sp +Print sizes and statistics of trees\&. +.sp +\fBOptions\fR +.PP +\-b +.RS 4 +Print raw numbers in bytes\&. +.RE +.RE +.SH "EXIT STATUS" +.sp +\fBbtrfs inspect\-internal\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&. +.SH "AVAILABILITY" +.sp +\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&. +.SH "SEE ALSO" +.sp +\fBmkfs\&.btrfs\fR(8) |