Message-Id: <D6C97BDC-9378-4BCD-A073-2B5527204306@dilger.ca>
Date:   Mon, 3 Feb 2020 13:41:42 -0700
From:   Andreas Dilger <adilger@...ger.ca>
To:     Jeremy Visser <jeremyvisser@...gle.com>
Cc:     linux-ext4@...r.kernel.org
Subject: Re: [PATCH] chattr.1: improve attribute formatting with labels and
 indented paragraphs

On Feb 2, 2020, at 7:37 PM, Jeremy Visser <jeremyvisser@...gle.com> wrote:
> 
> By convention, lists of options in man pages use a label followed by an
> indented description, such as this example from the Options section:
> 
>     -R     Recursively change attributes of directories and
>            their contents.
> 
> But the Attributes section places the available attributes mid-sentence,
> which makes it visually more difficult to parse:
> 
>     A file with the 'a' attribute set can only be opened
>     in append mode for writing.  [...]
> 
>     When a file with the 'A' attribute set is accessed, its
>     atime record is not modified.  [...]
> 
> This patch places a label beside each attribute description, which (in
> my opinion) improves readability, especially when visually skimming the
> list.  For example:
> 
>     a      A file with the 'a' attribute set can only be
>            opened in append mode for writing.
> 
>     A      When a file with the 'A' attribute set is accessed,
>            its atime record is not modified.
> 
> Signed-off-by: Jeremy Visser <jeremyvisser@...gle.com>

Looks like a good improvement.

Reviewed-by: Andreas Dilger <adilger@...ger.ca>

> ---
> misc/chattr.1.in | 59 ++++++++++++++++++++++++++++++++----------------
> 1 file changed, 40 insertions(+), 19 deletions(-)
> 
> diff --git a/misc/chattr.1.in b/misc/chattr.1.in
> index 66e791db..71e910c9 100644
> --- a/misc/chattr.1.in
> +++ b/misc/chattr.1.in
> @@ -79,20 +79,25 @@ Set the file's version/generation number.
> .BI \-p " project"
> Set the file's project number.
> .SH ATTRIBUTES
> +.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.
> -.PP
> +.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
> +.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
> @@ -101,42 +106,50 @@ 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
> +.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 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
> +.TP
> +.B E
> A file, directory, or symlink with the 'E' attribute set is encrypted by the
> filesystem.  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.
> -.PP
> +.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.
> -.PP
> +.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).
> -.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
> @@ -144,14 +157,16 @@ 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
> +.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).
> -.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 directory created
> in the directory will inherit the project id of the directory, rename
> @@ -159,22 +174,26 @@ 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
> +.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 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
> 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, ext3, and ext4 filesystems do
> not support tail-merging.
> -.PP
> +.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
> @@ -184,12 +203,14 @@ 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
> +.TP
> +.B V
> A file with the 'V' attribute set has fs-verity enabled.  It cannot be
> written to, and the filesystem will automatically verify all data read
> from it against a cryptographic hash that covers the entire file's
> --
> 2.25.0.341.g760bfbb309-goog
> 


Cheers, Andreas






Download attachment "signature.asc" of type "application/pgp-signature" (874 bytes)

Powered by blists - more mailing lists