summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-inspect-internal.8
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-inspect-internal.8')
-rw-r--r--Documentation/btrfs-inspect-internal.8355
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)