.\" -*- nroff -*-
.TH CHATTR 1 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
.SH NAME
-chattr \- change file attributes on a Linux second extended file system
+chattr \- change file attributes on a Linux file system
.SH SYNOPSIS
.B chattr
[
-.B \-RV
+.B \-RVf
]
[
-.B -v
-version
+.B \-v
+.I version
]
[
-mode
+.B \-p
+.I project
+]
+[
+.I mode
]
.I files...
.SH DESCRIPTION
.B chattr
-changes the file attributes on a Linux second extended file system.
+changes the file attributes on a Linux file system.
+.PP
+The format of a symbolic
+.I mode
+is
+.BR +-= [ aAcCdDeFijmPsStTux ].
+.PP
+The operator
+.RB ' + '
+causes the selected attributes to be added to the
+existing attributes of the files;
+.RB ' - '
+causes them to be removed; and
+.RB ' = '
+causes them to be the only attributes that the files have.
.PP
-The format of a symbolic mode is +-=[ASacdisu].
+The letters
+.RB ' aAcCdDeFijmPsStTux '
+select the new attributes for the files:
+append only
+.RB ( a ),
+no atime updates
+.RB ( A ),
+compressed
+.RB ( c ),
+no copy on write
+.RB ( C ),
+no dump
+.RB ( d ),
+synchronous directory updates
+.RB ( D ),
+extent format
+.RB ( e ),
+case-insensitive directory lookups
+.RB ( F ),
+immutable
+.RB ( i ),
+data journaling
+.RB ( j ),
+don't compress
+.RB ( m ),
+project hierarchy
+.RB ( P ),
+secure deletion
+.RB ( s ),
+synchronous updates
+.RB ( S ),
+no tail-merging
+.RB ( t ),
+top of directory hierarchy
+.RB ( T ),
+undeletable
+.RB ( u ),
+and direct access for files
+.RB ( x ).
.PP
-The operator `+' causes the selected attributes to be added to the
-existing attributes of the files; `-' causes them to be removed; and
-`=' causes them to be the only attributes that the files have.
+The following attributes are read-only, and may be listed by
+.BR lsattr (1)
+but not modified by chattr:
+encrypted
+.RB ( E ),
+indexed directory
+.RB ( I ),
+inline data
+.RB ( N ),
+and verity
+.RB ( V ).
.PP
-The letters `ASacdisu' select the new attributes for the files:
-don't update atime (A), synchronous updates (S), append only (a),
-compressed (c), immutable (i), no dump (d),
-secure deletion (s), and undeletable (u).
+Not all flags are supported or utilized by all file systems; refer to
+file system-specific man pages such as
+.BR btrfs (5),
+.BR ext4 (5),
+.BR mkfs.f2fs (8),
+and
+.BR xfs (5)
+for more file system-specific details.
.SH OPTIONS
.TP
-.I -R
+.B \-R
Recursively change attributes of directories and their contents.
.TP
-.I -V
-Verbosely describe changed attributes.
+.B \-V
+Be verbose with chattr's output and print the program version.
+.TP
+.B \-f
+Suppress most error messages.
.TP
-.I -v version
-Set the files version.
+.BI \-v " version"
+Set the file's version/generation number.
+.TP
+.BI \-p " project"
+Set the file's project number.
.SH ATTRIBUTES
-When a file with the 'A' attribute set is modified, its atime record is
+.TP
+.B a
+A file with the 'a' attribute set can only be opened in append mode for
+writing. Only the superuser or a process possessing the
+CAP_LINUX_IMMUTABLE capability can set or clear this attribute.
+.TP
+.B A
+When a file with the 'A' attribute set is accessed, its atime record is
not modified. This avoids a certain amount of disk I/O for laptop
systems.
-
-A file with the `a' attribute set can only be open in append mode for writing.
-
-A file with the `c' attribute set is automatically compressed on the disk
-by the kernel. A read from this file returns uncompressed data. A write to
-this file compresses data before storing them on the disk.
-
-A file with the `d' attribute set is not candidate for backup when the
+.TP
+.B c
+A file with the 'c' attribute set is automatically compressed on the disk
+by the kernel. A read from this file returns uncompressed data. A write to
+this file compresses data before storing them on the disk. Note: please
+make sure to read the bugs and limitations section at the end of this
+document. (Note: For btrfs, If the 'c' flag is set, then the 'C' flag
+cannot be set. Also conflicts with btrfs mount option 'nodatasum')
+.TP
+.B C
+A file with the 'C' attribute set will not be subject to copy-on-write
+updates. This flag is only supported on file systems which perform
+copy-on-write. (Note: For btrfs, the 'C' flag should be
+set on new or empty files. If it is set on a file which already has
+data blocks, it is undefined when the blocks assigned to the file will
+be fully stable. If the 'C' flag is set on a directory, it will have no
+effect on the directory, but new files created in that directory will
+have the No_COW attribute set. If the 'C' flag is set, then the 'c' flag
+cannot be set.)
+.TP
+.B d
+A file with the 'd' attribute set is not a candidate for backup when the
.BR dump (8)
program is run.
-
-A file with the `i' attribute cannot be modified: it cannot be deleted or
-renamed, no link can be created to this file and no data can be written
-to the file. Only the superuser can set or clear this attribute.
-
-When a file with the `s' attribute set is deleted, its blocks are zeroed and
-written back to the disk.
-
-When a file with the `S' attribute set is modified,
-the changes are written synchronously on the disk; this is equivalent to
-the `sync' mount option applied to a subset of the files.
-
-When a file with the `u' attribute set is deleted, its contents are saved.
-This allows the user to ask for its undeletion.
-
+.TP
+.B D
+When a directory with the 'D' attribute set is modified,
+the changes are written synchronously to the disk; this is equivalent to
+the 'dirsync' mount option applied to a subset of the files.
+.TP
+.B e
+The 'e' attribute indicates that the file is using extents for mapping
+the blocks on disk. It may not be removed using
+.BR chattr (1).
+.TP
+.B E
+A file, directory, or symlink with the 'E' attribute set is encrypted by the
+file system. This attribute may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B F
+A directory with the 'F' attribute set indicates that all the path
+lookups inside that directory are made in a case-insensitive fashion.
+This attribute can only be changed in empty directories on file systems
+with the casefold feature enabled.
+.TP
+.B i
+A file with the 'i' attribute cannot be modified: it cannot be deleted or
+renamed, no link can be created to this file, most of the file's
+metadata can not be modified, and the file can not be opened in write mode.
+Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
+capability can set or clear this attribute.
+.TP
+.B I
+The 'I' attribute is used by the htree code to indicate that a directory
+is being indexed using hashed trees. It may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B j
+A file with the 'j' attribute has all of its data written to the ext3 or
+ext4 journal before being written to the file itself, if the file system
+is mounted with the "data=ordered" or "data=writeback" options and the
+file system has a journal. When the file system is mounted with the
+"data=journal" option all file data is already journalled and this
+attribute has no effect. Only the superuser or a process possessing the
+CAP_SYS_RESOURCE capability can set or clear this attribute.
+.TP
+.B m
+A file with the 'm' attribute is excluded from compression on file
+systems that support per-file compression.
+.TP
+.B N
+A file with the 'N' attribute set indicates that the file has data
+stored inline, within the inode itself. It may not be set or cleared
+using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.TP
+.B P
+A directory with the 'P' attribute set will enforce a hierarchical
+structure for project id's. This means that files and directories created
+in the directory will inherit the project id of the directory, rename
+operations are constrained so when a file or directory is moved into
+another directory, that the project ids must match. In addition, a
+hard link to file can only be created when the project id for the file
+and the destination directory match.
+.TP
+.B s
+When a file with the 's' attribute set is deleted, its blocks are zeroed
+and written back to the disk. Note: please make sure to read the bugs
+and limitations section at the end of this document.
+.TP
+.B S
+When a file with the 'S' attribute set is modified,
+the changes are written synchronously to the disk; this is equivalent to
+the 'sync' mount option applied to a subset of the files.
+.TP
+.B t
+A file with the 't' attribute will not have a partial block fragment at
+the end of the file merged with other files (for those file systems which
+support tail-merging). This is necessary for applications such as LILO
+which read the file system directly, and which don't understand tail-merged
+files. Note: As of this writing, the ext2, ext3, and ext4 file systems do
+not support tail-merging.
+.TP
+.B T
+A directory with the 'T' attribute will be deemed to be the top of
+directory hierarchies for the purposes of the Orlov block allocator.
+This is a hint to the block allocator used by ext3 and ext4 that the
+subdirectories under this directory are not related, and thus should be
+spread apart for allocation purposes. For example it is a very good
+idea to set the 'T' attribute on the /home directory, so that /home/john
+and /home/mary are placed into separate block groups. For directories
+where this attribute is not set, the Orlov block allocator will try to
+group subdirectories closer together where possible.
+.TP
+.B u
+When a file with the 'u' attribute set is deleted, its contents are
+saved. This allows the user to ask for its undeletion. Note: please
+make sure to read the bugs and limitations section at the end of this
+document.
+.TP
+.B x
+A file with the 'x' requests the use of direct access (dax) mode, if the
+kernel supports DAX. This can be overridden by the 'dax=never' mount
+option. For more information see the kernel documentation for dax:
+<https://www.kernel.org/doc/html/latest/filesystems/dax.html>.
+.IP
+If the attribute is set on an existing directory, it will be inherited
+by all files and subdirectories that are subsequently created in the
+directory. If an existing directory has contained some files and
+subdirectories, modifying the attribute on the parent directory doesn't
+change the attributes on these files and subdirectories.
+.TP
+.B V
+A file with the 'V' attribute set has fs-verity enabled. It cannot be
+written to, and the file system will automatically verify all data read
+from it against a cryptographic hash that covers the entire file's
+contents, e.g. via a Merkle tree. This makes it possible to efficiently
+authenticate the file. This attribute may not be set or cleared using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.PP
.SH AUTHOR
.B chattr
-was written by Remy Card <card@masi.ibp.fr>, the developer and maintainer
-of the ext2 fs.
+was written by Remy Card <Remy.Card@linux.org>. It is currently being
+maintained by Theodore Ts'o <tytso@alum.mit.edu>.
.SH BUGS AND LIMITATIONS
-As of ext2 fs 0.5a, the `c' and `u' attribute are not honoured by the kernel
-code. As of the Linux 2.0 kernel, the 'A' attribute is not yet supported by
-the kernel code. (The noatime code is still in testing.)
+The 'c', 's', and 'u' attributes are not honored
+by the ext2, ext3, and ext4 file systems as implemented in the current
+mainline Linux kernels.
+Setting 'a' and 'i' attributes will not affect the ability to write
+to already existing file descriptors.
.PP
-These attributes will be implemented in a future ext2 fs version.
+The 'j' option is only useful for ext3 and ext4 file systems.
+.PP
+The 'D' option is only useful on Linux kernel 2.5.19 and later.
.SH AVAILABILITY
.B chattr
-is available for anonymous ftp from ftp.ibp.fr and tsx-11.mit.edu in
-/pub/linux/packages/ext2fs.
+is part of the e2fsprogs package and is available from
+http://e2fsprogs.sourceforge.net.
.SH SEE ALSO
-.BR lsattr (1)
+.BR lsattr (1),
+.BR btrfs (5),
+.BR ext4 (5),
+.BR mkfs.f2fs (8),
+.BR xfs (5).
git://git.whamcloud.com / tools / e2fsprogs.git / blobdiff