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