X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=misc%2Fchattr.1.in;h=028ae9e7ca4c798d1507c23052aabb6a7a1fa477;hb=8dd69539230cb236ed375111c93f36f1d515981a;hp=6c9ecf106417c0a96ee2600b0cfe5ea8e49ad187;hpb=51f8f8d260bab06d8c5c3aa12470e7787dae4199;p=tools%2Fe2fsprogs.git diff --git a/misc/chattr.1.in b/misc/chattr.1.in index 6c9ecf1..028ae9e 100644 --- a/misc/chattr.1.in +++ b/misc/chattr.1.in @@ -1,141 +1,208 @@ .\" -*- 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 .I version ] [ +.B \-p +.I project +] +[ .I mode ] .I files... .SH DESCRIPTION .B chattr -changes the file attributes on a Linux second extended file system. -.PP -The format of a symbolic mode is +-=[ASacDdIijsTtu]. -.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. -.PP -The letters `ASacDdijsu' select the new attributes for the files: -don't update atime (A), synchronous updates (S), synchronous directory -updates (D), append only (a), compressed (c), no dump (d), immutable (i), -data journalling (j), secure deletion (s), top of directory hierarchy -(T), no tail-merging (t), and undeletable (u). +changes the file attributes on a Linux file system. +.PP +The format of a symbolic mode is +-=[aAcCdDeijPsStTu]. +.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. +.PP +The letters 'aAcCdDeijPsStTu' 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), +project hierarchy (P), +secure deletion (s), +synchronous updates (S), +no tail-merging (t), +top of directory hierarchy (T), +and undeletable (u). +.PP +The following attributes are read-only, and may be listed by +.BR lsattr (1) +but not modified by chattr: +encrypted (E), +indexed directory (I), +and inline data (N). +.PP +Not all flags are supported or utilized by all filesystems; refer to +filesystem-specific man pages such as +.BR btrfs (5), +.BR ext4 (5), +and +.BR xfs (5) +for more filesystem-specific details. .SH OPTIONS .TP .B \-R Recursively change attributes of directories and their contents. -Symbolic links encountered during recursive directory traversals are -ignored. .TP .B \-V Be verbose with chattr's output and print the program version. .TP +.B \-f +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 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 -A file with the `a' attribute set can only be open in append mode for writing. -Only the superuser or a process pessessing the CAP_LINUX_IMMUTABLE -capability can set or clear this attribute. -.PP -A file with the `c' attribute set is automatically compressed on the disk +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. +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 +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.) +.PP +A file with the 'd' attribute set is not candidate for backup when the +.BR dump (8) +program is run. .PP -When a directory with the `D' attribute set is modified, +When a directory with the 'D' attribute set is modified, the changes are written synchronously on the disk; this is equivalent to -the `dirsync' mount option applied to a subset of the files. +the 'dirsync' mount option applied to a subset of the files. .PP -A file with the `d' attribute set is not candidate for backup when the -.BR dump (8) -program is run. +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 +The 'E' attribute is used by the experimental encryption patches to +indicate that the file has been encrypted. It may not be +set or reset using .BR chattr (1), although it can be displayed by .BR lsattr (1). .PP +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. +.PP The 'I' attribute is used by the htree code to indicate that a directory -is behind indexed using hashed trees. It may not be set or reset using +is being indexed using hashed trees. It may not be set or reset using .BR chattr (1), although it can be displayed by .BR lsattr (1). .PP -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 pessessing the -CAP_LINUX_IMMUTABLE capability can set or clear this attribute. -.PP -A file with the `j' attribute has all of its data written to the ext3 -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=journalled" 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 -When a file with the `s' attribute set is deleted, its blocks are zeroed and -written back to the disk. -.PP -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. -.PP -A directory with the 'T' attribute will be deemed to be the top of -directory hierarchies for the purposes of the Orlov block allocator -(which is used in on systems with Linux 2.5.46 or later). +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 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 -A file with the 't' attribute will not have a partial block fragment at -the of the file merged with other files (for those filesystems which -support tail-merging). This is necessary for applications such as LILO -which read the filesystem directly, and who don't understand tail-merged -files. -.PP -When a file with the `u' attribute set is deleted, its contents are saved. -This allows the user to ask for its undeletion. -.PP -The 'X' attribute is used by the experimental compression patches to -indicate that a raw contents of a compressed file can be accessed -directly. It currently may not be set or reset using +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 .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 -.BR chattr (1), -although it can be displayed by -.BR lsattr (1). +A directory with the 'P' attribute set will enforce a hierarchical +structure for project id's. This means that files and directory 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 id's much match. In addition, a +hard link to file can only be created when the project id for the file +and the destination directory match. +.PP +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 +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. +.PP +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 +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 +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. +.PP +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 .SH AUTHOR .B chattr -was written by Remy Card . +was written by Remy Card . It is currently being +maintained by Theodore Ts'o . .SH BUGS AND LIMITATIONS -As of Linux 2.2, the `c', 's', and `u' attribute are not honored -by the kernel filesystem code. These attributes will be implemented -in a future ext2 fs version. +The 'c', 's', and 'u' attributes are not honored +by the ext2, ext3, and ext4 filesystems 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. +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. +The 'D' option is only useful on Linux kernel 2.5.19 and later. .SH AVAILABILITY .B chattr 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 xfs (5).