.\"
.TH DEBUGFS 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
.SH NAME
-debugfs \- ext2 file system debugger
+debugfs \- ext2/ext3/ext4 file system debugger
.SH SYNOPSIS
.B debugfs
[
-.B \-w
+.B \-DVwcin
+]
+[
+.B \-b
+blocksize
+]
+[
+.B \-s
+superblock
]
[
.B \-f
request
]
[
+.B \-d
+data_source_device
+]
+[
device
]
.SH DESCRIPTION
The
.B debugfs
-program
-is a file system debugger. It can be used to examine and change the
-state of an ext2 file system.
+program is an interactive file system debugger. It can be used to
+examine and change the state of an ext2, ext3, or ext4 file system.
.br
.I device
-is the special file corresponding to the device containing the ext2
+is the special file corresponding to the device containing the
file system (e.g /dev/hdXX).
.SH OPTIONS
.TP
-.I -w
-Specify that the file system should be open in read-write mode. Without this
-option, the file system is open in read-only mode.
+.I \-w
+Specifies that the file system should be opened in read-write mode.
+Without this option, the file system is opened in read-only mode.
+.TP
+.I \-n
+Disables metadata checksum verification. This should only be used if
+you believe the metadata to be correct despite the complaints of
+e2fsprogs.
+.TP
+.I \-c
+Specifies that the file system should be opened in catastrophic mode, in
+which the inode and group bitmaps are not read initially. This can be
+useful for filesystems with significant corruption, but because of this,
+catastrophic mode forces the filesystem to be opened read-only.
+.TP
+.I \-i
+Specifies that
+.I device
+represents an ext2 image file created by the
+.B e2image
+program. Since the ext2 image file only contains the superblock, block
+group descriptor, block and inode allocation bitmaps, and
+the inode table, many
+.B debugfs
+commands will not function properly.
+.B Warning:
+no safety checks are in place, and
+.B debugfs
+may fail in interesting ways if commands such as
+.IR ls ", " dump ", "
+etc. are tried without specifying the
+.I data_source_device
+using the
+.I \-d
+option.
+.B debugfs
+is a debugging tool. It has rough edges!
+.TP
+.I -d data_source_device
+Used with the
+.I \-i
+option, specifies that
+.I data_source_device
+should be used when reading blocks not found in the ext2 image file.
+This includes data, directory, and indirect blocks.
+.TP
+.I -b blocksize
+Forces the use of the given block size for the file system, rather than
+detecting the correct block size as normal.
+.TP
+.I -s superblock
+Causes the file system superblock to be read from the given block
+number, instead of using the primary superblock (located at an offset of
+1024 bytes from the beginning of the filesystem). If you specify the
+.I -s
+option, you must also provide the blocksize of the filesystem via the
+.I -b
+option.
.TP
.I -f cmd_file
Causes
.IR cmd_file ,
and execute them. When
.B debugfs
-is finsihed executing those commands, it will exit.
-.TP
+is finished executing those commands, it will exit.
+.TP
+.I -D
+Causes
+.B debugfs
+to open the device using Direct I/O, bypassing the buffer cache. Note
+that some Linux devices, notably device mapper as of this writing, do
+not support Direct I/O.
+.TP
.I -R request
Causes
.B debugfs
to execute the single command
.IR request ,
and then exit.
+.TP
+.I -V
+print the version number of
+.B debugfs
+and exit.
+.SH SPECIFYING FILES
+Many
+.B debugfs
+commands take a
+.I filespec
+as an argument to specify an inode (as opposed to a pathname)
+in the filesystem which is currently opened by
+.BR debugfs .
+The
+.I filespec
+argument may be specified in two forms. The first form is an inode
+number surrounded by angle brackets, e.g.,
+.IR <2> .
+The second form is a pathname; if the pathname is prefixed by a forward slash
+('/'), then it is interpreted relative to the root of the filesystem
+which is currently opened by
+.BR debugfs .
+If not, the pathname is
+interpreted relative to the current working directory as maintained by
+.BR debugfs .
+This may be modified by using the
+.B debugfs
+command
+.IR cd .
+.\"
+.\"
+.\"
.SH COMMANDS
+This is a list of the commands which
.B debugfs
-is an interactive debugger. It understands a number of commands.
+supports.
+.TP
+.I blocks filespace
+Print the blocks used by the inode
+.I filespec
+to stdout.
+.TP
+.I bmap filespec logical_block
+Print the physical block number corresponding to the logical block number
+.I logical_block
+in the inode
+.IR filespec .
+.TP
+.I block_dump [-f out_file] block_num
+Dump the contents of a block, optionally to
+.IR out_file .
.TP
.I cat filespec
Dump the contents of the inode
Change the root directory to be the directory
.IR filespec .
.TP
-.I close
-Close the currently open file system.
+.I close [-a]
+Close the currently open file system. If the
+.I -a
+option is specified, write out any changes to the superblock and block
+group descriptors to all of the backup superblocks, not just to the
+master superblock.
.TP
.I clri file
Clear the contents of the inode
.IR file .
.TP
-.I dump [-p] filspec out_file
+.I dirsearch filespec filename
+Search the directory
+.I filespec
+for
+.IR filename .
+.TP
+.I dump [-p] filespec out_file
Dump the contents of the inode
.I filespec
to the output file
to match
.IR filespec .
.TP
+.I dump_mmp
+Display the multiple-mount protection (mmp) field values.
+.TP
+.I dx_hash [-h hash_alg] [-s hash_seed] filename
+Calculate the directory hash of
+.IR filename .
+The hash algorithm specified with
+.I -h
+may be "legacy" "half_md4" or "tea".
+The hash seed specified with
+.I -s
+must be in UUID format.
+.TP
+.I dump_extents [-n] [-l] filespec
+Dump the the extent tree of the inode
+.IR filespec .
+The
+.I -n
+flag will cause
+.I dump_extents
+to only display the interior nodes in the extent tree. The
+.I -l
+flag cause
+.I dump_extents
+to only display the leaf nodes in the extent tree.
+.IP
+(Please note that the length and range of blocks for the last extent in
+an interior node is an estimate by the extents library functions, and is
+not stored in filesystem data structures. Hence, the values displayed
+may not necessarily by accurate and does not indicate a problem or
+corruption in the file system.)
+.TP
.I expand_dir filespec
Expand the directory
.IR filespec .
.TP
-.I find_free_block [goal]
-Find the first free block, starting from
+.I feature [fs_feature] [-fs_feature] ...
+Set or clear various filesystem features in the superblock. After setting
+or clearing any filesystem features that were requested, print the current
+state of the filesystem feature set.
+.TP
+.I filefrag [-dvr] filespec
+Print the number of contiguous extents in
+.IR filespec .
+If
+.I filespec
+is a directory and the
+.I -d
+option is not specified,
+.I filefrag
+will print the number of contiguous extents for each file in
+the directory. The
+.I -v
+option will cause
+.I filefrag
+print a tabular listing of the contiguous extents in the
+file. The
+.I -r
+option will cause
+.I filefrag
+to do a recursive listing of the directory.
+.TP
+.I find_free_block [count [goal]]
+Find the first
+.I count
+free blocks, starting from
.I goal
-and allocates it.
+and allocate it.
.TP
.I find_free_inode [dir [mode]]
-Find a free inode and allocates it. If present,
+Find a free inode and allocate it. If present,
.I dir
specifies the inode number of the directory
which the inode is to be located. The second
specifies the permissions of the new inode. (If the directory bit is set
on the mode, the allocation routine will function differently.)
.TP
-.I freeb block
+.I freeb block [count]
Mark the block number
.I block
as not allocated.
-.TP
-.I freei filespec
+If the optional argument
+.I count
+is present, then
+.I count
+blocks starting at block number
+.I block
+will be marked as not allocated.
+.TP
+.I freefrag [-c chunk_kb ]
+Report free space fragmentation on the currently open file system.
+If the
+.I \-c
+option is specified then the filefrag command will print how many free
+chunks of size
+.I chunk_kb
+can be found in the file system. The chunk size must be a power of two
+and be larger than the file system block size.
+.TP
+.I freei filespec [num]
Free the inode specified by
-.I filespec
+.IR filespec .
+If
+.I num
+is specified, also clear num-1 inodes after the specified inode.
.TP
.I help
Print a list of commands understood by
-.BR debugfs (8).
+.BR debugfs .
+.TP
+.I htree_dump filespec
+Dump the hash-indexed directory
+.IR filespec ,
+showing its tree structure.
.TP
.I icheck block ...
-Print a listing of the inodes which use the one or more block specified
+Print a listing of the inodes which use the one or more blocks specified
on the command line.
.TP
-.I initialize device blocksize
+.I imap filespec
+Print the location of the inode data structure (in the inode table)
+of the inode
+.IR filespec .
+.TP
+.I init_filesys device blocksize
Create an ext2 file system on
.I device
with device size
the superblock and block descriptors.
.TP
.I kill_file filespec
-Dellocate the inode
+Deallocate the inode
.I filespec
and its blocks. Note that this does not remove any directory
entries (if any) to this inode. See the
-.I rm
+.BR rm (1)
command if you wish to unlink a file.
.TP
+.I lcd directory
+Change the current working directory of the
+.B debugfs
+process to
+.I directory
+on the native filesystem.
+.TP
.I ln filespec dest_file
Create a link named
.I dest_file
.IR filespec .
Note this does not adjust the inode reference counts.
.TP
-.I ls [-l] filespec
+.I logdump [-acs] [-b<block>] [-i<filespec>] [-f<journal_file>] [output_file]
+Dump the contents of the ext3 journal. By default, the journal inode as
+specified in the superblock. However, this can be overridden with the
+.I \-i
+option, which uses an inode specifier to specify the journal to be
+used. A file containing journal data can be specified using the
+.I \-f
+option. Finally, the
+.I \-s
+option utilizes the backup information in the superblock to locate the
+journal.
+.IP
+The
+.I \-a
+option causes the
+.I logdump
+program to print the contents of all of the descriptor blocks.
+The
+.I \-b
+option causes
+.I logdump
+to print all journal records that are refer to the specified block.
+The
+.I \-c
+option will print out the contents of all of the data blocks selected by
+the
+.I \-a
+and
+.I \-b
+options.
+.TP
+.I ls [-l] [-c] [-d] [-p] filespec
Print a listing of the files in the directory
.IR filespec .
+The
+.I \-l
+flag will list files using a more verbose format.
+The
+.I \-c
+flag causes directory block checksums (if present) to be displayed.
+The
+.I \-d
+flag will list deleted entries in the directory.
+The
+.I \-p
+flag will list the files in a format which is more easily parsable by
+scripts, as well as making it more clear when there are spaces or other
+non-printing characters at the end of filenames.
.TP
.I modify_inode filespec
Modify the contents of the inode structure in the inode
.I minor
device numbers must be specified.
.TP
-.I ncheck inode_num ...
-Take the requested list of inode numbers, and print a listing of pathnams
-to those inodes.
-.TP
-.I open [-w] device
-Open a file system for editing.
+.I ncheck [-c] inode_num ...
+Take the requested list of inode numbers, and print a listing of pathnames
+to those inodes. The
+.I -c
+flag will enable checking the file type information in the directory
+entry to make sure it matches the inode's type.
+.TP
+.I open [-w] [-e] [-f] [-i] [-c] [-D] [-b blocksize] [-s superblock] device
+Open a filesystem for editing. The
+.I -f
+flag forces the filesystem to be opened even if there are some unknown
+or incompatible filesystem features which would normally
+prevent the filesystem from being opened. The
+.I -e
+flag causes the filesystem to be opened in exclusive mode. The
+.IR -b ", " -c ", " -i ", " -s ", " -w ", and " -D
+options behave the same as the command-line options to
+.BR debugfs .
+.TP
+.I punch filespec start_blk [end_blk]
+Delete the blocks in the inode ranging from
+.I start_blk
+to
+.IR end_blk .
+If
+.I end_blk
+is omitted then this command will function as a truncate command; that
+is, all of the blocks starting at
+.I start_blk
+through to the end of the file will be deallocated.
+.TP
+.I symlink filespec target
+Make a symbolic link.
.TP
.I pwd
Print the current working directory.
Quit
.B debugfs
.TP
+.I rdump directory destination
+Recursively dump
+.I directory
+and all its contents (including regular files, symbolic links, and other
+directories) into the named
+.I destination
+which should be an existing directory on the native filesystem.
+.TP
.I rm pathname
Unlink
.IR pathname .
-If this cuases the inode pointed to by
+If this causes the inode pointed to by
.I pathname
to have no other references, deallocate the file. This command functions
as the unlink() system call.
.I rmdir filespec
Remove the directory
.IR filespec .
-This function is currently not implemented.
.TP
-.I setb block
+.I setb block [count]
Mark the block number
.I block
as allocated.
+If the optional argument
+.I count
+is present, then
+.I count
+blocks starting at block number
+.I block
+will be marked as allocated.
+.TP
+.I set_block_group bgnum field value
+Modify the block group descriptor specified by
+.I bgnum
+so that the block group descriptor field
+.I field
+has value
+.I value.
.TP
-.I seti filespec
+.I seti filespec [num]
Mark inode
.I filespec
-as in use in the inode bitmap.
+as in use in the inode bitmap. If
+.I num
+is specified, also set num-1 inodes after the specified inode.
.TP
-.I show_super_stats
-List the contents of the super block.
+.I set_inode_field filespec field value
+Modify the inode specified by
+.I filespec
+so that the inode field
+.I field
+has value
+.I value.
+The list of valid inode fields which can be set via this command
+can be displayed by using the command:
+.B set_inode_field -l
+.TP
+.I set_mmp_value field value
+Modify the multiple-mount protection (mmp) data so that the
+mmp field
+.I field
+has value
+.I value.
+The list of valid mmp fields which can be set via this command
+can be displayed by using the command:
+.B set_mmp_value -l
+.TP
+.I set_super_value field value
+Set the superblock field
+.I field
+to
+.I value.
+The list of valid superblock fields which can be set via this command
+can be displayed by using the command:
+.B set_super_value -l
+.TP
+.I show_super_stats [-h]
+List the contents of the super block and the block group descriptors. If the
+.I -h
+flag is given, only print out the superblock contents.
.TP
.I stat filespec
Display the contents of the inode structure of the inode
.IR filespec .
.TP
-.I testb block
+.I testb block [count]
Test if the block number
.I block
is marked as allocated in the block bitmap.
+If the optional argument
+.I count
+is present, then
+.I count
+blocks starting at block number
+.I block
+will be tested.
.TP
.I testi filespec
Test if the inode
.I filespec
is marked as allocated in the inode bitmap.
.TP
+.I undel <inode num> [pathname]
+Undelete the specified inode number (which must be surrounded by angle
+brackets) so that it and its blocks are marked in use, and optionally
+link the recovered inode to the specified pathname. The
+.B e2fsck
+command should always be run after using the
+.B undel
+command to recover deleted files.
+.IP
+Note that if you are recovering a large number of deleted files, linking
+the inode to a directory may require the directory to be expanded, which
+could allocate a block that had been used by one of the
+yet-to-be-undeleted files. So it is safer to undelete all of the
+inodes without specifying a destination pathname, and then in a separate
+pass, use the debugfs
+.B link
+command to link the inode to the destination pathname, or use
+.B e2fsck
+to check the filesystem and link all of the recovered inodes to the
+lost+found directory.
+.TP
.I unlink pathname
Remove the link specified by
.I pathname
and copy the contents of
.I source_file
into the destination file.
-.SH SPECIFYING FILES
-Many
+.TP
+.I zap_block [-f file] [-o offset] [-l length] [-p pattern] block_num
+Zero, or pattern-fill, portions of a block within a file or
+within the filesystem.
+.TP
+.I zap_block [-f file] [-b bit] block_num
+Bit-flip portions of a block within a file or
+within the filesystem.
+.SH ENVIRONMENT VARIABLES
+.TP
+.B DEBUGFS_PAGER, PAGER
+The
.B debugfs
-commands take a
-.I filespec
-as an argument to specify an inode (as opposed to a pathname)
-in the filesystem which is currently opened by debugfs. The
-.I filespec
-argument may be specified in two forms. The first form is an inode
-number surrounded by angle brackets, e.g.,
-.IR <2> .
-The second form is a pathname; if the pathname is prefixed by a forward slash
-('/'), then it is interpreted relative to the root of the filesystem
-which is currently opened by debugfs. If not, the pathname is
-interpreted relative to the current working directory as maintained
-by debugfs. This may be modified by using the debugfs command
-.IR cd .
+program always pipes the output of the some commands through a
+pager program. These commands include:
+.IR show_super_stats ,
+.IR list_directory ,
+.IR show_inode_info ,
+.IR list_deleted_inodes ,
+and
+.IR htree_dump .
+The specific pager can explicitly specified by the
+.B DEBUGFS_PAGER
+environment variable, and if it is not set, by the
+.B PAGER
+environment variable.
+.IP
+Note that since a pager is always used, the
+.BR less (1)
+pager is not particularly appropriate, since it clears the screen before
+displaying the output of the command and clears the output the screen
+when the pager is exited. Many users prefer to use the
+.BR less (1)
+pager for most purposes, which is why the
+.B DEBUGFS_PAGER
+environment variable is available to override the more general
+.B PAGER
+environment variable.
.SH AUTHOR
.B debugfs
was written by Theodore Ts'o <tytso@mit.edu>.
.SH SEE ALSO
.BR dumpe2fs (8),
+.BR tune2fs (8),
.BR e2fsck (8),
.BR mke2fs (8)
git://git.whamcloud.com / tools / e2fsprogs.git / blobdiff