debugfs/debugfs.8.in

   1 .\" -*- nroff -*-
   2 .\" Copyright 1993, 1994, 1995 by Theodore Ts'o.  All Rights Reserved.
   3 .\" This file may be copied under the terms of the GNU Public License.
   4 .\"
   5 .TH DEBUGFS 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
   6 .SH NAME
   7 debugfs \- ext2/ext3 file system debugger
   8 .SH SYNOPSIS
   9 .B debugfs
  10 [
  11 .B \-b
  12 blocksize
  13 ]
  14 [
  15 .B \-s
  16 superblock
  17 ]
  18 [
  19 .B \-f
  20 cmd_file
  21 ]
  22 [
  23 .B \-R
  24 request
  25 ]
  26 [
  27 .B \-V
  28 ]
  29 [
  30 [
  31 .B \-w
  32 ]
  33 [
  34 .B \-c
  35 ]
  36 [
  37 .B \-i
  38 ]
  39 [
  40 device
  41 ]
  42 ]
  43 .SH DESCRIPTION
  44 The
  45 .B debugfs
  46 program is an interactive file system debugger. It can be used to
  47 examine and change the state of an ext2 file system.
  48 .br
  49 .I device
  50 is the special file corresponding to the device containing the ext2
  51 file system (e.g /dev/hdXX).
  52 .SH OPTIONS
  53 .TP
  54 .I \-w
  55 Specifies that the file system should be opened in read-write mode.
  56 Without this option, the file system is opened in read-only mode.
  57 .TP
  58 .I \-c
  59 Specifies that the file system should be opened in catastrophic mode, in
  60 which the inode and group bitmaps are not read initially.  This can be
  61 useful for filesystems with significant corruption, but because of this,
  62 catastrophic mode forces the filesystem to be opened read-only.
  63 .TP
  64 .I \-i
  65 Specifies that
  66 .I device
  67 represents an ext2 image file created by the
  68 .B e2image
  69 program.  Since the ext2 image file only contains the superblock, block
  70 group descriptor, block and inode allocation bitmaps, and
  71 the inode table, many
  72 .B debugfs
  73 commands will not function properly.
  74 .B Warning:
  75 no safety checks are in place, and
  76 .B debugfs
  77 may fail in interesting ways if commands such as
  78 .IR ls ", " dump ", "
  79 etc. are tried.
  80 .B debugfs
  81 is a debugging tool.  It has rough edges!
  82 .TP
  83 .I -b blocksize
  84 Forces the use of the given block size for the file system, rather than
  85 detecting the correct block size as normal.
  86 .TP
  87 .I -s superblock
  88 Causes the file system superblock to be read from the given block number,
  89 rather than the default (1).  If you give a
  90 .I -s
  91 option, you must also give a
  92 .I -b
  93 option.
  94 .TP
  95 .I -f cmd_file
  96 Causes
  97 .B debugfs
  98 to read in commands from
  99 .IR cmd_file ,
 100 and execute them.  When
 101 .B debugfs
 102 is finished executing those commands, it will exit.
 103 .TP
 104 .I -R request
 105 Causes
 106 .B debugfs
 107 to execute the single command
 108 .IR request ,
 109 and then exit.
 110 .TP
 111 .I -V
 112 print the version number of
 113 .B debugfs
 114 and exit.
 115 .SH SPECIFYING FILES
 116 Many
 117 .B debugfs
 118 commands take a
 119 .I filespec
 120 as an argument to specify an inode (as opposed to a pathname)
 121 in the filesystem which is currently opened by
 122 .BR debugfs .
 123 The
 124 .I filespec
 125 argument may be specified in two forms.  The first form is an inode
 126 number surrounded by angle brackets, e.g.,
 127 .IR <2> .
 128 The second form is a pathname; if the pathname is prefixed by a forward slash
 129 ('/'), then it is interpreted relative to the root of the filesystem
 130 which is currently opened by
 131 .BR debugfs .
 132 If not, the pathname is
 133 interpreted relative to the current working directory as maintained by
 134 .BR debugfs .
 135 This may be modified by using the
 136 .B debugfs
 137 command
 138 .IR cd .
 139 .\"
 140 .\"
 141 .\"
 142 .SH COMMANDS
 143 This is a list of the commands which
 144 .B debugfs
 145 supports.
 146 .TP
 147 .I bmap filespec logical_block
 148 Print the physical block number corresponding to the logical block number
 149 .I logical_block
 150 in the inode
 151 .IR filespec .
 152 .TP
 153 .I cat filespec
 154 Dump the contents of the inode
 155 .I filespec
 156 to stdout.
 157 .TP
 158 .I cd filespec
 159 Change the current working directory to
 160 .IR filespec .
 161 .TP
 162 .I chroot filespec
 163 Change the root directory to be the directory
 164 .IR filespec .
 165 .TP
 166 .I close
 167 Close the currently open file system.
 168 .TP
 169 .I clri file
 170 Clear the contents of the inode
 171 .IR file .
 172 .TP
 173 .I dump [-p] filspec out_file
 174 Dump the contents of the inode
 175 .I filespec
 176 to the output file
 177 .IR out_file .
 178 If the
 179 .I -p
 180 option is given set the owner, group and permissions information on
 181 .I out_file
 182 to match
 183 .IR filespec .
 184 .TP
 185 .I expand_dir filespec
 186 Expand the directory
 187 .IR filespec .
 188 .TP
 189 .I feature [fs_feature] [-fs_feature] ...
 190 Set or clear various filesystem features in the superblock.  After setting
 191 or clearing any filesystem features that were requested, print the current
 192 state of the filesystem feature set.
 193 .TP
 194 .I find_free_block [count [goal]]
 195 Find the first
 196 .I count
 197 free blocks, starting from
 198 .I goal
 199 and allocate it.
 200 .TP
 201 .I find_free_inode [dir [mode]]
 202 Find a free inode and allocate it.  If present,
 203 .I dir
 204 specifies the inode number of the directory
 205 which the inode is to be located.  The second
 206 optional argument
 207 .I mode
 208 specifies the permissions of the new inode.  (If the directory bit is set
 209 on the mode, the allocation routine will function differently.)
 210 .TP
 211 .I freeb block [count]
 212 Mark the block number
 213 .I block
 214 as not allocated.
 215 If the optional argument
 216 .I count
 217 is present, then
 218 .I count
 219 blocks starting at block number
 220 .I block
 221 will be marked as not allocated.
 222 .TP
 223 .I freei filespec
 224 Free the inode specified by
 225 .IR filespec .
 226 .TP
 227 .I help
 228 Print a list of commands understood by
 229 .BR debugfs (8).
 230 .TP
 231 .I icheck block ...
 232 Print a listing of the inodes which use the one or more blocks specified
 233 on the command line.
 234 .TP
 235 .I imap filespec
 236 Print the location of the inode data structure (in the inode table)
 237 of the inode
 238 .IR filespec .
 239 .TP
 240 .I init_filesys device blocksize
 241 Create an ext2 file system on
 242 .I device
 243 with device size
 244 .IR blocksize .
 245 Note that this does not fully initialize all of the data structures;
 246 to do this, use the
 247 .BR mke2fs (8)
 248 program.  This is just a call to the low-level library, which sets up
 249 the superblock and block descriptors.
 250 .TP
 251 .I kill_file filespec
 252 Deallocate the inode
 253 .I filespec
 254 and its blocks.  Note that this does not remove any directory
 255 entries (if any) to this inode.  See the
 256 .BR rm (1)
 257 command if you wish to unlink a file.
 258 .TP
 259 .I lcd directory
 260 Change the current working directory of the
 261 .B debugfs
 262 process to
 263 .I directory
 264 on the native filesystem.
 265 .TP
 266 .I ln filespec dest_file
 267 Create a link named
 268 .I dest_file
 269 which is a link to
 270 .IR filespec .
 271 Note this does not adjust the inode reference counts.
 272 .TP
 273 .I logdump [-acs] [-b<block>] [-i<filespec>] [-f<journal_file>] [output_file]
 274 Dump the contents of the ext3 journal.  By default, the journal inode as
 275 specified in the superblock.  However, this can be overridden with the
 276 .I \-i
 277 option, which uses an inode specifier to specify the journal to be
 278 used.  A file containing journal data can be specified using the
 279 .I \-f
 280 option.   Finally, the
 281 .I \-s
 282 option utilizes the backup information in the superblock to locate the
 283 journal.
 284 .IP
 285 The
 286 .I \-a
 287 option causes the
 288 .I logdump
 289 program to print the contents of all of the descriptor blocks.
 290 The
 291 .I \-b
 292 option causes
 293 .I logdump
 294 to print all journal records that are refer to the specified block.
 295 The
 296 .I \-c
 297 option will print out the contents of all of the data blocks selected by
 298 the
 299 .I \-a
 300 and
 301 .I \-b
 302 options.
 303 .TP
 304 .I ls [-l] [-d] filespec
 305 Print a listing of the files in the directory
 306 .IR filespec .
 307 The
 308 .I \-l
 309 flag will list files using a more verbose format.
 310 The
 311 .I \-d
 312 flag will list deleted entries in the directory.
 313 .TP
 314 .I modify_inode filespec
 315 Modify the contents of the inode structure in the inode
 316 .IR filespec .
 317 .TP
 318 .I mkdir filespec
 319 Make a directory.
 320 .TP
 321 .I mknod filespec [p|[[c|b] major minor]]
 322 Create a special device file (a named pipe, character or block device).
 323 If a character or block device is to be made, the
 324 .I major
 325 and
 326 .I minor
 327 device numbers must be specified.
 328 .TP
 329 .I ncheck inode_num ...
 330 Take the requested list of inode numbers, and print a listing of pathnames
 331 to those inodes.
 332 .TP
 333 .I open [-w] [-f] [-i] [-c] [-b blocksize] [-s superblock] device
 334 Open a filesystem for editing.  The
 335 .I -w
 336 flag causes the filesystem to be opened for writing.  The
 337 .I -f
 338 flag forces the filesystem to be opened even if there are some unknown
 339 or incompatible filesystem features which would normally
 340 prevent the filesystem from being opened.  The
 341 .IR -c ", " -b ", " -i ", " and " -s
 342 options behave the same as those to
 343 .B debugfs
 344 itself.
 345 .TP
 346 .I pwd
 347 Print the current working directory.
 348 .TP
 349 .I quit
 350 Quit
 351 .B debugfs
 352 .TP
 353 .I rdump directory destination
 354 Recursively dump
 355 .I directory
 356 and all its contents (including regular files, symbolic links, and other
 357 directories) into the named
 358 .I destination
 359 which should be an existing directory on the native filesystem.
 360 .TP
 361 .I rm pathname
 362 Unlink
 363 .IR pathname .
 364 If this causes the inode pointed to by
 365 .I pathname
 366 to have no other references, deallocate the file.  This command functions
 367 as the unlink() system call.
 368 .I
 369 .TP
 370 .I rmdir filespec
 371 Remove the directory
 372 .IR filespec .
 373 .TP
 374 .I setb block [count]
 375 Mark the block number
 376 .I block
 377 as allocated.
 378 If the optional argument
 379 .I count
 380 is present, then
 381 .I count
 382 blocks starting at block number
 383 .I block
 384 will be marked as allocated.
 385 .TP
 386 .I seti filespec
 387 Mark inode
 388 .I filespec
 389 as in use in the inode bitmap.
 390 .TP
 391 .I set_super_value field value
 392 Set the superblock field
 393 .I field
 394 to
 395 .I value.
 396 The list of valid superblock fields which can be set via this command
 397 can be displayed by using the command:
 398 .B set_super_value -l
 399 .TP
 400 .I show_super_stats [-h]
 401 List the contents of the super block and the block group descriptors.  If the
 402 .I -h
 403 flag is given, only print out the superblock contents.
 404 .TP
 405 .I stat filespec
 406 Display the contents of the inode structure of the inode
 407 .IR filespec .
 408 .TP
 409 .I testb block [count]
 410 Test if the block number
 411 .I block
 412 is marked as allocated in the block bitmap.
 413 If the optional argument
 414 .I count
 415 is present, then
 416 .I count
 417 blocks starting at block number
 418 .I block
 419 will be tested.
 420 .TP
 421 .I testi filespec
 422 Test if the inode
 423 .I filespec
 424 is marked as allocated in the inode bitmap.
 425 .TP
 426 .I unlink pathname
 427 Remove the link specified by
 428 .I pathname
 429 to an inode.  Note this does not adjust the inode reference counts.
 430 .TP
 431 .I write source_file out_file
 432 Create a file in the filesystem named
 433 .IR out_file ,
 434 and copy the contents of
 435 .I source_file
 436 into the destination file.
 437 .SH ENVIRONMENT VARIABLES
 438 .TP
 439 .B DEBUGFS_PAGER, PAGER
 440 The
 441 .BR debugfs (8)
 442 program always pipes the output of the some commands through a
 443 pager program.  These commands include:
 444 .IR show_super_stats ,
 445 .IR list_directory ,
 446 .IR show_inode_info ,
 447 .IR list_deleted_inodes ,
 448 and
 449 .IR htree_dump .
 450 The specific pager can explicitly specified by the
 451 .B DEBUGFS_PAGER
 452 environment variable, and if it is not set, by the
 453 .B PAGER
 454 environment variable.
 455 .IP
 456 Note that since a pager is always used, the
 457 .BR less (1)
 458 pager is not particularly appropriate, since it clears the screen before
 459 displaying the output of the command and clears the output the screen
 460 when the pager is exited.  Many users prefer to use the
 461 .BR less (1)
 462 pager for most purposes, which is why the
 463 .B DEBUGFS_PAGER
 464 environment variable is available to override the more general
 465 .B PAGER
 466 environment variable.
 467 .SH AUTHOR
 468 .B debugfs
 469 was written by Theodore Ts'o <tytso@mit.edu>.
 470 .SH SEE ALSO
 471 .BR dumpe2fs (8),
 472 .BR e2fsck (8),
 473 .BR mke2fs (8)