Skip to contentSkip to conversation

man: list xfs_io lsattr inode flag letters

PATCH Superseded Darrick J. Wong 2 participants 4 messages Dec 18, 2019

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

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
index 2f17c64c..26523ab8 100644
@@ -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.
#1 lore raw
Quoted 7 lines · Darrick J. Wong

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.

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
---
 man/man8/xfs_io.8 |  123 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 117 insertions(+), 6 deletions(-)
man/man8/xfs_io.8 +117 -6
index 2f17c64c..26523ab8 100644
@@ -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.
#2 lore raw
Quoted 18 lines · Eric Sandeen
Quoted 7 lines · Darrick J. Wong

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.

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?"

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
.BR ioctl_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
---
 man/man8/xfs_io.8 |  123 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 117 insertions(+), 6 deletions(-)
man/man8/xfs_io.8 +117 -6
index 2f17c64c..26523ab8 100644
@@ -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.
#3 lore raw
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_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.

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?"

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
.BR ioctl_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:
o XFS_XFLAG_OSCAR
t XFS_XFLAG_THE
g XFS_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