Documentation/btrfs-inspect-internal.asciidoc

   1 btrfs-inspect-internal(8)
   2 =========================
   3
   4 NAME
   5 ----
   6 btrfs-inspect-internal - query various internal information
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs inspect-internal* <subcommand> <args>
  11
  12 DESCRIPTION
  13 -----------
  14
  15 This command group provides an interface to query internal information. The
  16 functionality ranges from a simple UI to an ioctl or a more complex query that
  17 assembles the result from several internal structures. The latter usually
  18 requires calls to privileged ioctls.
  19
  20 SUBCOMMAND
  21 ----------
  22 *dump-super* [options] <device> [device...]::
  23 (needs root privileges)
  24 +
  25 Show btrfs superblock information stored in devices.
  26 It is used to print the information of superblock,
  27 you can specify which mirror to print out.
  28 +
  29 By default, every device's first superblock will be printed out.
  30 +
  31 Mainly used for debug purpose.
  32 +
  33 `Options`
  34 +
  35 -f::::
  36 Print full superblock information.
  37 +
  38 Including the system chunk array and backup roots.
  39 +
  40 -a::::
  41 Print information of all superblocks.
  42 +
  43 If this option is given, '-i' option will be ignored.
  44 +
  45 -i <super_mirror>::::
  46 Specify which mirror to print out.
  47 +
  48 <super_mirror> is between 0 and 2.
  49 If several '-i <super_mirror>' are given, only the last one is valid.
  50 +
  51 -F::::
  52 Attempt to print the superblock even if no superblock magic is found.  May end
  53 badly.
  54 -s <bytenr>::::
  55 specify offset to a superblock in a non-standard location at 'bytenr', useful
  56 for debugging (disables the '-f' option)
  57
  58 *dump-tree* [options] <device>::
  59 (replaces the standalone tool *btrfs-debug-tree*)
  60 +
  61 Dump tree structures from a given device in textual form, expand keys to human
  62 readable equivalents where possible.
  63 This is useful for analyzing filesystem state or inconsistencies and has
  64 a positive educational effect on understanding the internal filesystem structure.
  65 +
  66 NOTE: contains file names, consider that if you're asked to send the dump for
  67 analysis. Does not contain file data.
  68 +
  69 `Options`
  70 +
  71 -e|--extents::::
  72 print only extent-related information: extent and device trees
  73 -d|--device::::
  74 print only device-related information: tree root, chunk and device trees
  75 -r|--roots::::
  76 print only short root node information, ie. the root tree keys
  77 -R|--backups::::
  78 same as --roots plus print backup root info, ie. the backup root keys and
  79 the respective tree root block offset
  80 -u|--uuid::::
  81 print only the uuid tree information, empty output if the tree does not exist
  82 -b <block_num>::::
  83 print info of the specified block only
  84 -t <tree_id>::::
  85 print only the tree with the specified ID, where the ID can be numerical or
  86 common name in a flexible human readable form
  87 +
  88 The tree id name recognition rules:
  89 [options="compact"]
  90 * case does not matter
  91 * the C source definition, eg. BTRFS_ROOT_TREE_OBJECTID
  92 * short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, eg. ROOT_TREE, ROOT
  93 * convenience aliases, eg. DEVICE for the DEV tree, CHECKSUM for CSUM
  94 * unrecognized ID is an error
  95
  96 *inode-resolve* [-v] <ino> <path>::
  97 (needs root privileges)
  98 +
  99 resolve paths to all files with given inode number 'ino' in a given subvolume
 100 at 'path', ie. all hardlinks
 101 +
 102 `Options`
 103 +
 104 -v::::
 105 verbose mode, print count of returned paths and ioctl() return value
 106
 107 *logical-resolve* [-Pv] [-s <bufsize>] <logical> <path>::
 108 (needs root privileges)
 109 +
 110 resolve paths to all files at given 'logical' address in the linear filesystem space
 111 +
 112 `Options`
 113 +
 114 -P::::
 115 skip the path resolving and print the inodes instead
 116 -v::::
 117 verbose mode, print count of returned paths and all ioctl() return values
 118 -s <bufsize>::::
 119 set internal buffer for storing the file names to 'bufsize', default is 4096, maximum 64k
 120
 121 *min-dev-size* [options] <path>::
 122 (needs root privileges)
 123 +
 124 return the minimum size the device can be shrunk to, without performing any
 125 resize operation, this may be useful before executing the actual resize operation
 126 +
 127 `Options`
 128 +
 129 --id <id>::::
 130 specify the device 'id' to query, default is 1 if this option is not used
 131
 132 *rootid* <path>::
 133 for a given file or directory, return the containing tree root id, for a
 134 subvolume itself return it's own tree id (ie. subvol id)
 135 +
 136 NOTE: The result is undefined for the so-called empty subvolumes (identified by
 137 inode number 2), but such subvolume does not contain any files anyway
 138
 139 *subvolid-resolve* <subvolid> <path>::
 140 (needs root privileges)
 141 +
 142 resolve the absolute path of a the subvolume id 'subvolid'
 143
 144 EXIT STATUS
 145 -----------
 146 *btrfs inspect-internal* returns a zero exit status if it succeeds. Non zero is
 147 returned in case of failure.
 148
 149 AVAILABILITY
 150 ------------
 151 *btrfs* is part of btrfs-progs.
 152 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 153 further details.
 154
 155 SEE ALSO
 156 --------
 157 `mkfs.btrfs`(8)