man: list xfs_io lsattr inode flag letters
PATCH 1/1 man: list xfs_io lsattr inode flag letters
From: Darrick J. Wong <[email protected]>
The section of the xfs_io manpage for the 'chattr' command says to refer to xfsctl(3) for information on the flags. The inode flag information was moved to ioctl_xfs_fssetxattr(2) ages ago, and it never actually mapped the inode flag letters to inode flag bits, so add those to the xfs_io manpage.
--- man/man8/xfs_io.8 | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 6 deletions(-)
man/man8/xfs_io.8 +117 -6
@@ -794,18 +794,129 @@ for all directory entries below the currently open file can be used to restrict the output to directories only). This is a depth first descent, it does not follow symlinks and it also does not cross mount points. + +The current inode flag letters are: + +.PD 0 +.RS +.TP 0.5i +.SM "r (XFS_XFLAG_REALTIME)" +The file is a realtime file. + +.TP +.SM "p (XFS_XFLAG_PREALLOC)" +The file has preallocated space. + +.TP +.SM "i (XFS_XFLAG_IMMUTABLE)" +The file is immutable - it cannot be modified, 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 flag. + +.TP +.SM "a (XFS_XFLAG_APPEND)" +The file is append-only - it 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 flag. + +.TP +.SM "s (XFS_XFLAG_SYNC)" +All writes to the file are synchronous. + +.TP +.SM "A (XFS_XFLAG_NOATIME)" +When the file is accessed, its atime record is not modified. + +.TP +.SM "d (XFS_XFLAG_NODUMP)" +The file should be skipped by backup utilities. + +.TP +.SM "t (XFS_XFLAG_RTINHERIT)" +New files created in this directory will be automatically flagged as realtime. +New directories created in the directory will inherit the inheritance bit. + +.TP +.SM "P (XFS_XFLAG_PROJINHERIT)" +New files and directories created in the directory will inherit the parent's +project ID. +New directories also inherit the project ID and project inheritance bit. + +.TP +.SM "n (XFS_XFLAG_NOSYMLINKS)" +Can only be set on a directory and disallows creation of symbolic links in the +directory. + +.TP +.SM "e (XFS_XFLAG_EXTSIZE)" +Extent size hint - if a basic extent size value is set on the file then the +allocator will try allocate in multiples of the set size for this file. +This only applies to non-realtime files. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. + +.TP +.SM "E (XFS_XFLAG_EXTSZINHERIT)" +New files and directories created in the directory will inherit the parent's +basic extent size value (see above). +Can only be set on a directory. + +.TP +.SM "f (XFS_XFLAG_NODEFRAG)" +The file should be skipped during a defragmentation operation. +When applied to a directory, new files and directories created will +inherit the no\-defrag state. + +.TP +.SM "S (XFS_XFLAG_FILESTREAM)" +Filestream allocator - allows a directory to reserve an allocation group for +exclusive use by files created within that directory. +Files being written in other directories will not use the same allocation group +and so files within different directories will not interleave +extents on disk. +The reservation is only active while files are being created and written into +the directory. + +.TP +.SM "x (XFS_XFLAG_DAX)" +If the filesystem lives on directly accessible persistent memory, reads and +writes to this file will go straight to the persistent memory, bypassing the +page cache. +A file with this flag set cannot share blocks. +If set on a directory, new files and directories created will inherit the +persistent memory capability. + +.TP +.SM "C (XFS_XFLAG_COWEXTSIZE)" +Copy on Write Extent size hint - if a CoW extent size value is set on the file, +the allocator will allocate extents for staging a copy on write operation +in multiples of the set size for this file. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. +If the CoW extent size is set on a directory, then new file and directories +created in the directory will inherit the parent's CoW extent size value. + +.TP +.SM "X (XFS_XFLAG_HASATTR)" +The file has extended attributes associated with it. +This flag cannot be changed via chattr. +.RE + .TP .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfSxC " ]" Change extended inode flags on the currently open file. The .B \-R and .B \-D -options have the same meaning as above. The mapping between each -letter and the inode flags (refer to -.BR xfsctl (3) -for the full list) is available via the -.B help -command. +options have the same meaning as above. + +See the +.B lsattr +command above for the list of inode flag letters. + .TP .BI "flink " path Link the currently open file descriptor into the filesystem namespace.
Quoted 7 lines · Darrick J. Wong
From: Darrick J. Wong <[email protected]>
The section of the
xfs_iomanpage for the 'chattr' command says to refer to xfsctl(3) for information on the flags. The inode flag information was moved toioctl_xfs_fssetxattr(2)ages ago, and it never actually mapped the inode flag letters to inode flag bits, so add those to thexfs_iomanpage.
Hm, ok. The info is in the command's help output but I suppose it's useful enough to have it in the (a?) manpage, too.
OTOH this cuts & pastes quite a lot from the ioctl_xfs_fsgetxattr and I get nervous when we do that because it /will/ get out of sync.
I wonder if we can just say "refer to help output for flag mappings, and to ioctl_xfs_fsgetxattr for flag descriptions?"
Or would it suffice to just fix up the existing text:
The mapping between each
letter and the inode flags (refer to
.BR ioctl_xfs_fssetxattr (2)
for the full list) is available via the
.B help
command.
Quoted 146 lines
Signed-off-by Darrick J. Wong <[email protected]>--- man/man8/xfs_io.8 | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 6 deletions(-)man/man8/xfs_io.8 +117
-6@@ -794,18 +794,129 @@ for all directory entries below the currently open file can be used to restrict the output to directories only). This is a depth first descent, it does not follow symlinks and it also does not cross mount points. + +The current inode flag letters are: + +.PD 0 +.RS +.TP 0.5i +.SM "r (XFS_XFLAG_REALTIME)" +The file is a realtime file. + +.TP +.SM "p (XFS_XFLAG_PREALLOC)" +The file has preallocated space. + +.TP +.SM "i (XFS_XFLAG_IMMUTABLE)" +The file is immutable - it cannot be modified, 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 flag. + +.TP +.SM "a (XFS_XFLAG_APPEND)" +The file is append-only - it 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 flag. + +.TP +.SM "s (XFS_XFLAG_SYNC)" +All writes to the file are synchronous. + +.TP +.SM "A (XFS_XFLAG_NOATIME)" +When the file is accessed, its atime record is not modified. + +.TP +.SM "d (XFS_XFLAG_NODUMP)" +The file should be skipped by backup utilities. + +.TP +.SM "t (XFS_XFLAG_RTINHERIT)" +New files created in this directory will be automatically flagged as realtime. +New directories created in the directory will inherit the inheritance bit. + +.TP +.SM "P (XFS_XFLAG_PROJINHERIT)" +New files and directories created in the directory will inherit the parent's +project ID. +New directories also inherit the project ID and project inheritance bit. + +.TP +.SM "n (XFS_XFLAG_NOSYMLINKS)" +Can only be set on a directory and disallows creation of symbolic links in the +directory. + +.TP +.SM "e (XFS_XFLAG_EXTSIZE)" +Extent size hint - if a basic extent size value is set on the file then the +allocator will try allocate in multiples of the set size for this file. +This only applies to non-realtime files. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. + +.TP +.SM "E (XFS_XFLAG_EXTSZINHERIT)" +New files and directories created in the directory will inherit the parent's +basic extent size value (see above). +Can only be set on a directory. + +.TP +.SM "f (XFS_XFLAG_NODEFRAG)" +The file should be skipped during a defragmentation operation. +When applied to a directory, new files and directories created will +inherit the no\-defrag state. + +.TP +.SM "S (XFS_XFLAG_FILESTREAM)" +Filestream allocator - allows a directory to reserve an allocation group for +exclusive use by files created within that directory. +Files being written in other directories will not use the same allocation group +and so files within different directories will not interleave +extents on disk. +The reservation is only active while files are being created and written into +the directory. + +.TP +.SM "x (XFS_XFLAG_DAX)" +If the filesystem lives on directly accessible persistent memory, reads and +writes to this file will go straight to the persistent memory, bypassing the +page cache. +A file with this flag set cannot share blocks. +If set on a directory, new files and directories created will inherit the +persistent memory capability. + +.TP +.SM "C (XFS_XFLAG_COWEXTSIZE)" +Copy on Write Extent size hint - if a CoW extent size value is set on the file, +the allocator will allocate extents for staging a copy on write operation +in multiples of the set size for this file. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. +If the CoW extent size is set on a directory, then new file and directories +created in the directory will inherit the parent's CoW extent size value. + +.TP +.SM "X (XFS_XFLAG_HASATTR)" +The file has extended attributes associated with it. +This flag cannot be changed via chattr. +.RE + .TP .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfSxC " ]" Change extended inode flags on the currently open file. The .B \-R and .B \-D -options have the same meaning as above. The mapping between each -letter and the inode flags (refer to -.BR xfsctl (3) -for the full list) is available via the -.B help -command. +options have the same meaning as above. + +See the +.B lsattr +command above for the list of inode flag letters. + .TP .BI "flink " path Link the currently open file descriptor into the filesystem namespace.
Quoted 18 lines · Eric Sandeen
Quoted 7 lines · Darrick J. Wong
From: Darrick J. Wong <[email protected]>
The section of the
xfs_iomanpage for the 'chattr' command says to refer to xfsctl(3) for information on the flags. The inode flag information was moved toioctl_xfs_fssetxattr(2)ages ago, and it never actually mapped the inode flag letters to inode flag bits, so add those to thexfs_iomanpage.Hm, ok. The info is in the command's help output but I suppose it's useful enough to have it in the (a?) manpage, too.
OTOH this cuts & pastes quite a lot from the
ioctl_xfs_fsgetxattrand I get nervous when we do that because it /will/ get out of sync.I wonder if we can just say "refer to help output for flag mappings, and to
ioctl_xfs_fsgetxattrfor flag descriptions?"
Quoted 8 lines
Or would it suffice to just fix up the existing text:
The mapping between each
letter and the inode flags (refer to
.BRioctl_xfs_fssetxattr(2)
for the full list) is available via the
.B help
command.
Hmm, I guess that would work too?
Or how about add the raw mapping from letter to flag in the manpage:
"The inode flags are as follows:
o XFS_XFLAG_OSCAR
t XFS_XFLAG_THE
g XFS_XFLAG_GROUCH"
? :)
/bikeshedding
--D
Quoted 146 lines
Quoted 146 lines
Signed-off-by Darrick J. Wong <[email protected]>--- man/man8/xfs_io.8 | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 6 deletions(-)man/man8/xfs_io.8 +117
-6@@ -794,18 +794,129 @@ for all directory entries below the currently open file can be used to restrict the output to directories only). This is a depth first descent, it does not follow symlinks and it also does not cross mount points. + +The current inode flag letters are: + +.PD 0 +.RS +.TP 0.5i +.SM "r (XFS_XFLAG_REALTIME)" +The file is a realtime file. + +.TP +.SM "p (XFS_XFLAG_PREALLOC)" +The file has preallocated space. + +.TP +.SM "i (XFS_XFLAG_IMMUTABLE)" +The file is immutable - it cannot be modified, 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 flag. + +.TP +.SM "a (XFS_XFLAG_APPEND)" +The file is append-only - it 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 flag. + +.TP +.SM "s (XFS_XFLAG_SYNC)" +All writes to the file are synchronous. + +.TP +.SM "A (XFS_XFLAG_NOATIME)" +When the file is accessed, its atime record is not modified. + +.TP +.SM "d (XFS_XFLAG_NODUMP)" +The file should be skipped by backup utilities. + +.TP +.SM "t (XFS_XFLAG_RTINHERIT)" +New files created in this directory will be automatically flagged as realtime. +New directories created in the directory will inherit the inheritance bit. + +.TP +.SM "P (XFS_XFLAG_PROJINHERIT)" +New files and directories created in the directory will inherit the parent's +project ID. +New directories also inherit the project ID and project inheritance bit. + +.TP +.SM "n (XFS_XFLAG_NOSYMLINKS)" +Can only be set on a directory and disallows creation of symbolic links in the +directory. + +.TP +.SM "e (XFS_XFLAG_EXTSIZE)" +Extent size hint - if a basic extent size value is set on the file then the +allocator will try allocate in multiples of the set size for this file. +This only applies to non-realtime files. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. + +.TP +.SM "E (XFS_XFLAG_EXTSZINHERIT)" +New files and directories created in the directory will inherit the parent's +basic extent size value (see above). +Can only be set on a directory. + +.TP +.SM "f (XFS_XFLAG_NODEFRAG)" +The file should be skipped during a defragmentation operation. +When applied to a directory, new files and directories created will +inherit the no\-defrag state. + +.TP +.SM "S (XFS_XFLAG_FILESTREAM)" +Filestream allocator - allows a directory to reserve an allocation group for +exclusive use by files created within that directory. +Files being written in other directories will not use the same allocation group +and so files within different directories will not interleave +extents on disk. +The reservation is only active while files are being created and written into +the directory. + +.TP +.SM "x (XFS_XFLAG_DAX)" +If the filesystem lives on directly accessible persistent memory, reads and +writes to this file will go straight to the persistent memory, bypassing the +page cache. +A file with this flag set cannot share blocks. +If set on a directory, new files and directories created will inherit the +persistent memory capability. + +.TP +.SM "C (XFS_XFLAG_COWEXTSIZE)" +Copy on Write Extent size hint - if a CoW extent size value is set on the file, +the allocator will allocate extents for staging a copy on write operation +in multiples of the set size for this file. +See +.BR ioctl_xfs_fsgetxattr "(2)" +for more information. +If the CoW extent size is set on a directory, then new file and directories +created in the directory will inherit the parent's CoW extent size value. + +.TP +.SM "X (XFS_XFLAG_HASATTR)" +The file has extended attributes associated with it. +This flag cannot be changed via chattr. +.RE + .TP .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfSxC " ]" Change extended inode flags on the currently open file. The .B \-R and .B \-D -options have the same meaning as above. The mapping between each -letter and the inode flags (refer to -.BR xfsctl (3) -for the full list) is available via the -.B help -command. +options have the same meaning as above. + +See the +.B lsattr +command above for the list of inode flag letters. + .TP .BI "flink " path Link the currently open file descriptor into the filesystem namespace.
Quoted 28 lines · Darrick J. Wong
Quoted 18 lines · Eric Sandeen
Quoted 7 lines · Darrick J. Wong
From: Darrick J. Wong <[email protected]>
The section of the
xfs_iomanpage for the 'chattr' command says to refer to xfsctl(3) for information on the flags. The inode flag information was moved toioctl_xfs_fssetxattr(2)ages ago, and it never actually mapped the inode flag letters to inode flag bits, so add those to thexfs_iomanpage.Hm, ok. The info is in the command's help output but I suppose it's useful enough to have it in the (a?) manpage, too.
OTOH this cuts & pastes quite a lot from the
ioctl_xfs_fsgetxattrand I get nervous when we do that because it /will/ get out of sync.I wonder if we can just say "refer to help output for flag mappings, and to
ioctl_xfs_fsgetxattrfor flag descriptions?"Quoted 8 lines
Or would it suffice to just fix up the existing text:
The mapping between each
letter and the inode flags (refer to
.BRioctl_xfs_fssetxattr(2)
for the full list) is available via the
.B help
command.
Quoted 8 lines
Hmm, I guess that would work too?
Or how about add the raw mapping from letter to flag in the manpage:
"The inode flags are as follows:
oXFS_XFLAG_OSCAR
tXFS_XFLAG_THE
gXFS_XFLAG_GROUCH"
I guess to tie it all together we could adopt the current help output descriptions, something like
r realtime (XFS_XFLAG_REALTIME) i immutable (XFS_XFLAG_IMMUTABLE) a append-only ( ....)
... see ioctl_xfs_fsgetxattr for detailed flag descriptions.
I dunno, or am I too averse to the cut & paste in the original patch?
Quoted 3 lines
? :)
/bikeshedding
/waffling
-Eric