.\" -*- nroff -*-
.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved.
.\" This file may be copied under the terms of the GNU Public License.
-.\"
+.\"
.TH E2FSCK 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
.SH NAME
-e2fsck \- check a Linux second extended file system
+e2fsck \- check a Linux ext2/ext3/ext4 file system
.SH SYNOPSIS
.B e2fsck
[
-.B \-pacnyrdfvstFSV
+.B \-pacnyrdfkvtDFV
]
[
.B \-b
.I blocksize
]
[
-.B \-l|-L
+.BR \-l | \-L
.I bad_blocks_file
]
+[
+.B \-C
+.I fd
+]
+@JDEV@[
+@JDEV@.B \-j
+@JDEV@.I external-journal
+@JDEV@]
+[
+.B \-E
+.I extended_options
+]
+[
+.B \-z
+.I undo_file
+]
.I device
.SH DESCRIPTION
.B e2fsck
-is used to check a Linux second extended file system.
-.TP
+is used to check the ext2/ext3/ext4 family of file systems.
+For ext3 and ext4 filesystems that use a journal, if the system has been
+shut down uncleanly without any errors, normally, after replaying the
+committed transactions in the journal, the file system should be
+marked as clean. Hence, for filesystems that use journalling,
+.B e2fsck
+will normally replay the journal and exit, unless its superblock
+indicates that further checking is required.
+.PP
.I device
-is the special file corresponding to the device (e.g /dev/hdXX).
+is a block device (e.g.,
+.IR /dev/sdc1 )
+or file containing the file system.
+.PP
+Note that in general it is not safe to run
+.B e2fsck
+on mounted filesystems. The only exception is if the
+.B \-n
+option is specified, and
+.BR \-c ,
+.BR \-l ,
+or
+.B -L
+options are
+.I not
+specified. However, even if it is safe to do so, the results printed by
+.B e2fsck
+are not valid if the filesystem is mounted. If
+.B e2fsck
+asks whether or not you should check a filesystem which is mounted,
+the only correct answer is ``no''. Only experts who really know what
+they are doing should consider answering this question in any other way.
+.PP
+If
+.B e2fsck
+is run in interactive mode (meaning that none of
+.BR \-y ,
+.BR \-n ,
+or
+.BR \-p
+are specified), the program will ask the user to fix each problem found in the
+filesystem. A response of 'y' will fix the error; 'n' will leave the error
+unfixed; and 'a' will fix the problem and all subsequent problems; pressing
+Enter will proceed with the default response, which is printed before the
+question mark. Pressing Control-C terminates e2fsck immediately.
.SH OPTIONS
.TP
-.I -a
-This option does the same thing as the
-.I -p
+.B \-a
+This option does the same thing as the
+.B \-p
option. It is provided for backwards compatibility only; it is
-suggested that people use
-.I -p
-option whever possible.
+suggested that people use
+.B \-p
+option whenever possible.
.TP
-.I -b superblock
-Instead of using the normal superblock, use the alternative superblock
-specified by
+.BI \-b " superblock"
+Instead of using the normal superblock, use an alternative superblock
+specified by
.IR superblock .
+This option is normally used when the primary superblock has been
+corrupted. The location of backup superblocks is dependent on the
+filesystem's blocksize, the number of blocks per group, and features
+such as
+.BR sparse_super .
+.IP
+Additional backup superblocks can be determined by using the
+.B mke2fs
+program using the
+.B \-n
+option to print out where the superblocks exist, supposing
+.B mke2fs
+is supplied with arguments that are consistent with the filesystem's layout
+(e.g. blocksize, blocks per group,
+.BR sparse_super ,
+etc.).
+.IP
+If an alternative superblock is specified and
+the filesystem is not opened read-only, e2fsck will make sure that the
+primary superblock is updated appropriately upon completion of the
+filesystem check.
.TP
-.I -B blocksize
-Normally, e2fsck will search for the superblock at various different
-block sizes in an attempt to find the appropriate block size. This
-search can be fooled in some cases. This option forces e2fsck to only
-try locating the superblock at a particular blocksize. If the
-superblock is not found, e2fsck will terminate with a fatal error.
+.BI \-B " blocksize"
+Normally,
+.B e2fsck
+will search for the superblock at various different
+block sizes in an attempt to find the appropriate block size.
+This search can be fooled in some cases. This option forces
+.B e2fsck
+to only try locating the superblock at a particular blocksize.
+If the superblock is not found,
+.B e2fsck
+will terminate with a fatal error.
.TP
-.I -c
-This option causes e2fsck to run the
+.B \-c
+This option causes
+.B e2fsck
+to use
.BR badblocks (8)
-program to find any blocks
-which are bad on the filesystem, and then marks them as bad by adding them
-to the bad block inode.
+program to do a read-only scan of the device in order to find any bad
+blocks. If any bad blocks are found, they are added to the bad block
+inode to prevent them from being allocated to a file or directory. If
+this option is specified twice, then the bad block scan will be done
+using a non-destructive read-write test.
.TP
-.I -d
+.BI \-C " fd"
+This option causes
+.B e2fsck
+to write completion information to the specified file descriptor
+so that the progress of the filesystem
+check can be monitored. This option is typically used by programs
+which are running
+.BR e2fsck .
+If the file descriptor number is negative, then absolute value of
+the file descriptor will be used, and the progress information will be
+suppressed initially. It can later be enabled by sending the
+.B e2fsck
+process a SIGUSR1 signal.
+If the file descriptor specified is 0,
+.B e2fsck
+will print a completion bar as it goes about its business. This requires
+that e2fsck is running on a video console or terminal.
+.TP
+.B \-d
Print debugging output (useless unless you are debugging
+.BR e2fsck ).
+.TP
+.B \-D
+Optimize directories in filesystem. This option causes e2fsck to
+try to optimize all directories, either by reindexing them if the
+filesystem supports directory indexing, or by sorting and compressing
+directories for smaller directories, or for filesystems using
+traditional linear directories.
+.IP
+Even without the
+.B \-D
+option,
+.B e2fsck
+may sometimes optimize a few directories --- for example, if
+directory indexing is enabled and a directory is not indexed and would
+benefit from being indexed, or if the index structures are corrupted
+and need to be rebuilt. The
+.B \-D
+option forces all directories in the filesystem to be optimized. This can
+sometimes make them a little smaller and slightly faster to search, but
+in practice, you should rarely need to use this option.
+.IP
+The
+.B \-D
+option will detect directory entries with duplicate names in a single
+directory, which e2fsck normally does not enforce for performance reasons.
+.TP
+.BI \-E " extended_options"
+Set e2fsck extended options. Extended options are comma
+separated, and may take an argument using the equals ('=') sign. The
+following options are supported:
+.RS 1.2i
+.TP
+.BI clone= dup|zero
+Resolve files with shared blocks in pass 1D by giving each file a private
+copy of the blocks (dup);
+or replacing the shared blocks with private, zero-filled blocks (zero).
+The default is dup.
+.TP
+.BI shared= preserve|lost+found|delete
+Files with shared blocks discovered in pass 1D are cloned and then left
+in place (preserve);
+cloned and then disconnected from their parent directory,
+then reconnected to /lost+found in pass 3 (lost+found);
+or simply deleted (delete). The default is preserve.
+.TP
+.BI ea_ver= extended_attribute_version
+Set the version of the extended attribute blocks which
+.B e2fsck
+will require while checking the filesystem. The version number may
+be 1 or 2. The default extended attribute version format is 2.
+.TP
+.BI journal_only
+Only replay the journal if required, but do not perform any further checks
+or repairs.
+.TP
+.BI fragcheck
+During pass 1, print a detailed report of any discontiguous blocks for
+files in the filesystem.
+.TP
+.BI discard
+Attempt to discard free blocks and unused inode blocks after the full
+filesystem check (discarding blocks is useful on solid state devices and sparse
+/ thin-provisioned storage). Note that discard is done in pass 5 AFTER the
+filesystem has been fully checked and only if it does not contain recognizable
+errors. However there might be cases where
.B e2fsck
-).
+does not fully recognize a problem and hence in this case this
+option may prevent you from further manual data recovery.
+.TP
+.BI nodiscard
+Do not attempt to discard free blocks and unused inode blocks. This option is
+exactly the opposite of discard option. This is set as default.
+.TP
+.BI no_optimize_extents
+Do not offer to optimize the extent tree by eliminating unnecessary
+width or depth. This can also be enabled in the options section of
+.BR /etc/e2fsck.conf .
+.TP
+.BI optimize_extents
+Offer to optimize the extent tree by eliminating unnecessary
+width or depth. This is the default unless otherwise specified in
+.BR /etc/e2fsck.conf .
+.TP
+.BI inode_count_fullmap
+Trade off using memory for speed when checking a file system with a
+large number of hard-linked files. The amount of memory required is
+proportional to the number of inodes in the file system. For large file
+systems, this can be gigabytes of memory. (For example, a 40TB file system
+with 2.8 billion inodes will consume an additional 5.7 GB memory if this
+optimization is enabled.) This optimization can also be enabled in the
+options section of
+.BR /etc/e2fsck.conf .
+.TP
+.BI no_inode_count_fullmap
+Disable the
+.B inode_count_fullmap
+optimization. This is the default unless otherwise specified in
+.BR /etc/e2fsck.conf .
+.TP
+.BI readahead_kb
+Use this many KiB of memory to pre-fetch metadata in the hopes of reducing
+e2fsck runtime. By default, this is set to the size of two block groups' inode
+tables (typically 4MiB on a regular ext4 filesystem); if this amount is more
+than 1/50th of total physical memory, readahead is disabled. Set this to zero
+to disable readahead entirely.
+.TP
+.BI bmap2extent
+Convert block-mapped files to extent-mapped files.
+.TP
+.BI fixes_only
+Only fix damaged metadata; do not optimize htree directories or compress
+extent trees. This option is incompatible with the -D and -E bmap2extent
+options.
.TP
-.I -f
+.BI unshare_blocks
+If the filesystem has shared blocks, with the shared blocks read-only feature
+enabled, then this will unshare all shared blocks and unset the read-only
+feature bit. If there is not enough free space then the operation will fail.
+If the filesystem does not have the read-only feature bit, but has shared
+blocks anyway, then this option will have no effect. Note when using this
+option, if there is no free space to clone blocks, there is no prompt to
+delete files and instead the operation will fail.
+.IP
+Note that unshare_blocks implies the "-f" option to ensure that all passes
+are run. Additionally, if "-n" is also specified, e2fsck will simulate trying
+to allocate enough space to deduplicate. If this fails, the exit code will
+be non-zero.
+.RE
+.TP
+.B \-f
Force checking even if the file system seems clean.
.TP
-.I -F
+.B \-F
Flush the filesystem device's buffer caches before beginning. Only
-really useful for doing e2fsck time trials.
+really useful for doing
+.B e2fsck
+time trials.
+@JDEV@.TP
+@JDEV@.BI \-j " external-journal"
+@JDEV@Set the pathname where the external-journal for this filesystem can be
+@JDEV@found.
.TP
-.I -l filename
-Add the blocks listed in the file specified by
+.BI \-k
+When combined with the
+.B \-c
+option, any existing bad blocks in the bad blocks list are preserved,
+and any new bad blocks found by running
+.BR badblocks (8)
+will be added to the existing bad blocks list.
+.TP
+.BI \-l " filename"
+Add the block numbers listed in the file specified by
.I filename
-to the list of bad blocks.
+to the list of bad blocks. The format of this file is the same as the
+one generated by the
+.BR badblocks (8)
+program. Note that the block numbers are based on the blocksize
+of the filesystem. Hence,
+.BR badblocks (8)
+must be given the blocksize of the filesystem in order to obtain correct
+results. As a result, it is much simpler and safer to use the
+.B -c
+option to
+.BR e2fsck ,
+since it will assure that the correct parameters are passed to the
+.B badblocks
+program.
.TP
-.I -L filename
-Set the bad blocks list to be the list of blocks specified by
+.BI \-L " filename"
+Set the bad blocks list to be the list of blocks specified by
.IR filename .
-(This option is the same as the
-.I -l
+(This option is the same as the
+.B \-l
option, except the bad blocks list is cleared before the blocks listed
in the file are added to the bad blocks list.)
.TP
-.I -n
-Open the filesystem read-only, and assume an answer of ``no'' to all
+.B \-n
+Open the filesystem read-only, and assume an answer of `no' to all
questions. Allows
.B e2fsck
-to be used non-interactively. (Note: if the
-.IR -c ,
-.IR -l ,
+to be used non-interactively. This option
+may not be specified at the same time as the
+.B \-p
or
-.I -L
-options are specified in addition to the
-.I -n
-option, then the filesystem will be opened read-write, to permit the
-bad-blocks list to be updated. However, no other changes will be made
-to the filesystem.)
+.B \-y
+options.
.TP
-.I -p
-Automatically repair ("preen") the file system without any questions.
+.B \-p
+Automatically repair ("preen") the file system. This option will cause
+.B e2fsck
+to automatically
+fix any filesystem problems that can be safely fixed without human
+intervention. If
+.B e2fsck
+discovers a problem which may require the system administrator
+to take additional corrective action,
+.B e2fsck
+will print a description of the problem and then exit with the value 4
+logically or'ed into the exit code. (See the \fBEXIT CODE\fR section.)
+This option is normally used by the system's boot scripts. It may not
+be specified at the same time as the
+.B \-n
+or
+.B \-y
+options.
.TP
-.I -r
+.B \-r
This option does nothing at all; it is provided only for backwards
compatibility.
-.IP
-.I -s
-This option will byte-swap the filesystem so that it is using the normalized,
-standard byte-order (which is i386 or little endian). If the filesystem is
-already in the standard byte-order, e2fsck will take no action.
-.TP
-.I -S
-This option will byte-swap the filesystem, regardless of its current
-byte-order.
.TP
-.I -t
+.B \-t
Print timing statistics for
.BR e2fsck .
If this option is used twice, additional timing statistics are printed
on a pass by pass basis.
.TP
-.I -v
+.B \-v
Verbose mode.
.TP
-.I -V
+.B \-V
Print version information and exit.
.TP
-.I -y
-Assume an answer of ``yes'' to all questions; allows
+.B \-y
+Assume an answer of `yes' to all questions; allows
.B e2fsck
-to be used non-interactively.
+to be used non-interactively. This option
+may not be specified at the same time as the
+.B \-n
+or
+.B \-p
+options.
+.TP
+.BI \-z " undo_file"
+Before overwriting a file system block, write the old contents of the block to
+an undo file. This undo file can be used with e2undo(8) to restore the old
+contents of the file system should something go wrong. If the empty string is
+passed as the undo_file argument, the undo file will be written to a file named
+e2fsck-\fIdevice\fR.e2undo in the directory specified via the
+\fIE2FSPROGS_UNDO_DIR\fR environment variable.
+
+WARNING: The undo file cannot be used to recover from a power or system crash.
.SH EXIT CODE
The exit code returned by
.B e2fsck
.br
\ 2\ \-\ File system errors corrected, system should
.br
-\ \ \ \ be rebooted if file system was mounted
+\ \ \ \ be rebooted
.br
\ 4\ \-\ File system errors left uncorrected
.br
.br
\ 16\ \-\ Usage or syntax error
.br
+\ 32\ \-\ E2fsck canceled by user request
+.br
\ 128\ \-\ Shared library error
.br
-.SH BUGS
+.SH SIGNALS
+The following signals have the following effect when sent to
+.BR e2fsck .
+.TP
+.B SIGUSR1
+This signal causes
+.B e2fsck
+to start displaying a completion bar or emitting progress information.
+(See discussion of the
+.B \-C
+option.)
+.TP
+.B SIGUSR2
+This signal causes
+.B e2fsck
+to stop displaying a completion bar or emitting progress information.
+.SH REPORTING BUGS
Almost any piece of software will have bugs. If you manage to find a
-filesystem which causes
+filesystem which causes
.B e2fsck
-to crash, or which
+to crash, or which
.B e2fsck
is unable to repair, please report it to the author.
.PP
Please include as much information as possible in your bug report.
Ideally, include a complete transcript of the
.B e2fsck
-run, so I can see exactly what error messages are displayed. If you
-have a writeable filesystem where the transcript can be stored, the
+run, so I can see exactly what error messages are displayed. (Make sure
+the messages printed by
+.B e2fsck
+are in English; if your system has been
+configured so that
+.BR e2fsck 's
+messages have been translated into another language, please set the the
+.B LC_ALL
+environment variable to
+.B C
+so that the transcript of e2fsck's output will be useful to me.)
+If you
+have a writable filesystem where the transcript can be stored, the
.BR script (1)
program is a handy way to save the output of
-.e2fsck
+.B e2fsck
to a file.
.PP
-It is also useful to send the output of
+It is also useful to send the output of
.BR dumpe2fs (8).
-If a specific inode or inodes seems to be giving
-.B e2fsck
+If a specific inode or inodes seems to be giving
+.B e2fsck
trouble, try running the
.BR debugfs (8)
-command and send the output of the
-.I stat
-command run on the relevant inode(s). If the inode is a directory,
-the debugfs
+command and send the output of the
+.BR stat (1u)
+command run on the relevant inode(s). If the inode is a directory, the
+.B debugfs
.I dump
command will allow you to extract the contents of the directory inode,
which can sent to me after being first run through
.BR uuencode (1).
+The most useful data you can send to help reproduce
+the bug is a compressed raw image dump of the filesystem, generated using
+.BR e2image (8).
+See the
+.BR e2image (8)
+man page for more details.
.PP
-Always include the full version string which
+Always include the full version string which
.B e2fsck
displays when it is run, so I know which version you are running.
+.SH ENVIRONMENT
+.TP
+.BI E2FSCK_CONFIG
+Determines the location of the configuration file (see
+.BR e2fsck.conf (5)).
.SH AUTHOR
-This version of
+This version of
.B e2fsck
-is written by Theodore Ts'o <tytso@mit.edu>.
+was written by Theodore Ts'o <tytso@mit.edu>.
.SH SEE ALSO
-.BR mke2fs (8),
-.BR tune2fs (8),
+.BR e2fsck.conf (5),
+.BR badblocks (8),
.BR dumpe2fs (8),
-.BR debugfs (8)
+.BR debugfs (8),
+.BR e2image (8),
+.BR mke2fs (8),
+.BR tune2fs (8)
git://git.whamcloud.com / tools / e2fsprogs.git / blobdiff