X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=misc%2Fchattr.1.in;h=50c54e7d722b66b8faf1d3d18aea46f75b385853;hb=64ed1351c8ffaa07944dd16780879a62f7d2df7c;hp=75b3ed8c466bcc351c12d902d51dfd41a9a7176f;hpb=a93a4c724f20f752bb49639f6704bc5d2f8f00bd;p=tools%2Fe2fsprogs.git diff --git a/misc/chattr.1.in b/misc/chattr.1.in index 75b3ed8..50c54e7 100644 --- a/misc/chattr.1.in +++ b/misc/chattr.1.in @@ -12,6 +12,10 @@ chattr \- change file attributes on a Linux file system .I version ] [ +.B \-p +.I project +] +[ .I mode ] .I files... @@ -19,45 +23,80 @@ chattr \- change file attributes on a Linux file system .B chattr changes the file attributes on a Linux file system. .PP -The format of a symbolic mode is +-=[aAcCdDeijsStTu]. +The format of a symbolic +.I mode +is +.BR +-= [ aAcCdDeFijmPsStTux ]. .PP -The operator '+' causes the selected attributes to be added to the -existing attributes of the files; '-' causes them to be removed; and '=' +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 letters 'aAcCdDeijsStTu' select the new attributes for the files: -append only (a), -no atime updates (A), -compressed (c), -no copy on write (C), -no dump (d), -synchronous directory updates (D), -extent format (e), -immutable (i), -data journalling (j), -secure deletion (s), -synchronous updates (S), -no tail-merging (t), -top of directory hierarchy (T), -and undeletable (u). +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 following attributes are read-only, and may be listed by .BR lsattr (1) but not modified by chattr: -compression error (E), -huge file (h), -indexed directory (I), -inline data (N), -compression raw access (X), -and compressed dirty file (Z). +encrypted +.RB ( E ), +indexed directory +.RB ( I ), +inline data +.RB ( N ), +and verity +.RB ( V ). .PP -Not all flags are supported or utilized by all filesystems; refer to -filesystem-specific man pages such as +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 filesystem-specific details. +for more file system-specific details. .SH OPTIONS .TP .B \-R @@ -71,21 +110,30 @@ Suppress most error messages. .TP .BI \-v " version" Set the file's version/generation number. +.TP +.BI \-p " project" +Set the file's project number. .SH ATTRIBUTES -A file with the 'a' attribute set can only be open in append mode for writing. -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE -capability can set or clear this attribute. -.PP +.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. -.PP +.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. -.PP +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 @@ -93,74 +141,100 @@ 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 -the No_COW attribute.) -.PP -A file with the 'd' attribute set is not candidate for backup when the +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. -.PP +.TP +.B D When a directory with the 'D' attribute set is modified, -the changes are written synchronously on the disk; this is equivalent to +the changes are written synchronously to the disk; this is equivalent to the 'dirsync' mount option applied to a subset of the files. -.PP +.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). -.PP -The 'E' attribute is used by the experimental compression patches to -indicate that a compressed file has a compression error. It may not be -set or reset using -.BR chattr (1), -although it can be displayed by -.BR lsattr (1). -.PP -The 'h' attribute indicates the file is storing its blocks in units of the -filesystem blocksize instead of in units of sectors, and means that the file -is (or at one time was) larger than 2TB. It may not be set or reset using +.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). -.PP +.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 and no data can be written -to the file. Only the superuser or a process possessing the -CAP_LINUX_IMMUTABLE capability can set or clear this attribute. -.PP +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 reset using +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). -.PP -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 filesystem -is mounted with the "data=ordered" or "data=writeback" options. When the -filesystem 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. -.PP +.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 reset using +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). -.PP +.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. -.PP +.TP +.B S When a file with the 'S' attribute set is modified, -the changes are written synchronously on the disk; this is equivalent to +the changes are written synchronously to the disk; this is equivalent to the 'sync' mount option applied to a subset of the files. -.PP +.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 filesystems which +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 filesystem directly, and which don't understand tail-merged -files. Note: As of this writing, the ext2 or ext3 filesystems do not -(yet, except in very experimental patches) support tail-merging. -.PP +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 @@ -170,21 +244,31 @@ 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. -.PP +.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. -.PP -The 'X' attribute is used by the experimental compression patches to -indicate that the raw contents of a compressed file can be accessed -directly. It currently may not be set or reset using -.BR chattr (1), -although it can be displayed by -.BR lsattr (1). -.PP -The 'Z' attribute is used by the experimental compression patches to -indicate a compressed file is dirty. It may not be set or reset using +.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: +. +.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). @@ -195,10 +279,12 @@ was written by Remy Card . It is currently being maintained by Theodore Ts'o . .SH BUGS AND LIMITATIONS The 'c', 's', and 'u' attributes are not honored -by the ext2, ext3, and ext4 filesystems as implemented in the current +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 -The 'j' option is only useful if the filesystem is mounted as ext3 or ext4. +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 @@ -209,4 +295,5 @@ http://e2fsprogs.sourceforge.net. .BR lsattr (1), .BR btrfs (5), .BR ext4 (5), +.BR mkfs.f2fs (8), .BR xfs (5).