* [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses
@ 2019-06-20 16:50 Darrick J. Wong
2019-06-20 16:50 ` [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage Darrick J. Wong
` (8 more replies)
0 siblings, 9 replies; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:50 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
Hi all,
Add documentation for all the ioctls that xfs_scrub uses, so that we
finally have some literature about how those interfaces are supposed to
work.
If you're going to start using this mess, you probably ought to just
pull from my git trees, which are linked below.
This is an extraordinary way to destroy everything. Enjoy!
Comments and questions are, as always, welcome.
--D
xfsprogs git tree:
https://git.kernel.org/cgit/linux/kernel/git/djwong/xfsprogs-dev.git/log/?h=document-ioctls
^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
@ 2019-06-20 16:50 ` Darrick J. Wong
2019-07-03 22:48 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 2/9] man: create a separate GEOMETRY " Darrick J. Wong
` (7 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:50 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Break out the xfs file attribute get and set ioctls into a separate
manpage to reduce clutter in xfsctl.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_fsgetxattr.2 | 245 ++++++++++++++++++++++++++++++++++++++
man/man2/ioctl_xfs_fsgetxattra.2 | 1
man/man2/ioctl_xfs_fssetxattr.2 | 1
man/man3/xfsctl.3 | 159 +------------------------
4 files changed, 255 insertions(+), 151 deletions(-)
create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
create mode 100644 man/man2/ioctl_xfs_fsgetxattra.2
create mode 100644 man/man2/ioctl_xfs_fssetxattr.2
diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
new file mode 100644
index 00000000..7462c46c
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsgetxattr.2
@@ -0,0 +1,245 @@
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSGETXATTR 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_fsgetxattr \- query information for an open file
+.SH SYNOPSIS
+.br
+.B #include <linux/fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
+.SH DESCRIPTION
+Query or set additional attributes associated with files in various file
+systems.
+The attributes are conveyed in a structure of the form:
+.PP
+.in +4n
+.nf
+struct fsxattr {
+ __u32 fsx_xflags;
+ __u32 fsx_extsize;
+ __u32 fsx_nextents;
+ __u32 fsx_projid;
+ __u32 fsx_cowextsize;
+ unsigned char fsx_pad[8];
+};
+.fi
+.in
+.PP
+.I fsx_xflags
+are extended flags that apply to this file.
+Refer to the section
+.B XFS INODE FLAGS
+below for more information.
+
+.PP
+.I fsx_extsize
+is the preferred extent allocation size for data blocks mapped to this file,
+in units of filesystem blocks.
+If this value is zero, the filesystem will choose a default option, which
+is currently zero.
+If
+.B XFS_IOC_FSSETXATTR
+is called with
+.B XFS_XFLAG_EXTSIZE
+set in
+.I fsx_xflags
+and this field is zero, the XFLAG will be cleared instead.
+.PP
+.I fsx_nextents
+is the number of data extents in this file.
+If
+.B XFS_IOC_FSGETXATTRA
+was used, then this is the number of extended attribute extents in the file.
+.PP
+.I fsx_projid
+is the project ID of this file.
+.PP
+.I fsx_cowextsize
+is the preferred extent allocation size for copy on write operations
+targeting this file, in units of filesystem blocks.
+If this field is zero, the filesystem will choose a default option,
+which is currently 128 filesystem blocks.
+If
+.B XFS_IOC_FSSETXATTR
+is called with
+.B XFS_XFLAG_COWEXTSIZE
+set in
+.I fsx_xflags
+and this field is zero, the XFLAG will be cleared instead.
+
+.PP
+.I fsx_pad
+must be zeroed.
+
+.SH XFS INODE FLAGS
+This field can be a combination of the following:
+
+.TP
+.B XFS_XFLAG_REALTIME
+The file is a realtime file.
+This bit can only be changed when the file is empty.
+.TP
+.B XFS_XFLAG_PREALLOC
+The file has preallocated space.
+.TP
+.B 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.
+If this flag is set before a
+.B XFS_IOC_FSSETXATTR
+call and would not be cleared by the call, then no other attributes can be
+changed and
+.B EPERM
+will be returned.
+.TP
+.B 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
+.B XFS_XFLAG_SYNC
+All writes to the file are synchronous.
+If set on a directory and the
+.B /proc/sys/fs/xfs/inherit_sync
+knob is set, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_NOATIME
+When the file is accessed, its atime record is not modified.
+If set on a directory and the
+.B /proc/sys/fs/xfs/inherit_noatime
+knob is set, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_NODUMP
+The file should be skipped by backup utilities.
+If set on a directory and the
+.B /proc/sys/fs/xfs/inherit_nodump
+knob is set, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_RTINHERIT
+Realtime inheritance bit - new files created in the directory
+will be automatically as realtime times.
+If set on a directory, new subdirectories created in the directory will also
+have the inheritance flag set.
+.TP
+.B XFS_XFLAG_PROJINHERIT
+Project inheritance bit - new files and directories created in
+this directory will inherit the project ID of this directory.
+If set on a directory, new subdirectories created in the directory will also
+have the inheritance flag set.
+.TP
+.B XFS_XFLAG_NOSYMLINKS
+Disallows creation of symbolic links in the directory.
+This flag can only be set on a directory.
+If set on a directory and the
+.B /proc/sys/fs/xfs/inherit_nosymlinks
+knob is set, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_EXTSIZE
+Extent size bit - if a basic extent size value is set on the file
+then the allocator will allocate in multiples of the set size for
+this file (see
+.B fsx_extsize
+below).
+This flag can only be set on a file if it is empty.
+.TP
+.B XFS_XFLAG_EXTSZINHERIT
+Extent size inheritance bit - new files and directories created in
+the directory will inherit the extent size value (see
+.B fsx_extsize
+below) of the parent directory.
+New subdirectories created in the directory will inherit the extent size
+inheritance bit.
+.TP
+.B XFS_XFLAG_NODEFRAG
+No defragment file bit - the file should be skipped during a defragmentation
+operation.
+If set on a directory and the
+.B /proc/sys/fs/xfs/inherit_nodefrag
+knob is set, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_FILESTREAM
+Filestream allocator bit - 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.
+If set on a directory, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B 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 cannot be reflinked and have the
+.BR XFS_XFLAG_DAX
+set at the same time.
+That is to say that DAX files cannot share blocks.
+If set on a directory, new files and subdirectories created in the directory
+will also have the flag set.
+.TP
+.B XFS_XFLAG_COWEXTSIZE
+Copy on Write Extent size bit - 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
+.B fsx_cowextsize
+below).
+If set on a directory, new files and subdirectories created in the directory
+will have both the flag and the CoW extent size value set.
+.TP
+.B XFS_XFLAG_HASATTR
+The file has extended attributes associated with it.
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EACCESS
+Caller does not have sufficient access to change the attributes.
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.TP
+.B EPERM
+Caller did not have permission to change the attributes.
+.SH CONFORMING TO
+This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
+Linux kernel.
+Not all fields may be understood by filesystems other than xfs.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_iflags (2)
diff --git a/man/man2/ioctl_xfs_fsgetxattra.2 b/man/man2/ioctl_xfs_fsgetxattra.2
new file mode 100644
index 00000000..9bd595ae
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsgetxattra.2
@@ -0,0 +1 @@
+.so man2/ioctl_xfs_fsgetxattr.2
diff --git a/man/man2/ioctl_xfs_fssetxattr.2 b/man/man2/ioctl_xfs_fssetxattr.2
new file mode 100644
index 00000000..9bd595ae
--- /dev/null
+++ b/man/man2/ioctl_xfs_fssetxattr.2
@@ -0,0 +1 @@
+.so man2/ioctl_xfs_fsgetxattr.2
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 462ccbd8..2992b5be 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -132,161 +132,17 @@ will fail with EINVAL.
All I/O requests are kept consistent with any data brought into
the cache with an access through a non-direct I/O file descriptor.
-.TP
-.B XFS_IOC_FSGETXATTR
-Get additional attributes associated with files in XFS file systems.
-The final argument points to a variable of type
-.BR "struct fsxattr" ,
-whose fields include:
-.B fsx_xflags
-(extended flag bits),
-.B fsx_extsize
-(nominal extent size in file system blocks),
-.B fsx_nextents
-(number of data extents in the file).
-A
-.B fsx_extsize
-value returned indicates that a preferred extent size was previously
-set on the file, a
-.B fsx_extsize
-of zero indicates that the defaults for that filesystem will be used.
-A
-.B fsx_cowextsize
-value returned indicates that a preferred copy on write extent size was
-previously set on the file, whereas a
-.B fsx_cowextsize
-of zero indicates that the defaults for that filesystem will be used.
-The current default for
-.B fsx_cowextsize
-is 128 blocks.
-Currently the meaningful bits for the
-.B fsx_xflags
-field are:
-.PD 0
-.RS
-.TP 1.0i
-.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
-The file is a realtime file.
-.TP
-.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
-The file has preallocated space.
-.TP
-.SM "Bit 3 (0x8) \- 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 "Bit 4 (0x10) \- 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 "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
-All writes to the file are synchronous.
-.TP
-.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
-When the file is accessed, its atime record is not modified.
-.TP
-.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
-The file should be skipped by backup utilities.
-.TP
-.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
-Realtime inheritance bit - new files created in the directory
-will be automatically realtime, and new directories created in
-the directory will inherit the inheritance bit.
-.TP
-.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
-Project inheritance bit - new files and directories created in
-the directory will inherit the parents project ID. New
-directories also inherit the project inheritance bit.
-.TP
-.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
-Can only be set on a directory and disallows creation of
-symbolic links in that directory.
-.TP
-.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
-Extent size bit - if a basic extent size value is set on the file
-then the allocator will allocate in multiples of the set size for
-this file (see
-.B XFS_IOC_FSSETXATTR
-below).
-.TP
-.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
-Extent size inheritance bit - new files and directories created in
-the directory will inherit the parents basic extent size value (see
-.B XFS_IOC_FSSETXATTR
-below).
-Can only be set on a directory.
-.TP
-.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
-No defragment file bit - the file should be skipped during a defragmentation
-operation. When applied to a directory, new files and directories created will
-inherit the no\-defrag bit.
-.TP
-.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
-Filestream allocator bit - 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 "Bit 15 (0x8000) \- 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 cannot be reflinked and have the
-.BR XFS_XFLAG_DAX
-set at the same time.
-That is to say that DAX files cannot share blocks.
-.TP
-.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
-Copy on Write Extent size bit - 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
-.B XFS_IOC_FSSETXATTR
-below).
-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 "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
-The file has extended attributes associated with it.
-.RE
.PP
-.PD
-
-.TP
-.B XFS_IOC_FSGETXATTRA
-Identical to
+.nf
.B XFS_IOC_FSGETXATTR
-except that the
-.B fsx_nextents
-field contains the number of attribute extents in the file.
-
+.B XFS_IOC_FSGETXATTRA
+.fi
+.PD 0
.TP
.B XFS_IOC_FSSETXATTR
-Set additional attributes associated with files in XFS file systems.
-The final argument points to a variable of type
-.BR "struct fsxattr" ,
-but only the following fields are used in this call:
-.BR fsx_xflags ,
-.BR fsx_extsize ,
-.BR fsx_cowextsize ,
-and
-.BR fsx_projid .
-The
-.B fsx_xflags
-realtime file bit and the file's extent size may be changed only
-when the file is empty, except in the case of a directory where
-the extent size can be set at any time (this value is only used
-for regular file allocations, so should only be set on a directory
-in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
-The copy on write extent size,
-.BR fsx_cowextsize ,
-can be set at any time.
+See
+.BR ioctl_xfs_fsgetxattr (2)
+for more information.
.TP
.B XFS_IOC_GETBMAP
@@ -649,6 +505,7 @@ The remainder of these operations will not be described further
as they are not of general use to applications.
.SH SEE ALSO
+.BR ioctl_xfs_fsgetxattr (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 2/9] man: create a separate GEOMETRY ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
2019-06-20 16:50 ` [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 15:01 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 3/9] man: create a separate FSBULKSTAT " Darrick J. Wong
` (6 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Break out the xfs geometry ioctl into a separate manpage so that we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_fsop_geometry.2 | 221 ++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 11 +-
2 files changed, 228 insertions(+), 4 deletions(-)
create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2
diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
new file mode 100644
index 00000000..c6e89efd
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsop_geometry.2
@@ -0,0 +1,221 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_fsop_geometry \- report XFS filesystem shape
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geom*" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geom_v1 *" arg );
+.SH DESCRIPTION
+Report the storage space parameters that influence allocation decisions in
+this XFS filesystem.
+This information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_geom {
+ __u32 blocksize;
+ __u32 rtextsize;
+ __u32 agblocks;
+ __u32 agcount;
+ __u32 logblocks;
+ __u32 sectsize;
+ __u32 inodesize;
+ __u32 imaxpct;
+ __u64 datablocks;
+ __u64 rtblocks;
+ __u64 rtextents;
+ __u64 logstart;
+ unsigned char uuid[16];
+ __u32 sunit;
+ __u32 swidth;
+ __s32 version;
+ __u32 flags;
+ __u32 logsectsize;
+ __u32 rtsectsize;
+ __u32 dirblocksize;
+ /* struct xfs_fsop_geom_v1 stops here. */
+
+ __u32 logsunit;
+};
+.fi
+.in
+.PP
+.I blocksize
+is the size of a fundamental filesystem block, in bytes.
+.PP
+.I rtextsize
+is the size of an extent on the realtime volume, in bytes.
+.PP
+.I agblocks
+is the size of an allocation group, in units of filesystem blocks.
+.PP
+.I agcount
+is the number of allocation groups in the filesystem.
+.PP
+.I logblocks
+is the size of the log, in units of filesystem blocks.
+.PP
+.I sectsize
+is the smallest amount of data that can be written to the data device
+atomically, in bytes.
+.PP
+.I inodesize
+is the size of an inode record, in bytes.
+.PP
+.I imaxpct
+is the maximum percentage of the filesystem that can be allocated to inode
+record blocks.
+.PP
+.I datablocks
+is the size of the data device, in units of filesystem blocks.
+.PP
+.I rtblocks
+is the size of the realtime device, in units of filesystem blocks.
+.PP
+.I rtextents
+is the number of extents that can be allocated on the realtime device.
+.PP
+.I logstart
+is the start of the log, in units of filesystem blocks.
+If the filesystem has an external log, this will be zero.
+.PP
+.I uuid
+is the universal unique identifier of the filesystem.
+.PP
+.I sunit
+is what the filesystem has been told is the size of a RAID stripe unit on the
+underlying data device, in filesystem blocks.
+.PP
+.I swidth
+is what the filesystem has been told is the width of a RAID stripe on the
+underlying data device, in units of RAID stripe units.
+.PP
+.I version
+is the version of this structure.
+This value will be XFS_FSOP_GEOM_VERSION.
+.PP
+.I flags
+tell us what features are enabled on the filesystem.
+Refer to the section
+.B FILESYSTEM FEATURE FLAGS
+below for more information about each feature.
+.PP
+.I logsectsize
+is the smallest amount of data that can be written to the log device atomically,
+in bytes.
+.PP
+.I rtsectsize
+is the smallest amount of data that can be written to the realtime device
+atomically, in bytes.
+.PP
+.I dirblocksize
+is the size of directory blocks, in bytes.
+.PP
+.I logsunit
+is what the filesystem has been told is the size of a RAID stripe unit on the
+underlying log device, in filesystem blocks.
+This field is meaningful only if the flag
+.B XFS_FSOP_GEOM_FLAGS_LOGV2
+is set.
+.SH FILESYSTEM FEATURE FLAGS
+Filesystem features are reported to userspace as a combination the following
+flags:
+.TP
+.B XFS_FSOP_GEOM_FLAGS_ATTR
+Extended attributes are present.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_NLINK
+This filesystem supports up to 2^32 links.
+If this flag is not set, the filesystem supports only 2^16 links.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_QUOTA
+Quotas are enabled.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_IALIGN
+Inodes are aligned for better performance.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DALIGN
+Filesystem tries to align data block allocations to RAID stripe units for
+better performance.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SHARED
+Unused.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_EXTFLG
+Filesystem supports unwritten extents.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DIRV2
+Directories are in version 2 format and maintain free space data for better
+performance.
+Version 1 format directories are no longer supported.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_LOGV2
+Log uses the V2 format.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SECTOR
+The log device has a sector size larger than 512 bytes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_ATTR2
+Filesystem contains V2 extended attributes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_PROJID32
+Project IDs can be as large as 2^32.
+If this flag is not set, the filesystem supports only 2^16 project IDs.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
+Case-insensitive lookups are supported on directories.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_LAZYSB
+On-disk superblock counters are updated only at unmount time.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_V5SB
+Metadata blocks are self describing and contain checksums.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_FTYPE
+Directories contain inode types in directory entries.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_FINOBT
+Filesystem maintains an index of free inodes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SPINODES
+Filesystem may allocate discontiguous inode chunks when free space is
+fragmented.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_RMAPBT
+Filesystem stores reverse mappings of blocks to owners.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_REFLINK
+Filesystem supports sharing blocks between files.
+.RE
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 2992b5be..1237eac6 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
be initialized to zero).
An error is returned if the inode number is invalid.
+.TP
+.B XFS_IOC_FSGEOMETRY
+See
+.BR ioctl_xfs_fsop_geometry (2)
+for more information.
+
.PP
.nf
.B XFS_IOC_THAW
@@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
These interfaces are used to implement various filesystem internal
operations on XFS filesystems.
For
-.B XFS_IOC_FSGEOMETRY
-(get filesystem mkfs time information), the output structure is of type
-.BR struct xfs_fsop_geom .
-For
.B XFS_FS_COUNTS
(get filesystem dynamic global information), the output structure is of type
.BR xfs_fsop_counts_t .
@@ -506,6 +508,7 @@ as they are not of general use to applications.
.SH SEE ALSO
.BR ioctl_xfs_fsgetxattr (2),
+.BR ioctl_xfs_fsop_geometry (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 3/9] man: create a separate FSBULKSTAT ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
2019-06-20 16:50 ` [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage Darrick J. Wong
2019-06-20 16:51 ` [PATCH 2/9] man: create a separate GEOMETRY " Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 16:22 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3 Darrick J. Wong
` (5 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Break out the xfs bulkstat ioctl into a separate manpage so that we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_fsbulkstat.2 | 216 +++++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 87 +---------------
2 files changed, 223 insertions(+), 80 deletions(-)
create mode 100644 man/man2/ioctl_xfs_fsbulkstat.2
diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
new file mode 100644
index 00000000..f50f80bd
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsbulkstat.2
@@ -0,0 +1,216 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSBULKSTAT 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_fsbulkstat \- query information for a batch of XFS inodes
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
+.SH DESCRIPTION
+Query stat information for a group of XFS inodes.
+These ioctls use
+.B struct xfs_fsop_bulkreq
+to set up a bulk transfer with the kernel:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_bulkreq {
+ __u64 *lastip;
+ __s32 count;
+ void *ubuffer;
+ __s32 *ocount;
+};
+.fi
+.in
+.PP
+.I lastip
+points to a value that will receive the number of the "last inode".
+This cannot be NULL.
+For
+.BR FSBULKSTAT ,
+this should be set to one less than the number of the first inode for which the
+caller wants information, or zero to start with the first inode in the
+filesystem.
+For
+.BR FSBULKSTAT_SINGLE ,
+this should be set to the number of the inode for which the caller wants
+information.
+After the call, this value will be set to the number of the last inode for
+which information was supplied.
+This field will not be updated if
+.I ocount
+is NULL.
+.PP
+.I count
+is the number of elements in the
+.B ubuffer
+array and therefore the number of inodes for which to return stat information.
+This value must be set to 1 for
+.BR FSBULKSTAT_SINGLE .
+.PP
+.I ocount
+points to a value that will receive the number of records returned.
+If this value is NULL, then neither
+.I ocount
+nor
+.I lastip
+will be updated.
+.PP
+.I ubuffer
+points to a memory buffer into which inode stat information will be copied.
+This buffer must be an array of
+.B struct xfs_bstat
+which is described below.
+The array must have at least
+.I count
+elements.
+.PP
+.in +4n
+.nf
+struct xfs_bstat {
+ __u64 bs_ino;
+ __u16 bs_mode;
+ __u16 bs_nlink;
+ __u32 bs_uid;
+ __u32 bs_gid;
+ __u32 bs_rdev;
+ __s32 bs_blksize;
+ __s64 bs_size;
+ struct xfs_bstime bs_atime;
+ struct xfs_bstime bs_mtime;
+ struct xfs_bstime bs_ctime;
+ int64_t bs_blocks;
+ __u32 bs_xflags;
+ __s32 bs_extsize;
+ __s32 bs_extents;
+ __u32 bs_gen;
+ __u16 bs_projid_lo;
+ __u16 bs_forkoff;
+ __u16 bs_projid_hi;
+ unsigned char bs_pad[6];
+ __u32 bs_cowextsize;
+ __u32 bs_dmevmask;
+ __u16 bs_dmstate;
+ __u16 bs_aextents;
+};
+.fi
+.in
+.PP
+The structure members are as follows:
+.PP
+.I bs_ino
+is the inode number for this record.
+.PP
+.I bs_mode
+is the file type and mode.
+.PP
+.I bs_nlink
+is the number of hard links to this inode.
+.PP
+.I bs_uid
+is the user id.
+.PP
+.I bs_gid
+is the group id.
+.PP
+.I bs_rdev
+is the encoded device id if this is a special file.
+.PP
+.I bs_blksize
+is the size of a data block for this file, in units of bytes.
+.PP
+.I bs_size
+is the size of the file, in bytes.
+.PP
+.I bs_atime
+is the last time this file was accessed.
+.PP
+.I bs_mtime
+is the last time the contents of this file were modified.
+.PP
+.I bs_ctime
+is the last time this inode record was modified.
+.PP
+.I bs_blocks
+is the number of filesystem blocks allocated to this file, including metadata.
+.PP
+.I bs_xflags
+contains the extended flags that are set on this inode.
+These flags are the same values as those defined in the
+.B XFS INODE FLAGS
+section of the
+.BR ioctl_xfs_fsgetxattr (2)
+manpage.
+
+.PD 1
+.PP
+.I bs_extsize
+is the extent size hint for this file, in bytes.
+.PP
+.I bs_extents
+is the number of storage mappings associated with this file's data.
+.PP
+.I bs_gen
+is the generation number of the inode record.
+.PP
+.I bs_projid_lo
+is the lower 16-bits of the project id.
+.PP
+.I bs_forkoff
+is the offset of the attribute fork in the inode record, in bytes.
+.PP
+.I bs_projid_hi
+is the upper 16-bits of the project id.
+.PP
+.I bs_pad[6]
+is zeroed.
+.PP
+.I bs_cowextsize
+is the Copy on Write extent size hint for this file, in bytes.
+.PP
+.I bs_dmevmask
+is unused on Linux.
+.PP
+.I bs_dmstate
+is unused on Linux.
+.PP
+.I bs_aextents
+is the number of storage mappings associated with this file's extended
+attributes.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_xfs_fsgetxattr (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 1237eac6..94a6ad4b 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -399,92 +399,18 @@ An output
.B ocount
value of zero means that the inode table has been exhausted.
-.TP
-.B XFS_IOC_FSBULKSTAT
-This interface is used to extract inode information (stat
-information) "in bulk" from a filesystem. It is intended to
-be called iteratively, to obtain information about the entire
-set of inodes in a filesystem.
-The information is passed in and out via a structure of type
-.B xfs_fsop_bulkreq_t
-pointed to by the final argument.
-.B lastip
-is a pointer to a variable containing the last inode number returned,
-initially it should be zero.
-.B icount
-indicates the size of the array of structures specified by
-.B ubuffer.
-.B ubuffer
-is the address of an array of structures of type
-.BR xfs_bstat_t .
-Many of the elements in the structure are the same as for the stat
-structure.
-The structure has the following elements:
-.B bs_ino
-(inode number),
-.B bs_mode
-(type and mode),
-.B bs_nlink
-(number of links),
-.B bs_uid
-(user id),
-.B bs_gid
-(group id),
-.B bs_rdev
-(device value),
-.B bs_blksize
-(block size of the filesystem),
-.B bs_size
-(file size in bytes),
-.B bs_atime
-(access time),
-.B bs_mtime
-(modify time),
-.B bs_ctime
-(inode change time),
-.B bs_blocks
-(number of blocks used by the file),
-.B bs_xflags
-(extended flags),
-.B bs_extsize
-(extent size),
-.B bs_extents
-(number of extents),
-.B bs_gen
-(generation count),
-.B bs_projid_lo
-(project id - low word),
-.B bs_projid_hi
-(project id - high word, used when projid32bit feature is enabled),
-.B bs_dmevmask
-(DMIG event mask),
-.B bs_dmstate
-(DMIG state information), and
-.B bs_aextents
-(attribute extent count).
-.B ocount
-is a pointer to a count of returned values, filled in by the call.
-An output
-.B ocount
-value of zero means that the inode table has been exhausted.
-
-.TP
-.B XFS_IOC_FSBULKSTAT_SINGLE
-This interface is a variant of the
-.B XFS_IOC_FSBULKSTAT
-interface, used to obtain information about a single inode.
-for an open file in the filesystem of interest.
-The same structure is used to pass information in and out of
-the kernel, except no output count parameter is used (should
-be initialized to zero).
-An error is returned if the inode number is invalid.
-
.TP
.B XFS_IOC_FSGEOMETRY
See
.BR ioctl_xfs_fsop_geometry (2)
for more information.
+.TP
+.BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
+See
+.BR ioctl_xfs_fsbulkstat (2)
+for more information.
+
.PP
.nf
.B XFS_IOC_THAW
@@ -509,6 +435,7 @@ as they are not of general use to applications.
.SH SEE ALSO
.BR ioctl_xfs_fsgetxattr (2),
.BR ioctl_xfs_fsop_geometry (2),
+.BR ioctl_xfs_fsbulkstat (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (2 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 3/9] man: create a separate FSBULKSTAT " Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 16:23 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 5/9] man: create a separate INUMBERS ioctl manpage Darrick J. Wong
` (4 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Link to the scrub ioctl documentation from xfsctl.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man3/xfsctl.3 | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 94a6ad4b..78fad975 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -411,6 +411,12 @@ See
.BR ioctl_xfs_fsbulkstat (2)
for more information.
+.TP
+.B XFS_IOC_SCRUB_METADATA
+See
+.BR ioctl_xfs_scrub_metadata (2)
+for more information.
+
.PP
.nf
.B XFS_IOC_THAW
@@ -436,6 +442,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_fsgetxattr (2),
.BR ioctl_xfs_fsop_geometry (2),
.BR ioctl_xfs_fsbulkstat (2),
+.BR ioctl_xfs_scrub_metadata (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 5/9] man: create a separate INUMBERS ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (3 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3 Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 15:16 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 6/9] man: create a separate FSCOUNTS " Darrick J. Wong
` (3 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Create a separate manual page for the xfs INUMBERS ioctl so we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_fsinumbers.2 | 122 +++++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 34 +----------
2 files changed, 126 insertions(+), 30 deletions(-)
create mode 100644 man/man2/ioctl_xfs_fsinumbers.2
diff --git a/man/man2/ioctl_xfs_fsinumbers.2 b/man/man2/ioctl_xfs_fsinumbers.2
new file mode 100644
index 00000000..04f32109
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsinumbers.2
@@ -0,0 +1,122 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSINUMBERS 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_fsinumbers \- extract a list of valid inode numbers from an XFS filesystem
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *" arg );
+.SH DESCRIPTION
+Queries inode allocation information from an XFS filesystem.
+It is intended to be called iteratively to obtain the entire set of inodes.
+These ioctls use
+.B struct xfs_fsop_bulkreq
+to set up a bulk transfer with the kernel:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_bulkreq {
+ __u64 *lastip;
+ __s32 count;
+ void *ubuffer;
+ __s32 *ocount;
+};
+.fi
+.in
+.PP
+.I lastip
+points to a value that will receive the number of the "last inode".
+This should be set to one less than the number of the first inode for which the
+caller wants information, or zero to start with the first inode in the
+filesystem.
+After the call, this value will be set to the number of the last inode for
+which information is supplied.
+This field will not be updated if
+.I ocount
+is NULL.
+.PP
+.I count
+is the number of elements in the
+.B ubuffer
+array and therefore the number of inode groups for which to return allocation
+information.
+.PP
+.I ocount
+points to a value that will receive the number of records returned.
+An output value of zero means that there are no more inode groups left to
+enumerate.
+If this value is NULL, then neither
+.I ocount
+nor
+.I lastip
+will be updated.
+.PP
+.I ubuffer
+points to a memory buffer where inode group information will be copied.
+This buffer must be an array of
+.B struct xfs_inogrp
+which is described below.
+The array must have at least
+.I count
+elements.
+.PP
+.in +4n
+.nf
+struct xfs_inogrp {
+ __u64 xi_startino;
+ __s32 xi_alloccount;
+ __u64 xi_allocmask;
+}
+.fi
+.in
+.PP
+This structure describes inode usage information for a group of 64 consecutive
+inode numbers.
+The fields are as follows:
+.PP
+.I xi_startino
+is the first inode number of this group.
+.PP
+.I xi_alloccount
+is the number of bits that are set in
+.IR xi_allocmask .
+This is the number of inodes allocated in this group.
+.PP
+.I xi_allocmask
+is a bitmask of inodes that are allocated in this inode group.
+The bitmask is 64 bits long, and the least significant bit corresponds to inode
+.BR xi_startino .
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 78fad975..c14f7d33 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -368,36 +368,9 @@ can be any open file in the XFS filesystem in question.
.PP
.TP
.B XFS_IOC_FSINUMBERS
-This interface is used to extract a list of valid inode numbers from an
-XFS filesystem.
-It is intended to be called iteratively, to obtain the entire set of inodes.
-The information is passed in and out via a structure of type
-.B xfs_fsop_bulkreq_t
-pointed to by the final argument.
-.B lastip
-is a pointer to a variable containing the last inode number returned,
-initially it should be zero.
-.B icount
-is the size of the array of structures specified by
-.BR ubuffer .
-.B ubuffer
-is the address of an array of structures, of type
-.BR xfs_inogrp_t .
-This structure has the following elements:
-.B xi_startino
-(starting inode number),
-.B xi_alloccount
-(count of bits set in xi_allocmask), and
-.B xi_allocmask
-(mask of allocated inodes in this group).
-The bitmask is 64 bits long, and the least significant bit corresponds to inode
-.B xi_startino.
-Each bit is set if the corresponding inode is in use.
-.B ocount
-is a pointer to a count of returned values, filled in by the call.
-An output
-.B ocount
-value of zero means that the inode table has been exhausted.
+See
+.BR ioctl_xfs_fsinumbers (2)
+for more information.
.TP
.B XFS_IOC_FSGEOMETRY
@@ -443,6 +416,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_fsop_geometry (2),
.BR ioctl_xfs_fsbulkstat (2),
.BR ioctl_xfs_scrub_metadata (2),
+.BR ioctl_xfs_fsinumbers (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 6/9] man: create a separate FSCOUNTS ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (4 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 5/9] man: create a separate INUMBERS ioctl manpage Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 15:15 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 7/9] man: create a separate RESBLKS " Darrick J. Wong
` (2 subsequent siblings)
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Create a separate manual page for the xfs FSCOUNTS ioctl so we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_fscounts.2 | 69 +++++++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 14 +++++---
2 files changed, 77 insertions(+), 6 deletions(-)
create mode 100644 man/man2/ioctl_xfs_fscounts.2
diff --git a/man/man2/ioctl_xfs_fscounts.2 b/man/man2/ioctl_xfs_fscounts.2
new file mode 100644
index 00000000..eb7df89c
--- /dev/null
+++ b/man/man2/ioctl_xfs_fscounts.2
@@ -0,0 +1,69 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSCOUNTS 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_fscounts \- query XFS summary counter information
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *" arg );
+.SH DESCRIPTION
+Query the raw filesystem summary counters.
+Unlike
+.BR statvfs (3),
+the values returned here are the raw values, which do not reflect any
+alterations or limits set by project quotas.
+The counter information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_counts {
+ __u64 freedata;
+ __u64 freertx;
+ __u64 freeino;
+ __u64 allocino;
+};
+.fi
+.in
+.PP
+The fields of this structure are as follows:
+.PP
+.I freedata
+is the number of free filesystem blocks on the data device.
+.PP
+.I freertx
+is the number of free extents on the realtime device.
+.PP
+.I freeino
+is the number of inode records that are not in use within the space that has
+been allocated for them.
+.PP
+.I allocino
+is the number of inode records for which space has been allocated.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index c14f7d33..ee3188ec 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -390,6 +390,12 @@ See
.BR ioctl_xfs_scrub_metadata (2)
for more information.
+.TP
+.B XFS_IOC_FSCOUNTS
+See
+.BR ioctl_xfs_fscounts (2)
+for more information.
+
.PP
.nf
.B XFS_IOC_THAW
@@ -398,16 +404,11 @@ for more information.
.B XFS_IOC_SET_RESBLKS
.B XFS_IOC_FSGROWFSDATA
.B XFS_IOC_FSGROWFSLOG
-.B XFS_IOC_FSGROWFSRT
.fi
.TP
-.B XFS_IOC_FSCOUNTS
+.B XFS_IOC_FSGROWFSRT
These interfaces are used to implement various filesystem internal
operations on XFS filesystems.
-For
-.B XFS_FS_COUNTS
-(get filesystem dynamic global information), the output structure is of type
-.BR xfs_fsop_counts_t .
The remainder of these operations will not be described further
as they are not of general use to applications.
@@ -417,6 +418,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_fsbulkstat (2),
.BR ioctl_xfs_scrub_metadata (2),
.BR ioctl_xfs_fsinumbers (2),
+.BR ioctl_xfs_fscounts (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 7/9] man: create a separate RESBLKS ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (5 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 6/9] man: create a separate FSCOUNTS " Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 16:02 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP " Darrick J. Wong
2019-06-20 16:51 ` [PATCH 9/9] man: create a separate xfs shutdown " Darrick J. Wong
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Create a separate manual page for the xfs RESBLKS ioctls so we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_getresblks.2 | 65 +++++++++++++++++++++++++++++++++++++++
man/man2/ioctl_xfs_setresblks.2 | 1 +
man/man3/xfsctl.3 | 14 +++++++-
3 files changed, 78 insertions(+), 2 deletions(-)
create mode 100644 man/man2/ioctl_xfs_getresblks.2
create mode 100644 man/man2/ioctl_xfs_setresblks.2
diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
new file mode 100644
index 00000000..694b4496
--- /dev/null
+++ b/man/man2/ioctl_xfs_getresblks.2
@@ -0,0 +1,65 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GETRESBLKS 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_getresblks \- query XFS summary counter information
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
+.SH DESCRIPTION
+Query or set the free space reservation information.
+These blocks are reserved by the filesystem as a final attempt to prevent
+metadata update failures due to insufficient space.
+Only the system administrator can call these ioctls, because overriding the
+defaults is extremely dangerous and should never be tried by anyone.
+.PP
+The reservation information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_resblks {
+ __u64 resblks;
+ __u64 resblks_avail;
+};
+.fi
+.in
+.PP
+.I resblks
+is the number of blocks that the filesystem will try to maintain to prevent
+critical out of space situations.
+.PP
+.I resblks_avail
+is the number of reserved blocks remaining.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B EPERM
+Caller does not have permission to call this ioctl.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man2/ioctl_xfs_setresblks.2 b/man/man2/ioctl_xfs_setresblks.2
new file mode 100644
index 00000000..209bc0a8
--- /dev/null
+++ b/man/man2/ioctl_xfs_setresblks.2
@@ -0,0 +1 @@
+.so man2/ioctl_xfs_getresblks.2
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index ee3188ec..89975a3c 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -396,12 +396,21 @@ See
.BR ioctl_xfs_fscounts (2)
for more information.
+.TP
+.nf
+.B XFS_IOC_GET_RESBLKS
+.fi
+.TP
+.B XFS_IOC_SET_RESBLKS
+See
+.BR ioctl_xfs_getresblks (2)
+for more information.
+Save yourself a lot of frustration and avoid these ioctls.
+
.PP
.nf
.B XFS_IOC_THAW
.B XFS_IOC_FREEZE
-.B XFS_IOC_GET_RESBLKS
-.B XFS_IOC_SET_RESBLKS
.B XFS_IOC_FSGROWFSDATA
.B XFS_IOC_FSGROWFSLOG
.fi
@@ -419,6 +428,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_scrub_metadata (2),
.BR ioctl_xfs_fsinumbers (2),
.BR ioctl_xfs_fscounts (2),
+.BR ioctl_xfs_getresblks (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (6 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 7/9] man: create a separate RESBLKS " Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 15:53 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 9/9] man: create a separate xfs shutdown " Darrick J. Wong
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Create a separate manual page for the xfs BMAP ioctls so we can document
how they work.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_getbmap.2 | 1
man/man2/ioctl_xfs_getbmapa.2 | 1
man/man2/ioctl_xfs_getbmapx.2 | 172 +++++++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 61 ++-------------
4 files changed, 184 insertions(+), 51 deletions(-)
create mode 100644 man/man2/ioctl_xfs_getbmap.2
create mode 100644 man/man2/ioctl_xfs_getbmapa.2
create mode 100644 man/man2/ioctl_xfs_getbmapx.2
diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
new file mode 100644
index 00000000..909402fc
--- /dev/null
+++ b/man/man2/ioctl_xfs_getbmap.2
@@ -0,0 +1 @@
+.so man2/ioctl_xfs_getbmapx.2
diff --git a/man/man2/ioctl_xfs_getbmapa.2 b/man/man2/ioctl_xfs_getbmapa.2
new file mode 100644
index 00000000..909402fc
--- /dev/null
+++ b/man/man2/ioctl_xfs_getbmapa.2
@@ -0,0 +1 @@
+.so man2/ioctl_xfs_getbmapx.2
diff --git a/man/man2/ioctl_xfs_getbmapx.2 b/man/man2/ioctl_xfs_getbmapx.2
new file mode 100644
index 00000000..cf21ca32
--- /dev/null
+++ b/man/man2/ioctl_xfs_getbmapx.2
@@ -0,0 +1,172 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GETBMAPX 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_getbmapx \- query extent information for an open file
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
+.br
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
+.SH DESCRIPTION
+Get the block map for a segment of a file in an XFS file system.
+The mapping information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct getbmap {
+ __s64 bmv_offset;
+ __s64 bmv_block;
+ __s64 bmv_length;
+ __s32 bmv_count;
+ __s32 bmv_entries;
+};
+.fi
+.in
+.PP
+The
+.B XFS_IOC_GETBMAPX
+ioctl uses a larger version of that structure:
+.PP
+.in +4n
+.nf
+struct getbmapx {
+ __s64 bmv_offset;
+ __s64 bmv_block;
+ __s64 bmv_length;
+ __s32 bmv_count;
+ __s32 bmv_entries;
+ __s32 bmv_iflags;
+ __s32 bmv_oflags;
+ __s32 bmv_unused1;
+ __s32 bmv_unused2;
+};
+.fi
+.in
+.PP
+All sizes and offsets in the structure are in units of 512 bytes.
+.PP
+The first structure in the array is a header and the remaining structures in
+the array contain block map information on return.
+The header controls iterative calls to the command and should be filled out as
+follows:
+.TP
+.I bmv_offset
+The file offset of the area of interest in the file.
+.TP
+.I bmv_length
+The length of the area of interest in the file.
+If this value is set to -1, the length of the interesting area is the rest of
+the file.
+.TP
+.I bmv_count
+The length of the array, including this header.
+.TP
+.I bmv_entries
+The number of entries actually filled in by the call.
+This does not need to be filled out before the call.
+.TP
+.I bmv_iflags
+For the
+.B XFS_IOC_GETBMAPX
+function, this is a bitmask containing a combination of the following flags:
+.RS 0.4i
+.TP
+.B BMV_IF_ATTRFORK
+Return information about the extended attribute fork.
+.TP
+.B BMV_IF_PREALLOC
+Return information about unwritten pre-allocated segments.
+.TP
+.B BMV_IF_DELALLOC
+Return information about delayed allocation reservation segments.
+.TP
+.B BMV_IF_NO_HOLES
+Do not return information about holes.
+.RE
+.PD 1
+.PP
+The other
+.I bmv_*
+fields in the header are ignored.
+.PP
+On return from a call, the header is updated so that the command can be
+reused to obtain more information without re-initializing the structures.
+The remainder of the array will be filled out by the call as follows:
+
+.TP
+.I bmv_offset
+File offset of segment.
+.TP
+.I bmv_block
+Physical starting block of segment.
+If this is -1, then the segment is a hole.
+.TP
+.I bmv_length
+Length of segment.
+.TP
+.I bmv_oflags
+The
+.B XFS_IOC_GETBMAPX
+function will fill this field with a combination of the following flags:
+.RS 0.4i
+.TP
+.B BMV_OF_PREALLOC
+The segment is an unwritten pre-allocation.
+.TP
+.B BMV_OF_DELALLOC
+The segment is a delayed allocation reservation.
+.TP
+.B BMV_OF_LAST
+This segment is the last in the file.
+.TP
+.B BMV_OF_SHARED
+This segment shares blocks with other files.
+.RE
+.PD 1
+.PP
+The other
+.I bmv_*
+fields are ignored in the array of outputted records.
+.PP
+The
+.B XFS_IOC_GETBMAPA
+command is identical to
+.B XFS_IOC_GETBMAP
+except that information about the attribute fork of the file is returned.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 89975a3c..077dd411 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -144,59 +144,17 @@ See
.BR ioctl_xfs_fsgetxattr (2)
for more information.
-.TP
-.B XFS_IOC_GETBMAP
-Get the block map for a segment of a file in an XFS file system.
-The final argument points to an arry of variables of type
-.BR "struct getbmap" .
-All sizes and offsets in the structure are in units of 512 bytes.
-The structure fields include:
-.B bmv_offset
-(file offset of segment),
-.B bmv_block
-(starting block of segment),
-.B bmv_length
-(length of segment),
-.B bmv_count
-(number of array entries, including the first), and
-.B bmv_entries
-(number of entries filled in).
-The first structure in the array is a header, and the remaining
-structures in the array contain block map information on return.
-The header controls iterative calls to the
+.PP
+.nf
.B XFS_IOC_GETBMAP
-command.
-The caller fills in the
-.B bmv_offset
-and
-.B bmv_length
-fields of the header to indicate the area of interest in the file,
-and fills in the
-.B bmv_count
-field to indicate the length of the array.
-If the
-.B bmv_length
-value is set to \-1 then the length of the interesting area is the rest
-of the file.
-On return from a call, the header is updated so that the command can be
-reused to obtain more information, without re-initializing the structures.
-Also on return, the
-.B bmv_entries
-field of the header is set to the number of array entries actually filled in.
-The non-header structures will be filled in with
-.BR bmv_offset ,
-.BR bmv_block ,
-and
-.BR bmv_length .
-If a region of the file has no blocks (is a hole in the file) then the
-.B bmv_block
-field is set to \-1.
-
-.TP
.B XFS_IOC_GETBMAPA
-Identical to
-.B XFS_IOC_GETBMAP
-except that information about the attribute fork of the file is returned.
+.fi
+.PD 0
+.TP
+.B XFS_IOC_GETBMAPX
+See
+.BR ioctl_getbmap (2)
+for more information.
.PP
.B XFS_IOC_RESVSP
@@ -429,6 +387,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_fsinumbers (2),
.BR ioctl_xfs_fscounts (2),
.BR ioctl_xfs_getresblks (2),
+.BR ioctl_xfs_getbmap (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 9/9] man: create a separate xfs shutdown ioctl manpage
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
` (7 preceding siblings ...)
2019-06-20 16:51 ` [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP " Darrick J. Wong
@ 2019-06-20 16:51 ` Darrick J. Wong
2019-07-05 16:08 ` Eric Sandeen
8 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-06-20 16:51 UTC (permalink / raw)
To: sandeen, darrick.wong; +Cc: linux-xfs
From: Darrick J. Wong <darrick.wong@oracle.com>
Create a separate manual page for the xfs shutdown ioctl so we can
document how it works.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
man/man2/ioctl_xfs_goingdown.2 | 63 ++++++++++++++++++++++++++++++++++++++++
man/man3/xfsctl.3 | 7 ++++
2 files changed, 70 insertions(+)
create mode 100644 man/man2/ioctl_xfs_goingdown.2
diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
new file mode 100644
index 00000000..bedc85c8
--- /dev/null
+++ b/man/man2/ioctl_xfs_goingdown.2
@@ -0,0 +1,63 @@
+.\" Copyright (c) 2019, Oracle. All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GOINGDOWN 2 2019-06-17 "XFS"
+.SH NAME
+ioctl_xfs_goingdown \- shut down an XFS filesystem
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
+.SH DESCRIPTION
+Shuts down a live XFS filesystem.
+This is a software initiated hard shutdown and should be avoided whenever
+possible.
+After this call completes, the filesystem will be totally unusable and must be
+unmounted.
+
+.PP
+.I flags
+can be one of the following:
+.RS 0.4i
+.TP
+.B XFS_FSOP_GOING_FLAGS_DEFAULT
+Flush all dirty data and in-core state to disk, flush pending transactions to
+the log, and shut down.
+.TP
+.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
+Flush all pending transactions to the log and shut down, leaving all dirty
+data unwritten.
+.TP
+.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
+Shut down immediately, without writing pending transactions or dirty data
+to disk.
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B EPERM
+Caller did not have permission to shut down the filesystem.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 077dd411..7e6588b8 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -365,6 +365,12 @@ See
for more information.
Save yourself a lot of frustration and avoid these ioctls.
+.TP
+.B XFS_IOC_GOINGDOWN
+See
+.BR ioctl_xfs_goingdown (2)
+for more information.
+
.PP
.nf
.B XFS_IOC_THAW
@@ -388,6 +394,7 @@ as they are not of general use to applications.
.BR ioctl_xfs_fscounts (2),
.BR ioctl_xfs_getresblks (2),
.BR ioctl_xfs_getbmap (2),
+.BR ioctl_xfs_goingdown (2),
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage
2019-06-20 16:50 ` [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage Darrick J. Wong
@ 2019-07-03 22:48 ` Eric Sandeen
2019-07-04 2:04 ` Darrick J. Wong
0 siblings, 1 reply; 26+ messages in thread
From: Eric Sandeen @ 2019-07-03 22:48 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:50 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Break out the xfs file attribute get and set ioctls into a separate
> manpage to reduce clutter in xfsctl.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
> man/man2/ioctl_xfs_fsgetxattr.2 | 245 ++++++++++++++++++++++++++++++++++++++
> man/man2/ioctl_xfs_fsgetxattra.2 | 1
> man/man2/ioctl_xfs_fssetxattr.2 | 1
> man/man3/xfsctl.3 | 159 +------------------------
> 4 files changed, 255 insertions(+), 151 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
> create mode 100644 man/man2/ioctl_xfs_fsgetxattra.2
> create mode 100644 man/man2/ioctl_xfs_fssetxattr.2
>
Ok I started nitpicking again but realized that lots of this is inherited;
perhaps we should have just done a 100% pure move, followed by an improvement
patch. So anything bothersome that was just inherited here I'll...
try to ignore, and focus on stuff that is new and unclear or incorrect.
If I get acks for the suggestions below I'll just do it on the way in.
> diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> new file mode 100644
> index 00000000..7462c46c
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> @@ -0,0 +1,245 @@
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSGETXATTR 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_fsgetxattr \- query information for an open file
> +.SH SYNOPSIS
> +.br
> +.B #include <linux/fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
> +.SH DESCRIPTION
> +Query or set additional attributes associated with files in various file
> +systems.
> +The attributes are conveyed in a structure of the form:
> +.PP
> +.in +4n
> +.nf
> +struct fsxattr {
> + __u32 fsx_xflags;
> + __u32 fsx_extsize;
> + __u32 fsx_nextents;
> + __u32 fsx_projid;
> + __u32 fsx_cowextsize;
> + unsigned char fsx_pad[8];
> +};
> +.fi
> +.in
> +.PP
> +.I fsx_xflags
> +are extended flags that apply to this file.
> +Refer to the section
> +.B XFS INODE FLAGS
> +below for more information.
> +
> +.PP
> +.I fsx_extsize
> +is the preferred extent allocation size for data blocks mapped to this file,
> +in units of filesystem blocks.
> +If this value is zero, the filesystem will choose a default option, which
> +is currently zero.
> +If
> +.B XFS_IOC_FSSETXATTR
> +is called with
> +.B XFS_XFLAG_EXTSIZE
> +set in
> +.I fsx_xflags
> +and this field is zero, the XFLAG will be cleared instead.
"instead" implies that the value is ignored, I think, so:
"and this field set to zero, the XFLAG will also be cleared."
> +.PP
> +.I fsx_nextents
> +is the number of data extents in this file.
> +If
> +.B XFS_IOC_FSGETXATTRA
> +was used, then this is the number of extended attribute extents in the file.
> +.PP
> +.I fsx_projid
> +is the project ID of this file.
> +.PP
> +.I fsx_cowextsize
> +is the preferred extent allocation size for copy on write operations
> +targeting this file, in units of filesystem blocks.
> +If this field is zero, the filesystem will choose a default option,
> +which is currently 128 filesystem blocks.
> +If
> +.B XFS_IOC_FSSETXATTR
> +is called with
> +.B XFS_XFLAG_COWEXTSIZE
> +set in
> +.I fsx_xflags
> +and this field is zero, the XFLAG will be cleared instead.
"and this field set to zero, the XFLAG will also be cleared."
> +
> +.PP
> +.I fsx_pad
> +must be zeroed.
> +
> +.SH XFS INODE FLAGS
> +This field can be a combination of the following:
> +
> +.TP
> +.B XFS_XFLAG_REALTIME
> +The file is a realtime file.
> +This bit can only be changed when the file is empty.
> +.TP
> +.B XFS_XFLAG_PREALLOC
> +The file has preallocated space.
> +.TP
> +.B 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.
> +If this flag is set before a
> +.B XFS_IOC_FSSETXATTR
> +call and would not be cleared by the call, then no other attributes can be
> +changed and
> +.B EPERM
> +will be returned.
> +.TP
> +.B XFS_XFLAG_APPEND
> +The file is append-only - it can only be open in append mode for
opened?
> +writing.
> +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> +capability can set or clear this flag.
> +.TP
> +.B XFS_XFLAG_SYNC
> +All writes to the file are synchronous.
> +If set on a directory and the
> +.B /proc/sys/fs/xfs/inherit_sync
> +knob is set, new files and subdirectories created in the directory
Ok ignoring the colloquial knob for now ;)
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_NOATIME
> +When the file is accessed, its atime record is not modified.
> +If set on a directory and the
> +.B /proc/sys/fs/xfs/inherit_noatime
> +knob is set, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_NODUMP
> +The file should be skipped by backup utilities.
> +If set on a directory and the
> +.B /proc/sys/fs/xfs/inherit_nodump
> +knob is set, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_RTINHERIT
> +Realtime inheritance bit - new files created in the directory
> +will be automatically as realtime times.
"will be automatically created as realtime files."
> +If set on a directory, new subdirectories created in the directory will also
> +have the inheritance flag set.
(I almost wonder if we should just group the inheritable flags together
and mention it once. "For the following flags, if the flag is set on
a directory ...") ((I'll worry about that later))
> +.TP
> +.B XFS_XFLAG_PROJINHERIT
> +Project inheritance bit - new files and directories created in
> +this directory will inherit the project ID of this directory.
> +If set on a directory, new subdirectories created in the directory will also
> +have the inheritance flag set.> +.TP
> +.B XFS_XFLAG_NOSYMLINKS
> +Disallows creation of symbolic links in the directory.
> +This flag can only be set on a directory.
> +If set on a directory and the
> +.B /proc/sys/fs/xfs/inherit_nosymlinks
> +knob is set, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_EXTSIZE
> +Extent size bit - if a basic extent size value is set on the file
> +then the allocator will allocate in multiples of the set size for
> +this file (see
> +.B fsx_extsize
> +below).
> +This flag can only be set on a file if it is empty.
I feel like "set" is ambiguous, it can mean "toggled from unset to set"
or "is currently set" - if interpreted on the latter, it sounds like a
GET operation should never see the flag unless it is empty. so:
"This flag can only be initially set on a file when it is empty" ?
> +.TP
> +.B XFS_XFLAG_EXTSZINHERIT
> +Extent size inheritance bit - new files and directories created in
> +the directory will inherit the extent size value (see
> +.B fsx_extsize
> +below) of the parent directory.
> +New subdirectories created in the directory will inherit the extent size
> +inheritance bit.
> +.TP
> +.B XFS_XFLAG_NODEFRAG
> +No defragment file bit - the file should be skipped during a defragmentation
> +operation.
> +If set on a directory and the
> +.B /proc/sys/fs/xfs/inherit_nodefrag
> +knob is set, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_FILESTREAM
> +Filestream allocator bit - 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.
> +If set on a directory, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B 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 cannot be reflinked and have the
> +.BR XFS_XFLAG_DAX
> +set at the same time.
> +That is to say that DAX files cannot share blocks.
Should we just say that this flag cannot be set on filesystems with the
reflink feature enabled?
> +If set on a directory, new files and subdirectories created in the directory
> +will also have the flag set.
> +.TP
> +.B XFS_XFLAG_COWEXTSIZE
> +Copy on Write Extent size bit - 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
> +.B fsx_cowextsize
> +below).
> +If set on a directory, new files and subdirectories created in the directory
> +will have both the flag and the CoW extent size value set.
> +.TP
> +.B XFS_XFLAG_HASATTR
> +The file has extended attributes associated with it.
> +
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EACCESS
> +Caller does not have sufficient access to change the attributes.
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.TP
> +.B EPERM
> +Caller did not have permission to change the attributes.
> +.SH CONFORMING TO
> +This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> +Linux kernel.
> +Not all fields may be understood by filesystems other than xfs.
> +.SH SEE ALSO
> +.BR ioctl (2),
> +.BR ioctl_iflags (2)
> diff --git a/man/man2/ioctl_xfs_fsgetxattra.2 b/man/man2/ioctl_xfs_fsgetxattra.2
> new file mode 100644
> index 00000000..9bd595ae
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsgetxattra.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_xfs_fsgetxattr.2
> diff --git a/man/man2/ioctl_xfs_fssetxattr.2 b/man/man2/ioctl_xfs_fssetxattr.2
> new file mode 100644
> index 00000000..9bd595ae
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fssetxattr.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_xfs_fsgetxattr.2
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 462ccbd8..2992b5be 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -132,161 +132,17 @@ will fail with EINVAL.
> All I/O requests are kept consistent with any data brought into
> the cache with an access through a non-direct I/O file descriptor.
>
> -.TP
> -.B XFS_IOC_FSGETXATTR
> -Get additional attributes associated with files in XFS file systems.
> -The final argument points to a variable of type
> -.BR "struct fsxattr" ,
> -whose fields include:
> -.B fsx_xflags
> -(extended flag bits),
> -.B fsx_extsize
> -(nominal extent size in file system blocks),
> -.B fsx_nextents
> -(number of data extents in the file).
> -A
> -.B fsx_extsize
> -value returned indicates that a preferred extent size was previously
> -set on the file, a
> -.B fsx_extsize
> -of zero indicates that the defaults for that filesystem will be used.
> -A
> -.B fsx_cowextsize
> -value returned indicates that a preferred copy on write extent size was
> -previously set on the file, whereas a
> -.B fsx_cowextsize
> -of zero indicates that the defaults for that filesystem will be used.
> -The current default for
> -.B fsx_cowextsize
> -is 128 blocks.
> -Currently the meaningful bits for the
> -.B fsx_xflags
> -field are:
> -.PD 0
> -.RS
> -.TP 1.0i
> -.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
> -The file is a realtime file.
> -.TP
> -.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
> -The file has preallocated space.
> -.TP
> -.SM "Bit 3 (0x8) \- 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 "Bit 4 (0x10) \- 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 "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
> -All writes to the file are synchronous.
> -.TP
> -.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
> -When the file is accessed, its atime record is not modified.
> -.TP
> -.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
> -The file should be skipped by backup utilities.
> -.TP
> -.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
> -Realtime inheritance bit - new files created in the directory
> -will be automatically realtime, and new directories created in
> -the directory will inherit the inheritance bit.
> -.TP
> -.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
> -Project inheritance bit - new files and directories created in
> -the directory will inherit the parents project ID. New
> -directories also inherit the project inheritance bit.
> -.TP
> -.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
> -Can only be set on a directory and disallows creation of
> -symbolic links in that directory.
> -.TP
> -.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
> -Extent size bit - if a basic extent size value is set on the file
> -then the allocator will allocate in multiples of the set size for
> -this file (see
> -.B XFS_IOC_FSSETXATTR
> -below).
> -.TP
> -.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
> -Extent size inheritance bit - new files and directories created in
> -the directory will inherit the parents basic extent size value (see
> -.B XFS_IOC_FSSETXATTR
> -below).
> -Can only be set on a directory.
> -.TP
> -.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
> -No defragment file bit - the file should be skipped during a defragmentation
> -operation. When applied to a directory, new files and directories created will
> -inherit the no\-defrag bit.
> -.TP
> -.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
> -Filestream allocator bit - 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 "Bit 15 (0x8000) \- 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 cannot be reflinked and have the
> -.BR XFS_XFLAG_DAX
> -set at the same time.
> -That is to say that DAX files cannot share blocks.
> -.TP
> -.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
> -Copy on Write Extent size bit - 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
> -.B XFS_IOC_FSSETXATTR
> -below).
> -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 "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
> -The file has extended attributes associated with it.
> -.RE
> .PP
> -.PD
> -
> -.TP
> -.B XFS_IOC_FSGETXATTRA
> -Identical to
> +.nf
> .B XFS_IOC_FSGETXATTR
> -except that the
> -.B fsx_nextents
> -field contains the number of attribute extents in the file.
> -
> +.B XFS_IOC_FSGETXATTRA
> +.fi
> +.PD 0
> .TP
> .B XFS_IOC_FSSETXATTR
> -Set additional attributes associated with files in XFS file systems.
> -The final argument points to a variable of type
> -.BR "struct fsxattr" ,
> -but only the following fields are used in this call:
> -.BR fsx_xflags ,
> -.BR fsx_extsize ,
> -.BR fsx_cowextsize ,
> -and
> -.BR fsx_projid .
> -The
> -.B fsx_xflags
> -realtime file bit and the file's extent size may be changed only
> -when the file is empty, except in the case of a directory where
> -the extent size can be set at any time (this value is only used
> -for regular file allocations, so should only be set on a directory
> -in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
> -The copy on write extent size,
> -.BR fsx_cowextsize ,
> -can be set at any time.
> +See
> +.BR ioctl_xfs_fsgetxattr (2)
> +for more information.
>
> .TP
> .B XFS_IOC_GETBMAP
> @@ -649,6 +505,7 @@ The remainder of these operations will not be described further
> as they are not of general use to applications.
>
> .SH SEE ALSO
> +.BR ioctl_xfs_fsgetxattr (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage
2019-07-03 22:48 ` Eric Sandeen
@ 2019-07-04 2:04 ` Darrick J. Wong
2019-07-04 3:43 ` Eric Sandeen
0 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-07-04 2:04 UTC (permalink / raw)
To: Eric Sandeen; +Cc: linux-xfs
On Wed, Jul 03, 2019 at 05:48:15PM -0500, Eric Sandeen wrote:
> On 6/20/19 11:50 AM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> >
> > Break out the xfs file attribute get and set ioctls into a separate
> > manpage to reduce clutter in xfsctl.
> >
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> > man/man2/ioctl_xfs_fsgetxattr.2 | 245 ++++++++++++++++++++++++++++++++++++++
> > man/man2/ioctl_xfs_fsgetxattra.2 | 1
> > man/man2/ioctl_xfs_fssetxattr.2 | 1
> > man/man3/xfsctl.3 | 159 +------------------------
> > 4 files changed, 255 insertions(+), 151 deletions(-)
> > create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
> > create mode 100644 man/man2/ioctl_xfs_fsgetxattra.2
> > create mode 100644 man/man2/ioctl_xfs_fssetxattr.2
> >
>
> Ok I started nitpicking again but realized that lots of this is inherited;
> perhaps we should have just done a 100% pure move, followed by an improvement
> patch. So anything bothersome that was just inherited here I'll...
> try to ignore, and focus on stuff that is new and unclear or incorrect.
>
> If I get acks for the suggestions below I'll just do it on the way in.
Ok.
> > diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> > new file mode 100644
> > index 00000000..7462c46c
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> > @@ -0,0 +1,245 @@
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSGETXATTR 2 2019-06-17 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsgetxattr \- query information for an open file
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <linux/fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
> > +.SH DESCRIPTION
> > +Query or set additional attributes associated with files in various file
> > +systems.
> > +The attributes are conveyed in a structure of the form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct fsxattr {
> > + __u32 fsx_xflags;
> > + __u32 fsx_extsize;
> > + __u32 fsx_nextents;
> > + __u32 fsx_projid;
> > + __u32 fsx_cowextsize;
> > + unsigned char fsx_pad[8];
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I fsx_xflags
> > +are extended flags that apply to this file.
> > +Refer to the section
> > +.B XFS INODE FLAGS
> > +below for more information.
> > +
> > +.PP
> > +.I fsx_extsize
> > +is the preferred extent allocation size for data blocks mapped to this file,
> > +in units of filesystem blocks.
> > +If this value is zero, the filesystem will choose a default option, which
> > +is currently zero.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B XFS_XFLAG_EXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
>
> "instead" implies that the value is ignored, I think, so:
>
> "and this field set to zero, the XFLAG will also be cleared."
LGTM
> > +.PP
> > +.I fsx_nextents
> > +is the number of data extents in this file.
> > +If
> > +.B XFS_IOC_FSGETXATTRA
> > +was used, then this is the number of extended attribute extents in the file.
> > +.PP
> > +.I fsx_projid
> > +is the project ID of this file.
> > +.PP
> > +.I fsx_cowextsize
> > +is the preferred extent allocation size for copy on write operations
> > +targeting this file, in units of filesystem blocks.
> > +If this field is zero, the filesystem will choose a default option,
> > +which is currently 128 filesystem blocks.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B XFS_XFLAG_COWEXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
>
> "and this field set to zero, the XFLAG will also be cleared."
LGTM
> > +
> > +.PP
> > +.I fsx_pad
> > +must be zeroed.
> > +
> > +.SH XFS INODE FLAGS
> > +This field can be a combination of the following:
> > +
> > +.TP
> > +.B XFS_XFLAG_REALTIME
> > +The file is a realtime file.
> > +This bit can only be changed when the file is empty.
> > +.TP
> > +.B XFS_XFLAG_PREALLOC
> > +The file has preallocated space.
>
> > +.TP
> > +.B 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.
> > +If this flag is set before a
> > +.B XFS_IOC_FSSETXATTR
> > +call and would not be cleared by the call, then no other attributes can be
> > +changed and
> > +.B EPERM
> > +will be returned.
> > +.TP
> > +.B XFS_XFLAG_APPEND
> > +The file is append-only - it can only be open in append mode for
>
> opened?
Yes.
> > +writing.
> > +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > +capability can set or clear this flag.
> > +.TP
> > +.B XFS_XFLAG_SYNC
> > +All writes to the file are synchronous.
> > +If set on a directory and the
> > +.B /proc/sys/fs/xfs/inherit_sync
> > +knob is set, new files and subdirectories created in the directory
>
> Ok ignoring the colloquial knob for now ;)
What's the colloquialism? "subdirectory"?
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_NOATIME
> > +When the file is accessed, its atime record is not modified.
> > +If set on a directory and the
> > +.B /proc/sys/fs/xfs/inherit_noatime
> > +knob is set, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_NODUMP
> > +The file should be skipped by backup utilities.
> > +If set on a directory and the
> > +.B /proc/sys/fs/xfs/inherit_nodump
> > +knob is set, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_RTINHERIT
> > +Realtime inheritance bit - new files created in the directory
> > +will be automatically as realtime times.
>
> "will be automatically created as realtime files."
Ok.
> > +If set on a directory, new subdirectories created in the directory will also
> > +have the inheritance flag set.
> (I almost wonder if we should just group the inheritable flags together
> and mention it once. "For the following flags, if the flag is set on
> a directory ...") ((I'll worry about that later))
Yeah, that would be a nice cleanup.
> > +.TP
> > +.B XFS_XFLAG_PROJINHERIT
> > +Project inheritance bit - new files and directories created in
> > +this directory will inherit the project ID of this directory.
> > +If set on a directory, new subdirectories created in the directory will also
> > +have the inheritance flag set.> +.TP
> > +.B XFS_XFLAG_NOSYMLINKS
> > +Disallows creation of symbolic links in the directory.
> > +This flag can only be set on a directory.
> > +If set on a directory and the
> > +.B /proc/sys/fs/xfs/inherit_nosymlinks
> > +knob is set, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_EXTSIZE
> > +Extent size bit - if a basic extent size value is set on the file
> > +then the allocator will allocate in multiples of the set size for
> > +this file (see
> > +.B fsx_extsize
> > +below).
> > +This flag can only be set on a file if it is empty.
>
> I feel like "set" is ambiguous, it can mean "toggled from unset to set"
> or "is currently set" - if interpreted on the latter, it sounds like a
> GET operation should never see the flag unless it is empty. so:
>
> "This flag can only be initially set on a file when it is empty" ?
AFAICT it can be set if the file is truncated back to empty.
"This flag can only be enabled on a file when it is empty"?
> > +.TP
> > +.B XFS_XFLAG_EXTSZINHERIT
> > +Extent size inheritance bit - new files and directories created in
> > +the directory will inherit the extent size value (see
> > +.B fsx_extsize
> > +below) of the parent directory.
> > +New subdirectories created in the directory will inherit the extent size
> > +inheritance bit.
> > +.TP
> > +.B XFS_XFLAG_NODEFRAG
> > +No defragment file bit - the file should be skipped during a defragmentation
> > +operation.
> > +If set on a directory and the
> > +.B /proc/sys/fs/xfs/inherit_nodefrag
> > +knob is set, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_FILESTREAM
> > +Filestream allocator bit - 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.
> > +If set on a directory, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B 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 cannot be reflinked and have the
> > +.BR XFS_XFLAG_DAX
> > +set at the same time.
> > +That is to say that DAX files cannot share blocks.
>
> Should we just say that this flag cannot be set on filesystems with the
> reflink feature enabled?
Yes.
Thanks for picking this up, sorry I was sloppy. :( :(
Happy Independence Day!~!
--D
> > +If set on a directory, new files and subdirectories created in the directory
> > +will also have the flag set.
> > +.TP
> > +.B XFS_XFLAG_COWEXTSIZE
> > +Copy on Write Extent size bit - 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
> > +.B fsx_cowextsize
> > +below).
> > +If set on a directory, new files and subdirectories created in the directory
> > +will have both the flag and the CoW extent size value set.
> > +.TP
> > +.B XFS_XFLAG_HASATTR
> > +The file has extended attributes associated with it.
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EACCESS
> > +Caller does not have sufficient access to change the attributes.
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.TP
> > +.B EPERM
> > +Caller did not have permission to change the attributes.
> > +.SH CONFORMING TO
> > +This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> > +Linux kernel.
> > +Not all fields may be understood by filesystems other than xfs.
> > +.SH SEE ALSO
> > +.BR ioctl (2),
> > +.BR ioctl_iflags (2)
> > diff --git a/man/man2/ioctl_xfs_fsgetxattra.2 b/man/man2/ioctl_xfs_fsgetxattra.2
> > new file mode 100644
> > index 00000000..9bd595ae
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsgetxattra.2
> > @@ -0,0 +1 @@
> > +.so man2/ioctl_xfs_fsgetxattr.2
> > diff --git a/man/man2/ioctl_xfs_fssetxattr.2 b/man/man2/ioctl_xfs_fssetxattr.2
> > new file mode 100644
> > index 00000000..9bd595ae
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fssetxattr.2
> > @@ -0,0 +1 @@
> > +.so man2/ioctl_xfs_fsgetxattr.2
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 462ccbd8..2992b5be 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -132,161 +132,17 @@ will fail with EINVAL.
> > All I/O requests are kept consistent with any data brought into
> > the cache with an access through a non-direct I/O file descriptor.
> >
> > -.TP
> > -.B XFS_IOC_FSGETXATTR
> > -Get additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -whose fields include:
> > -.B fsx_xflags
> > -(extended flag bits),
> > -.B fsx_extsize
> > -(nominal extent size in file system blocks),
> > -.B fsx_nextents
> > -(number of data extents in the file).
> > -A
> > -.B fsx_extsize
> > -value returned indicates that a preferred extent size was previously
> > -set on the file, a
> > -.B fsx_extsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -A
> > -.B fsx_cowextsize
> > -value returned indicates that a preferred copy on write extent size was
> > -previously set on the file, whereas a
> > -.B fsx_cowextsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -The current default for
> > -.B fsx_cowextsize
> > -is 128 blocks.
> > -Currently the meaningful bits for the
> > -.B fsx_xflags
> > -field are:
> > -.PD 0
> > -.RS
> > -.TP 1.0i
> > -.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
> > -The file is a realtime file.
> > -.TP
> > -.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
> > -The file has preallocated space.
> > -.TP
> > -.SM "Bit 3 (0x8) \- 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 "Bit 4 (0x10) \- 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 "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
> > -All writes to the file are synchronous.
> > -.TP
> > -.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
> > -When the file is accessed, its atime record is not modified.
> > -.TP
> > -.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
> > -The file should be skipped by backup utilities.
> > -.TP
> > -.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
> > -Realtime inheritance bit - new files created in the directory
> > -will be automatically realtime, and new directories created in
> > -the directory will inherit the inheritance bit.
> > -.TP
> > -.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
> > -Project inheritance bit - new files and directories created in
> > -the directory will inherit the parents project ID. New
> > -directories also inherit the project inheritance bit.
> > -.TP
> > -.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
> > -Can only be set on a directory and disallows creation of
> > -symbolic links in that directory.
> > -.TP
> > -.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
> > -Extent size bit - if a basic extent size value is set on the file
> > -then the allocator will allocate in multiples of the set size for
> > -this file (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -.TP
> > -.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
> > -Extent size inheritance bit - new files and directories created in
> > -the directory will inherit the parents basic extent size value (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -Can only be set on a directory.
> > -.TP
> > -.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
> > -No defragment file bit - the file should be skipped during a defragmentation
> > -operation. When applied to a directory, new files and directories created will
> > -inherit the no\-defrag bit.
> > -.TP
> > -.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
> > -Filestream allocator bit - 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 "Bit 15 (0x8000) \- 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 cannot be reflinked and have the
> > -.BR XFS_XFLAG_DAX
> > -set at the same time.
> > -That is to say that DAX files cannot share blocks.
> > -.TP
> > -.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
> > -Copy on Write Extent size bit - 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
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -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 "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
> > -The file has extended attributes associated with it.
> > -.RE
> > .PP
> > -.PD
> > -
> > -.TP
> > -.B XFS_IOC_FSGETXATTRA
> > -Identical to
> > +.nf
> > .B XFS_IOC_FSGETXATTR
> > -except that the
> > -.B fsx_nextents
> > -field contains the number of attribute extents in the file.
> > -
> > +.B XFS_IOC_FSGETXATTRA
> > +.fi
> > +.PD 0
> > .TP
> > .B XFS_IOC_FSSETXATTR
> > -Set additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -but only the following fields are used in this call:
> > -.BR fsx_xflags ,
> > -.BR fsx_extsize ,
> > -.BR fsx_cowextsize ,
> > -and
> > -.BR fsx_projid .
> > -The
> > -.B fsx_xflags
> > -realtime file bit and the file's extent size may be changed only
> > -when the file is empty, except in the case of a directory where
> > -the extent size can be set at any time (this value is only used
> > -for regular file allocations, so should only be set on a directory
> > -in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
> > -The copy on write extent size,
> > -.BR fsx_cowextsize ,
> > -can be set at any time.
> > +See
> > +.BR ioctl_xfs_fsgetxattr (2)
> > +for more information.
> >
> > .TP
> > .B XFS_IOC_GETBMAP
> > @@ -649,6 +505,7 @@ The remainder of these operations will not be described further
> > as they are not of general use to applications.
> >
> > .SH SEE ALSO
> > +.BR ioctl_xfs_fsgetxattr (2),
> > .BR fstatfs (2),
> > .BR statfs (2),
> > .BR xfs (5),
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage
2019-07-04 2:04 ` Darrick J. Wong
@ 2019-07-04 3:43 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-04 3:43 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 7/3/19 9:04 PM, Darrick J. Wong wrote:
>> Should we just say that this flag cannot be set on filesystems with the
>> reflink feature enabled?
> Yes.
>
> Thanks for picking this up, sorry I was sloppy. :( :(
Nah, documentation is hard and I'm picky.
> Happy Independence Day!~!
Tanks, man!
-Eric
> --D
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 2/9] man: create a separate GEOMETRY ioctl manpage
2019-06-20 16:51 ` [PATCH 2/9] man: create a separate GEOMETRY " Darrick J. Wong
@ 2019-07-05 15:01 ` Eric Sandeen
2019-07-05 16:25 ` Darrick J. Wong
0 siblings, 1 reply; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 15:01 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Break out the xfs geometry ioctl into a separate manpage so that we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
> man/man2/ioctl_xfs_fsop_geometry.2 | 221 ++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 11 +-
> 2 files changed, 228 insertions(+), 4 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2
Same drill, I can change any agreed-to suggestions on the way in,
just a couple things below.
>
> diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
> new file mode 100644
> index 00000000..c6e89efd
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsop_geometry.2
> @@ -0,0 +1,221 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_fsop_geometry \- report XFS filesystem shape
can we just say geometry here or maybe "layout?" "Shape" isn't really used anywhere else.
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geom*" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geom_v1 *" arg );
> +.SH DESCRIPTION
> +Report the storage space parameters that influence allocation decisions in
> +this XFS filesystem.
This doesn't seem 100% accurate (uuid for example...) but meh.
> +This information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_geom {
> + __u32 blocksize;
> + __u32 rtextsize;
> + __u32 agblocks;
> + __u32 agcount;
> + __u32 logblocks;
> + __u32 sectsize;
> + __u32 inodesize;
> + __u32 imaxpct;
> + __u64 datablocks;
> + __u64 rtblocks;
> + __u64 rtextents;
> + __u64 logstart;
> + unsigned char uuid[16];
> + __u32 sunit;
> + __u32 swidth;
> + __s32 version;
> + __u32 flags;
> + __u32 logsectsize;
> + __u32 rtsectsize;
> + __u32 dirblocksize;
> + /* struct xfs_fsop_geom_v1 stops here. */
> +
> + __u32 logsunit;
> +};
> +.fi
> +.in
> +.PP
> +.I blocksize
> +is the size of a fundamental filesystem block, in bytes.
> +.PP
> +.I rtextsize
> +is the size of an extent on the realtime volume, in bytes.
> +.PP
> +.I agblocks
> +is the size of an allocation group, in units of filesystem blocks.
> +.PP
> +.I agcount
> +is the number of allocation groups in the filesystem.
> +.PP
> +.I logblocks
> +is the size of the log, in units of filesystem blocks.
> +.PP
> +.I sectsize
> +is the smallest amount of data that can be written to the data device
> +atomically, in bytes.
> +.PP
> +.I inodesize
> +is the size of an inode record, in bytes.
> +.PP
> +.I imaxpct
> +is the maximum percentage of the filesystem that can be allocated to inode
> +record blocks.
> +.PP
> +.I datablocks
> +is the size of the data device, in units of filesystem blocks.
> +.PP
> +.I rtblocks
> +is the size of the realtime device, in units of filesystem blocks.
> +.PP
> +.I rtextents
> +is the number of extents that can be allocated on the realtime device.
> +.PP
> +.I logstart
> +is the start of the log, in units of filesystem blocks.
> +If the filesystem has an external log, this will be zero.
> +.PP
> +.I uuid
> +is the universal unique identifier of the filesystem.
> +.PP
> +.I sunit
> +is what the filesystem has been told is the size of a RAID stripe unit on the
> +underlying data device, in filesystem blocks.
> +.PP
> +.I swidth
> +is what the filesystem has been told is the width of a RAID stripe on the
> +underlying data device, in units of RAID stripe units.
> +.PP
> +.I version
> +is the version of this structure.
> +This value will be XFS_FSOP_GEOM_VERSION.
> +.PP
> +.I flags
> +tell us what features are enabled on the filesystem.
> +Refer to the section
> +.B FILESYSTEM FEATURE FLAGS
> +below for more information about each feature.
> +.PP
> +.I logsectsize
> +is the smallest amount of data that can be written to the log device atomically,
> +in bytes.
> +.PP
> +.I rtsectsize
> +is the smallest amount of data that can be written to the realtime device
> +atomically, in bytes.
> +.PP
> +.I dirblocksize
> +is the size of directory blocks, in bytes.
> +.PP
> +.I logsunit
> +is what the filesystem has been told is the size of a RAID stripe unit on the
> +underlying log device, in filesystem blocks.
> +This field is meaningful only if the flag
> +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> +is set.
> +.SH FILESYSTEM FEATURE FLAGS
> +Filesystem features are reported to userspace as a combination the following
> +flags:
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_ATTR
> +Extended attributes are present.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_NLINK
> +This filesystem supports up to 2^32 links.
> +If this flag is not set, the filesystem supports only 2^16 links.
Files on this filesystem support up to 2^32 hard links.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_QUOTA
> +Quotas are enabled.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_IALIGN
> +Inodes are aligned for better performance.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DALIGN
> +Filesystem tries to align data block allocations to RAID stripe units for
> +better performance.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SHARED
> +Unused.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_EXTFLG
> +Filesystem supports unwritten extents.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DIRV2
> +Directories are in version 2 format and maintain free space data for better
> +performance.
> +Version 1 format directories are no longer supported.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> +Log uses the V2 format.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SECTOR
> +The log device has a sector size larger than 512 bytes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_ATTR2
> +Filesystem contains V2 extended attributes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_PROJID32
> +Project IDs can be as large as 2^32.
> +If this flag is not set, the filesystem supports only 2^16 project IDs.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
> +Case-insensitive lookups are supported on directories.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_LAZYSB
> +On-disk superblock counters are updated only at unmount time.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_V5SB
> +Metadata blocks are self describing and contain checksums.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_FTYPE
> +Directories contain inode types in directory entries.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_FINOBT
> +Filesystem maintains an index of free inodes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SPINODES
> +Filesystem may allocate discontiguous inode chunks when free space is
> +fragmented.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_RMAPBT
> +Filesystem stores reverse mappings of blocks to owners.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_REFLINK
> +Filesystem supports sharing blocks between files.
> +.RE
> +
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 2992b5be..1237eac6 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
> be initialized to zero).
> An error is returned if the inode number is invalid.
>
> +.TP
> +.B XFS_IOC_FSGEOMETRY
> +See
> +.BR ioctl_xfs_fsop_geometry (2)
> +for more information.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> @@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
> These interfaces are used to implement various filesystem internal
> operations on XFS filesystems.
> For
> -.B XFS_IOC_FSGEOMETRY
> -(get filesystem mkfs time information), the output structure is of type
> -.BR struct xfs_fsop_geom .
> -For
> .B XFS_FS_COUNTS
> (get filesystem dynamic global information), the output structure is of type
> .BR xfs_fsop_counts_t .
> @@ -506,6 +508,7 @@ as they are not of general use to applications.
>
> .SH SEE ALSO
> .BR ioctl_xfs_fsgetxattr (2),
> +.BR ioctl_xfs_fsop_geometry (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 6/9] man: create a separate FSCOUNTS ioctl manpage
2019-06-20 16:51 ` [PATCH 6/9] man: create a separate FSCOUNTS " Darrick J. Wong
@ 2019-07-05 15:15 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 15:15 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Create a separate manual page for the xfs FSCOUNTS ioctl so we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
> ---
> man/man2/ioctl_xfs_fscounts.2 | 69 +++++++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 14 +++++---
> 2 files changed, 77 insertions(+), 6 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_fscounts.2
>
>
> diff --git a/man/man2/ioctl_xfs_fscounts.2 b/man/man2/ioctl_xfs_fscounts.2
> new file mode 100644
> index 00000000..eb7df89c
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fscounts.2
> @@ -0,0 +1,69 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSCOUNTS 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_fscounts \- query XFS summary counter information
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *" arg );
> +.SH DESCRIPTION
> +Query the raw filesystem summary counters.
> +Unlike
> +.BR statvfs (3),
> +the values returned here are the raw values, which do not reflect any
> +alterations or limits set by project quotas.
> +The counter information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_counts {
> + __u64 freedata;
> + __u64 freertx;
> + __u64 freeino;
> + __u64 allocino;
> +};
> +.fi
> +.in
> +.PP
> +The fields of this structure are as follows:
> +.PP
> +.I freedata
> +is the number of free filesystem blocks on the data device.
> +.PP
> +.I freertx
> +is the number of free extents on the realtime device.
> +.PP
> +.I freeino
> +is the number of inode records that are not in use within the space that has
> +been allocated for them.
> +.PP
> +.I allocino
> +is the number of inode records for which space has been allocated.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index c14f7d33..ee3188ec 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -390,6 +390,12 @@ See
> .BR ioctl_xfs_scrub_metadata (2)
> for more information.
>
> +.TP
> +.B XFS_IOC_FSCOUNTS
> +See
> +.BR ioctl_xfs_fscounts (2)
> +for more information.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> @@ -398,16 +404,11 @@ for more information.
> .B XFS_IOC_SET_RESBLKS
> .B XFS_IOC_FSGROWFSDATA
> .B XFS_IOC_FSGROWFSLOG
> -.B XFS_IOC_FSGROWFSRT
> .fi
> .TP
> -.B XFS_IOC_FSCOUNTS
> +.B XFS_IOC_FSGROWFSRT
> These interfaces are used to implement various filesystem internal
> operations on XFS filesystems.
> -For
> -.B XFS_FS_COUNTS
> -(get filesystem dynamic global information), the output structure is of type
> -.BR xfs_fsop_counts_t .
> The remainder of these operations will not be described further
> as they are not of general use to applications.
>
> @@ -417,6 +418,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_fsbulkstat (2),
> .BR ioctl_xfs_scrub_metadata (2),
> .BR ioctl_xfs_fsinumbers (2),
> +.BR ioctl_xfs_fscounts (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 5/9] man: create a separate INUMBERS ioctl manpage
2019-06-20 16:51 ` [PATCH 5/9] man: create a separate INUMBERS ioctl manpage Darrick J. Wong
@ 2019-07-05 15:16 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 15:16 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Create a separate manual page for the xfs INUMBERS ioctl so we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
modulo small change to move "last inode". to "last inode."
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
> ---
> man/man2/ioctl_xfs_fsinumbers.2 | 122 +++++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 34 +----------
> 2 files changed, 126 insertions(+), 30 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_fsinumbers.2
>
>
> diff --git a/man/man2/ioctl_xfs_fsinumbers.2 b/man/man2/ioctl_xfs_fsinumbers.2
> new file mode 100644
> index 00000000..04f32109
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsinumbers.2
> @@ -0,0 +1,122 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSINUMBERS 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_fsinumbers \- extract a list of valid inode numbers from an XFS filesystem
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *" arg );
> +.SH DESCRIPTION
> +Queries inode allocation information from an XFS filesystem.
> +It is intended to be called iteratively to obtain the entire set of inodes.
> +These ioctls use
> +.B struct xfs_fsop_bulkreq
> +to set up a bulk transfer with the kernel:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_bulkreq {
> + __u64 *lastip;
> + __s32 count;
> + void *ubuffer;
> + __s32 *ocount;
> +};
> +.fi
> +.in
> +.PP
> +.I lastip
> +points to a value that will receive the number of the "last inode".
> +This should be set to one less than the number of the first inode for which the
> +caller wants information, or zero to start with the first inode in the
> +filesystem.
> +After the call, this value will be set to the number of the last inode for
> +which information is supplied.
> +This field will not be updated if
> +.I ocount
> +is NULL.
> +.PP
> +.I count
> +is the number of elements in the
> +.B ubuffer
> +array and therefore the number of inode groups for which to return allocation
> +information.
> +.PP
> +.I ocount
> +points to a value that will receive the number of records returned.
> +An output value of zero means that there are no more inode groups left to
> +enumerate.
> +If this value is NULL, then neither
> +.I ocount
> +nor
> +.I lastip
> +will be updated.
> +.PP
> +.I ubuffer
> +points to a memory buffer where inode group information will be copied.
> +This buffer must be an array of
> +.B struct xfs_inogrp
> +which is described below.
> +The array must have at least
> +.I count
> +elements.
> +.PP
> +.in +4n
> +.nf
> +struct xfs_inogrp {
> + __u64 xi_startino;
> + __s32 xi_alloccount;
> + __u64 xi_allocmask;
> +}
> +.fi
> +.in
> +.PP
> +This structure describes inode usage information for a group of 64 consecutive
> +inode numbers.
> +The fields are as follows:
> +.PP
> +.I xi_startino
> +is the first inode number of this group.
> +.PP
> +.I xi_alloccount
> +is the number of bits that are set in
> +.IR xi_allocmask .
> +This is the number of inodes allocated in this group.
> +.PP
> +.I xi_allocmask
> +is a bitmask of inodes that are allocated in this inode group.
> +The bitmask is 64 bits long, and the least significant bit corresponds to inode
> +.BR xi_startino .
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 78fad975..c14f7d33 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -368,36 +368,9 @@ can be any open file in the XFS filesystem in question.
> .PP
> .TP
> .B XFS_IOC_FSINUMBERS
> -This interface is used to extract a list of valid inode numbers from an
> -XFS filesystem.
> -It is intended to be called iteratively, to obtain the entire set of inodes.
> -The information is passed in and out via a structure of type
> -.B xfs_fsop_bulkreq_t
> -pointed to by the final argument.
> -.B lastip
> -is a pointer to a variable containing the last inode number returned,
> -initially it should be zero.
> -.B icount
> -is the size of the array of structures specified by
> -.BR ubuffer .
> -.B ubuffer
> -is the address of an array of structures, of type
> -.BR xfs_inogrp_t .
> -This structure has the following elements:
> -.B xi_startino
> -(starting inode number),
> -.B xi_alloccount
> -(count of bits set in xi_allocmask), and
> -.B xi_allocmask
> -(mask of allocated inodes in this group).
> -The bitmask is 64 bits long, and the least significant bit corresponds to inode
> -.B xi_startino.
> -Each bit is set if the corresponding inode is in use.
> -.B ocount
> -is a pointer to a count of returned values, filled in by the call.
> -An output
> -.B ocount
> -value of zero means that the inode table has been exhausted.
> +See
> +.BR ioctl_xfs_fsinumbers (2)
> +for more information.
>
> .TP
> .B XFS_IOC_FSGEOMETRY
> @@ -443,6 +416,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_fsop_geometry (2),
> .BR ioctl_xfs_fsbulkstat (2),
> .BR ioctl_xfs_scrub_metadata (2),
> +.BR ioctl_xfs_fsinumbers (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP ioctl manpage
2019-06-20 16:51 ` [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP " Darrick J. Wong
@ 2019-07-05 15:53 ` Eric Sandeen
2019-07-05 17:19 ` Darrick J. Wong
0 siblings, 1 reply; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 15:53 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Create a separate manual page for the xfs BMAP ioctls so we can document
> how they work.
Same drill ... ;)
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
> man/man2/ioctl_xfs_getbmap.2 | 1
> man/man2/ioctl_xfs_getbmapa.2 | 1
> man/man2/ioctl_xfs_getbmapx.2 | 172 +++++++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 61 ++-------------
> 4 files changed, 184 insertions(+), 51 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_getbmap.2
> create mode 100644 man/man2/ioctl_xfs_getbmapa.2
> create mode 100644 man/man2/ioctl_xfs_getbmapx.2
>
>
> diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
> new file mode 100644
> index 00000000..909402fc
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getbmap.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_xfs_getbmapx.2
> diff --git a/man/man2/ioctl_xfs_getbmapa.2 b/man/man2/ioctl_xfs_getbmapa.2
> new file mode 100644
> index 00000000..909402fc
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getbmapa.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_xfs_getbmapx.2
> diff --git a/man/man2/ioctl_xfs_getbmapx.2 b/man/man2/ioctl_xfs_getbmapx.2
> new file mode 100644
> index 00000000..cf21ca32
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getbmapx.2
> @@ -0,0 +1,172 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GETBMAPX 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_getbmapx \- query extent information for an open file
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
> +.SH DESCRIPTION
> +Get the block map for a segment of a file in an XFS file system.
> +The mapping information is conveyed in a structure of the following form:
"conveyed via an array of structures of the following form"
(otherwise below we suddenly refer to "the array" which might leave some heads scratching)
> +.PP
> +.in +4n
> +.nf
> +struct getbmap {
> + __s64 bmv_offset;
> + __s64 bmv_block;
> + __s64 bmv_length;
> + __s32 bmv_count;
> + __s32 bmv_entries;
> +};
> +.fi
> +.in
> +.PP
> +The
> +.B XFS_IOC_GETBMAPX
> +ioctl uses a larger version of that structure:
> +.PP
> +.in +4n
> +.nf
> +struct getbmapx {
> + __s64 bmv_offset;
> + __s64 bmv_block;
> + __s64 bmv_length;
> + __s32 bmv_count;
> + __s32 bmv_entries;
> + __s32 bmv_iflags;
> + __s32 bmv_oflags;
> + __s32 bmv_unused1;
> + __s32 bmv_unused2;
> +};
> +.fi
> +.in
> +.PP
> +All sizes and offsets in the structure are in units of 512 bytes.
> +.PP
> +The first structure in the array is a header and the remaining structures in
> +the array contain block map information on return.
> +The header controls iterative calls to the command and should be filled out as
> +follows:
> +.TP
> +.I bmv_offset
> +The file offset of the area of interest in the file.
> +.TP
> +.I bmv_length
> +The length of the area of interest in the file.
> +If this value is set to -1, the length of the interesting area is the rest of
> +the file.
> +.TP
> +.I bmv_count
> +The length of the array, including this header.
"The number of elements in the array, including this header. The minimum value is 2."
> +.TP
> +.I bmv_entries
> +The number of entries actually filled in by the call.
> +This does not need to be filled out before the call.
I also wonder if we should say something about how to know when iterative
calls are done. Perhaps:
"This value may be zero if no extents were found in the requested
range, or if iterated calls have reached the end of the requested
range"
> +.TP
> +.I bmv_iflags
> +For the
> +.B XFS_IOC_GETBMAPX
> +function, this is a bitmask containing a combination of the following flags:
> +.RS 0.4i
> +.TP
> +.B BMV_IF_ATTRFORK
> +Return information about the extended attribute fork.
> +.TP
> +.B BMV_IF_PREALLOC
> +Return information about unwritten pre-allocated segments.
> +.TP
> +.B BMV_IF_DELALLOC
> +Return information about delayed allocation reservation segments.
> +.TP
> +.B BMV_IF_NO_HOLES
> +Do not return information about holes.
> +.RE
> +.PD 1
> +.PP
> +The other
> +.I bmv_*
> +fields in the header are ignored.
> +.PP
> +On return from a call, the header is updated so that the command can be
> +reused to obtain more information without re-initializing the structures.
Perhaps:
"On successful return from a call, the offset and length values in the header
are updated so that the command can be reused to obtain more information."
> +The remainder of the array will be filled out by the call as follows:
"The remaining elements of the array will be filled out ..."
> +
> +.TP
> +.I bmv_offset
> +File offset of segment.
> +.TP
> +.I bmv_block
> +Physical starting block of segment.
> +If this is -1, then the segment is a hole.
> +.TP
> +.I bmv_length
> +Length of segment.
> +.TP
> +.I bmv_oflags
> +The
> +.B XFS_IOC_GETBMAPX
> +function will fill this field with a combination of the following flags:
> +.RS 0.4i
> +.TP
> +.B BMV_OF_PREALLOC
> +The segment is an unwritten pre-allocation.
> +.TP
> +.B BMV_OF_DELALLOC
> +The segment is a delayed allocation reservation.
> +.TP
> +.B BMV_OF_LAST
> +This segment is the last in the file.
> +.TP
> +.B BMV_OF_SHARED
> +This segment shares blocks with other files.
> +.RE
> +.PD 1
> +.PP
> +The other
> +.I bmv_*
> +fields are ignored in the array of outputted records.
"are unused in the array of output records."
-Eric
> +.PP
> +The
> +.B XFS_IOC_GETBMAPA
> +command is identical to
> +.B XFS_IOC_GETBMAP
> +except that information about the attribute fork of the file is returned.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 89975a3c..077dd411 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -144,59 +144,17 @@ See
> .BR ioctl_xfs_fsgetxattr (2)
> for more information.
>
> -.TP
> -.B XFS_IOC_GETBMAP
> -Get the block map for a segment of a file in an XFS file system.
> -The final argument points to an arry of variables of type
> -.BR "struct getbmap" .
> -All sizes and offsets in the structure are in units of 512 bytes.
> -The structure fields include:
> -.B bmv_offset
> -(file offset of segment),
> -.B bmv_block
> -(starting block of segment),
> -.B bmv_length
> -(length of segment),
> -.B bmv_count
> -(number of array entries, including the first), and
> -.B bmv_entries
> -(number of entries filled in).
> -The first structure in the array is a header, and the remaining
> -structures in the array contain block map information on return.
> -The header controls iterative calls to the
> +.PP
> +.nf
> .B XFS_IOC_GETBMAP
> -command.
> -The caller fills in the
> -.B bmv_offset
> -and
> -.B bmv_length
> -fields of the header to indicate the area of interest in the file,
> -and fills in the
> -.B bmv_count
> -field to indicate the length of the array.
> -If the
> -.B bmv_length
> -value is set to \-1 then the length of the interesting area is the rest
> -of the file.
> -On return from a call, the header is updated so that the command can be
> -reused to obtain more information, without re-initializing the structures.
> -Also on return, the
> -.B bmv_entries
> -field of the header is set to the number of array entries actually filled in.
> -The non-header structures will be filled in with
> -.BR bmv_offset ,
> -.BR bmv_block ,
> -and
> -.BR bmv_length .
> -If a region of the file has no blocks (is a hole in the file) then the
> -.B bmv_block
> -field is set to \-1.
> -
> -.TP
> .B XFS_IOC_GETBMAPA
> -Identical to
> -.B XFS_IOC_GETBMAP
> -except that information about the attribute fork of the file is returned.
> +.fi
> +.PD 0
> +.TP
> +.B XFS_IOC_GETBMAPX
> +See
> +.BR ioctl_getbmap (2)
> +for more information.
>
> .PP
> .B XFS_IOC_RESVSP
> @@ -429,6 +387,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_fsinumbers (2),
> .BR ioctl_xfs_fscounts (2),
> .BR ioctl_xfs_getresblks (2),
> +.BR ioctl_xfs_getbmap (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 7/9] man: create a separate RESBLKS ioctl manpage
2019-06-20 16:51 ` [PATCH 7/9] man: create a separate RESBLKS " Darrick J. Wong
@ 2019-07-05 16:02 ` Eric Sandeen
2019-07-05 17:09 ` Darrick J. Wong
0 siblings, 1 reply; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 16:02 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Create a separate manual page for the xfs RESBLKS ioctls so we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
> man/man2/ioctl_xfs_getresblks.2 | 65 +++++++++++++++++++++++++++++++++++++++
> man/man2/ioctl_xfs_setresblks.2 | 1 +
> man/man3/xfsctl.3 | 14 +++++++-
> 3 files changed, 78 insertions(+), 2 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_getresblks.2
> create mode 100644 man/man2/ioctl_xfs_setresblks.2
>
>
> diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
> new file mode 100644
> index 00000000..694b4496
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getresblks.2
> @@ -0,0 +1,65 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GETRESBLKS 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_getresblks \- query XFS summary counter information
^^^^^^^^^^^^^^^
"query and set XFS free space reservation information"
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
> +.SH DESCRIPTION
I wonder if starting with a "don't use" right here would be wise, something like:
"Note: This is a[n] test/debug ioctl intended only for use by XFS filesystem developers."
> +Query or set the free space reservation information.
> +These blocks are reserved by the filesystem as a final attempt to prevent
> +metadata update failures due to insufficient space.
> +Only the system administrator can call these ioctls, because overriding the
> +defaults is extremely dangerous and should never be tried by anyone.
> +.PP
> +The reservation information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_resblks {
> + __u64 resblks;
> + __u64 resblks_avail;
> +};
> +.fi
> +.in
> +.PP
> +.I resblks
> +is the number of blocks that the filesystem will try to maintain to prevent
> +critical out of space situations.
> +.PP
> +.I resblks_avail
> +is the number of reserved blocks remaining.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B EPERM
> +Caller does not have permission to call this ioctl.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man2/ioctl_xfs_setresblks.2 b/man/man2/ioctl_xfs_setresblks.2
> new file mode 100644
> index 00000000..209bc0a8
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_setresblks.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_xfs_getresblks.2
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index ee3188ec..89975a3c 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -396,12 +396,21 @@ See
> .BR ioctl_xfs_fscounts (2)
> for more information.
>
> +.TP
> +.nf
> +.B XFS_IOC_GET_RESBLKS
> +.fi
> +.TP
> +.B XFS_IOC_SET_RESBLKS
> +See
> +.BR ioctl_xfs_getresblks (2)
> +for more information.
> +Save yourself a lot of frustration and avoid these ioctls.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> .B XFS_IOC_FREEZE
> -.B XFS_IOC_GET_RESBLKS
> -.B XFS_IOC_SET_RESBLKS
> .B XFS_IOC_FSGROWFSDATA
> .B XFS_IOC_FSGROWFSLOG
> .fi
> @@ -419,6 +428,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_scrub_metadata (2),
> .BR ioctl_xfs_fsinumbers (2),
> .BR ioctl_xfs_fscounts (2),
> +.BR ioctl_xfs_getresblks (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 9/9] man: create a separate xfs shutdown ioctl manpage
2019-06-20 16:51 ` [PATCH 9/9] man: create a separate xfs shutdown " Darrick J. Wong
@ 2019-07-05 16:08 ` Eric Sandeen
2019-07-05 17:13 ` Darrick J. Wong
0 siblings, 1 reply; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 16:08 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Create a separate manual page for the xfs shutdown ioctl so we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
> man/man2/ioctl_xfs_goingdown.2 | 63 ++++++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 7 ++++
> 2 files changed, 70 insertions(+)
> create mode 100644 man/man2/ioctl_xfs_goingdown.2
>
>
> diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
> new file mode 100644
> index 00000000..bedc85c8
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_goingdown.2
> @@ -0,0 +1,63 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GOINGDOWN 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_goingdown \- shut down an XFS filesystem
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
> +.SH DESCRIPTION
> +Shuts down a live XFS filesystem.
> +This is a software initiated hard shutdown and should be avoided whenever
> +possible.
> +After this call completes, the filesystem will be totally unusable and must be
> +unmounted.
That almost sounds permanently destructive. Perhaps:
"... will be totally unusable until the filesystem has been unmounted and remounted."
?
> +
> +.PP
> +.I flags
> +can be one of the following:
> +.RS 0.4i
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_DEFAULT
> +Flush all dirty data and in-core state to disk, flush pending transactions to
> +the log, and shut down.
What exactly do we mean by "in-core state" here? I'm not sure the average
reader will know (I'm not sure I know)
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
> +Flush all pending transactions to the log and shut down, leaving all dirty
> +data unwritten.
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
> +Shut down immediately, without writing pending transactions or dirty data
> +to disk.
> +
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
Hm crud, now I wonder about auditing all your stated error codes.
EPERM, EFAULT, and EINVAL seem to be the only options for this
particular call. Maybe that can be a 2nd cleanup, documenting
an error code that won't happen is harmless...
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B EPERM
> +Caller did not have permission to shut down the filesystem.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 077dd411..7e6588b8 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -365,6 +365,12 @@ See
> for more information.
> Save yourself a lot of frustration and avoid these ioctls.
>
> +.TP
> +.B XFS_IOC_GOINGDOWN
> +See
> +.BR ioctl_xfs_goingdown (2)
> +for more information.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> @@ -388,6 +394,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_fscounts (2),
> .BR ioctl_xfs_getresblks (2),
> .BR ioctl_xfs_getbmap (2),
> +.BR ioctl_xfs_goingdown (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 3/9] man: create a separate FSBULKSTAT ioctl manpage
2019-06-20 16:51 ` [PATCH 3/9] man: create a separate FSBULKSTAT " Darrick J. Wong
@ 2019-07-05 16:22 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 16:22 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Break out the xfs bulkstat ioctl into a separate manpage so that we can
> document how it works.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
same small thing for "last inode."
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
> ---
> man/man2/ioctl_xfs_fsbulkstat.2 | 216 +++++++++++++++++++++++++++++++++++++++
> man/man3/xfsctl.3 | 87 +---------------
> 2 files changed, 223 insertions(+), 80 deletions(-)
> create mode 100644 man/man2/ioctl_xfs_fsbulkstat.2
>
>
> diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
> new file mode 100644
> index 00000000..f50f80bd
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsbulkstat.2
> @@ -0,0 +1,216 @@
> +.\" Copyright (c) 2019, Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSBULKSTAT 2 2019-06-17 "XFS"
> +.SH NAME
> +ioctl_xfs_fsbulkstat \- query information for a batch of XFS inodes
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
> +.br
> +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
> +.SH DESCRIPTION
> +Query stat information for a group of XFS inodes.
> +These ioctls use
> +.B struct xfs_fsop_bulkreq
> +to set up a bulk transfer with the kernel:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_bulkreq {
> + __u64 *lastip;
> + __s32 count;
> + void *ubuffer;
> + __s32 *ocount;
> +};
> +.fi
> +.in
> +.PP
> +.I lastip
> +points to a value that will receive the number of the "last inode".
> +This cannot be NULL.
> +For
> +.BR FSBULKSTAT ,
> +this should be set to one less than the number of the first inode for which the
> +caller wants information, or zero to start with the first inode in the
> +filesystem.
> +For
> +.BR FSBULKSTAT_SINGLE ,
> +this should be set to the number of the inode for which the caller wants
> +information.
> +After the call, this value will be set to the number of the last inode for
> +which information was supplied.
> +This field will not be updated if
> +.I ocount
> +is NULL.
> +.PP
> +.I count
> +is the number of elements in the
> +.B ubuffer
> +array and therefore the number of inodes for which to return stat information.
> +This value must be set to 1 for
> +.BR FSBULKSTAT_SINGLE .
> +.PP
> +.I ocount
> +points to a value that will receive the number of records returned.
> +If this value is NULL, then neither
> +.I ocount
> +nor
> +.I lastip
> +will be updated.
> +.PP
> +.I ubuffer
> +points to a memory buffer into which inode stat information will be copied.
> +This buffer must be an array of
> +.B struct xfs_bstat
> +which is described below.
> +The array must have at least
> +.I count
> +elements.
> +.PP
> +.in +4n
> +.nf
> +struct xfs_bstat {
> + __u64 bs_ino;
> + __u16 bs_mode;
> + __u16 bs_nlink;
> + __u32 bs_uid;
> + __u32 bs_gid;
> + __u32 bs_rdev;
> + __s32 bs_blksize;
> + __s64 bs_size;
> + struct xfs_bstime bs_atime;
> + struct xfs_bstime bs_mtime;
> + struct xfs_bstime bs_ctime;
> + int64_t bs_blocks;
> + __u32 bs_xflags;
> + __s32 bs_extsize;
> + __s32 bs_extents;
> + __u32 bs_gen;
> + __u16 bs_projid_lo;
> + __u16 bs_forkoff;
> + __u16 bs_projid_hi;
> + unsigned char bs_pad[6];
> + __u32 bs_cowextsize;
> + __u32 bs_dmevmask;
> + __u16 bs_dmstate;
> + __u16 bs_aextents;
> +};
> +.fi
> +.in
> +.PP
> +The structure members are as follows:
> +.PP
> +.I bs_ino
> +is the inode number for this record.
> +.PP
> +.I bs_mode
> +is the file type and mode.
> +.PP
> +.I bs_nlink
> +is the number of hard links to this inode.
> +.PP
> +.I bs_uid
> +is the user id.
> +.PP
> +.I bs_gid
> +is the group id.
> +.PP
> +.I bs_rdev
> +is the encoded device id if this is a special file.
> +.PP
> +.I bs_blksize
> +is the size of a data block for this file, in units of bytes.
> +.PP
> +.I bs_size
> +is the size of the file, in bytes.
> +.PP
> +.I bs_atime
> +is the last time this file was accessed.
> +.PP
> +.I bs_mtime
> +is the last time the contents of this file were modified.
> +.PP
> +.I bs_ctime
> +is the last time this inode record was modified.
> +.PP
> +.I bs_blocks
> +is the number of filesystem blocks allocated to this file, including metadata.
> +.PP
> +.I bs_xflags
> +contains the extended flags that are set on this inode.
> +These flags are the same values as those defined in the
> +.B XFS INODE FLAGS
> +section of the
> +.BR ioctl_xfs_fsgetxattr (2)
> +manpage.
> +
> +.PD 1
> +.PP
> +.I bs_extsize
> +is the extent size hint for this file, in bytes.
> +.PP
> +.I bs_extents
> +is the number of storage mappings associated with this file's data.
> +.PP
> +.I bs_gen
> +is the generation number of the inode record.
> +.PP
> +.I bs_projid_lo
> +is the lower 16-bits of the project id.
> +.PP
> +.I bs_forkoff
> +is the offset of the attribute fork in the inode record, in bytes.
> +.PP
> +.I bs_projid_hi
> +is the upper 16-bits of the project id.
> +.PP
> +.I bs_pad[6]
> +is zeroed.
> +.PP
> +.I bs_cowextsize
> +is the Copy on Write extent size hint for this file, in bytes.
> +.PP
> +.I bs_dmevmask
> +is unused on Linux.
> +.PP
> +.I bs_dmstate
> +is unused on Linux.
> +.PP
> +.I bs_aextents
> +is the number of storage mappings associated with this file's extended
> +attributes.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2),
> +.BR ioctl_xfs_fsgetxattr (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 1237eac6..94a6ad4b 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -399,92 +399,18 @@ An output
> .B ocount
> value of zero means that the inode table has been exhausted.
>
> -.TP
> -.B XFS_IOC_FSBULKSTAT
> -This interface is used to extract inode information (stat
> -information) "in bulk" from a filesystem. It is intended to
> -be called iteratively, to obtain information about the entire
> -set of inodes in a filesystem.
> -The information is passed in and out via a structure of type
> -.B xfs_fsop_bulkreq_t
> -pointed to by the final argument.
> -.B lastip
> -is a pointer to a variable containing the last inode number returned,
> -initially it should be zero.
> -.B icount
> -indicates the size of the array of structures specified by
> -.B ubuffer.
> -.B ubuffer
> -is the address of an array of structures of type
> -.BR xfs_bstat_t .
> -Many of the elements in the structure are the same as for the stat
> -structure.
> -The structure has the following elements:
> -.B bs_ino
> -(inode number),
> -.B bs_mode
> -(type and mode),
> -.B bs_nlink
> -(number of links),
> -.B bs_uid
> -(user id),
> -.B bs_gid
> -(group id),
> -.B bs_rdev
> -(device value),
> -.B bs_blksize
> -(block size of the filesystem),
> -.B bs_size
> -(file size in bytes),
> -.B bs_atime
> -(access time),
> -.B bs_mtime
> -(modify time),
> -.B bs_ctime
> -(inode change time),
> -.B bs_blocks
> -(number of blocks used by the file),
> -.B bs_xflags
> -(extended flags),
> -.B bs_extsize
> -(extent size),
> -.B bs_extents
> -(number of extents),
> -.B bs_gen
> -(generation count),
> -.B bs_projid_lo
> -(project id - low word),
> -.B bs_projid_hi
> -(project id - high word, used when projid32bit feature is enabled),
> -.B bs_dmevmask
> -(DMIG event mask),
> -.B bs_dmstate
> -(DMIG state information), and
> -.B bs_aextents
> -(attribute extent count).
> -.B ocount
> -is a pointer to a count of returned values, filled in by the call.
> -An output
> -.B ocount
> -value of zero means that the inode table has been exhausted.
> -
> -.TP
> -.B XFS_IOC_FSBULKSTAT_SINGLE
> -This interface is a variant of the
> -.B XFS_IOC_FSBULKSTAT
> -interface, used to obtain information about a single inode.
> -for an open file in the filesystem of interest.
> -The same structure is used to pass information in and out of
> -the kernel, except no output count parameter is used (should
> -be initialized to zero).
> -An error is returned if the inode number is invalid.
> -
> .TP
> .B XFS_IOC_FSGEOMETRY
> See
> .BR ioctl_xfs_fsop_geometry (2)
> for more information.
>
> +.TP
> +.BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
> +See
> +.BR ioctl_xfs_fsbulkstat (2)
> +for more information.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> @@ -509,6 +435,7 @@ as they are not of general use to applications.
> .SH SEE ALSO
> .BR ioctl_xfs_fsgetxattr (2),
> .BR ioctl_xfs_fsop_geometry (2),
> +.BR ioctl_xfs_fsbulkstat (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3
2019-06-20 16:51 ` [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3 Darrick J. Wong
@ 2019-07-05 16:23 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 16:23 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
>
> Link to the scrub ioctl documentation from xfsctl.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
> ---
> man/man3/xfsctl.3 | 7 +++++++
> 1 file changed, 7 insertions(+)
>
>
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 94a6ad4b..78fad975 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -411,6 +411,12 @@ See
> .BR ioctl_xfs_fsbulkstat (2)
> for more information.
>
> +.TP
> +.B XFS_IOC_SCRUB_METADATA
> +See
> +.BR ioctl_xfs_scrub_metadata (2)
> +for more information.
> +
> .PP
> .nf
> .B XFS_IOC_THAW
> @@ -436,6 +442,7 @@ as they are not of general use to applications.
> .BR ioctl_xfs_fsgetxattr (2),
> .BR ioctl_xfs_fsop_geometry (2),
> .BR ioctl_xfs_fsbulkstat (2),
> +.BR ioctl_xfs_scrub_metadata (2),
> .BR fstatfs (2),
> .BR statfs (2),
> .BR xfs (5),
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 2/9] man: create a separate GEOMETRY ioctl manpage
2019-07-05 15:01 ` Eric Sandeen
@ 2019-07-05 16:25 ` Darrick J. Wong
0 siblings, 0 replies; 26+ messages in thread
From: Darrick J. Wong @ 2019-07-05 16:25 UTC (permalink / raw)
To: Eric Sandeen; +Cc: linux-xfs
On Fri, Jul 05, 2019 at 10:01:56AM -0500, Eric Sandeen wrote:
>
>
> On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> >
> > Break out the xfs geometry ioctl into a separate manpage so that we can
> > document how it works.
> >
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> > man/man2/ioctl_xfs_fsop_geometry.2 | 221 ++++++++++++++++++++++++++++++++++++
> > man/man3/xfsctl.3 | 11 +-
> > 2 files changed, 228 insertions(+), 4 deletions(-)
> > create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2
>
> Same drill, I can change any agreed-to suggestions on the way in,
> just a couple things below.
>
> >
> > diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
> > new file mode 100644
> > index 00000000..c6e89efd
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsop_geometry.2
> > @@ -0,0 +1,221 @@
> > +.\" Copyright (c) 2019, Oracle. All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-06-17 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsop_geometry \- report XFS filesystem shape
>
> can we just say geometry here or maybe "layout?" "Shape" isn't really
> used anywhere else.
Eh, I guess that's fine for the title. I was trying to avoid using
geometry to define itself, but that can wait.
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geom*" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geom_v1 *" arg );
> > +.SH DESCRIPTION
> > +Report the storage space parameters that influence allocation decisions in
> > +this XFS filesystem.
>
> This doesn't seem 100% accurate (uuid for example...) but meh.
"Report the parameters that control filesystem space configuration
decisions in a particular XFS filesystem."
Any better?
>
> > +This information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_geom {
> > + __u32 blocksize;
> > + __u32 rtextsize;
> > + __u32 agblocks;
> > + __u32 agcount;
> > + __u32 logblocks;
> > + __u32 sectsize;
> > + __u32 inodesize;
> > + __u32 imaxpct;
> > + __u64 datablocks;
> > + __u64 rtblocks;
> > + __u64 rtextents;
> > + __u64 logstart;
> > + unsigned char uuid[16];
> > + __u32 sunit;
> > + __u32 swidth;
> > + __s32 version;
> > + __u32 flags;
> > + __u32 logsectsize;
> > + __u32 rtsectsize;
> > + __u32 dirblocksize;
> > + /* struct xfs_fsop_geom_v1 stops here. */
> > +
> > + __u32 logsunit;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I blocksize
> > +is the size of a fundamental filesystem block, in bytes.
> > +.PP
> > +.I rtextsize
> > +is the size of an extent on the realtime volume, in bytes.
> > +.PP
> > +.I agblocks
> > +is the size of an allocation group, in units of filesystem blocks.
> > +.PP
> > +.I agcount
> > +is the number of allocation groups in the filesystem.
> > +.PP
> > +.I logblocks
> > +is the size of the log, in units of filesystem blocks.
> > +.PP
> > +.I sectsize
> > +is the smallest amount of data that can be written to the data device
> > +atomically, in bytes.
> > +.PP
> > +.I inodesize
> > +is the size of an inode record, in bytes.
> > +.PP
> > +.I imaxpct
> > +is the maximum percentage of the filesystem that can be allocated to inode
> > +record blocks.
> > +.PP
> > +.I datablocks
> > +is the size of the data device, in units of filesystem blocks.
> > +.PP
> > +.I rtblocks
> > +is the size of the realtime device, in units of filesystem blocks.
> > +.PP
> > +.I rtextents
> > +is the number of extents that can be allocated on the realtime device.
> > +.PP
> > +.I logstart
> > +is the start of the log, in units of filesystem blocks.
> > +If the filesystem has an external log, this will be zero.
> > +.PP
> > +.I uuid
> > +is the universal unique identifier of the filesystem.
> > +.PP
> > +.I sunit
> > +is what the filesystem has been told is the size of a RAID stripe unit on the
> > +underlying data device, in filesystem blocks.
> > +.PP
> > +.I swidth
> > +is what the filesystem has been told is the width of a RAID stripe on the
> > +underlying data device, in units of RAID stripe units.
> > +.PP
> > +.I version
> > +is the version of this structure.
> > +This value will be XFS_FSOP_GEOM_VERSION.
> > +.PP
> > +.I flags
> > +tell us what features are enabled on the filesystem.
> > +Refer to the section
> > +.B FILESYSTEM FEATURE FLAGS
> > +below for more information about each feature.
> > +.PP
> > +.I logsectsize
> > +is the smallest amount of data that can be written to the log device atomically,
> > +in bytes.
> > +.PP
> > +.I rtsectsize
> > +is the smallest amount of data that can be written to the realtime device
> > +atomically, in bytes.
> > +.PP
> > +.I dirblocksize
> > +is the size of directory blocks, in bytes.
> > +.PP
> > +.I logsunit
> > +is what the filesystem has been told is the size of a RAID stripe unit on the
> > +underlying log device, in filesystem blocks.
> > +This field is meaningful only if the flag
> > +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> > +is set.
> > +.SH FILESYSTEM FEATURE FLAGS
> > +Filesystem features are reported to userspace as a combination the following
> > +flags:
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_ATTR
> > +Extended attributes are present.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_NLINK
> > +This filesystem supports up to 2^32 links.
> > +If this flag is not set, the filesystem supports only 2^16 links.
>
> Files on this filesystem support up to 2^32 hard links.
Yes, that's better. :)
--D
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_QUOTA
> > +Quotas are enabled.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_IALIGN
> > +Inodes are aligned for better performance.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DALIGN
> > +Filesystem tries to align data block allocations to RAID stripe units for
> > +better performance.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SHARED
> > +Unused.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_EXTFLG
> > +Filesystem supports unwritten extents.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DIRV2
> > +Directories are in version 2 format and maintain free space data for better
> > +performance.
> > +Version 1 format directories are no longer supported.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> > +Log uses the V2 format.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SECTOR
> > +The log device has a sector size larger than 512 bytes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_ATTR2
> > +Filesystem contains V2 extended attributes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_PROJID32
> > +Project IDs can be as large as 2^32.
> > +If this flag is not set, the filesystem supports only 2^16 project IDs.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
> > +Case-insensitive lookups are supported on directories.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_LAZYSB
> > +On-disk superblock counters are updated only at unmount time.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_V5SB
> > +Metadata blocks are self describing and contain checksums.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_FTYPE
> > +Directories contain inode types in directory entries.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_FINOBT
> > +Filesystem maintains an index of free inodes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SPINODES
> > +Filesystem may allocate discontiguous inode chunks when free space is
> > +fragmented.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_RMAPBT
> > +Filesystem stores reverse mappings of blocks to owners.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_REFLINK
> > +Filesystem supports sharing blocks between files.
> > +.RE
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 2992b5be..1237eac6 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
> > be initialized to zero).
> > An error is returned if the inode number is invalid.
> >
> > +.TP
> > +.B XFS_IOC_FSGEOMETRY
> > +See
> > +.BR ioctl_xfs_fsop_geometry (2)
> > +for more information.
> > +
> > .PP
> > .nf
> > .B XFS_IOC_THAW
> > @@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
> > These interfaces are used to implement various filesystem internal
> > operations on XFS filesystems.
> > For
> > -.B XFS_IOC_FSGEOMETRY
> > -(get filesystem mkfs time information), the output structure is of type
> > -.BR struct xfs_fsop_geom .
> > -For
> > .B XFS_FS_COUNTS
> > (get filesystem dynamic global information), the output structure is of type
> > .BR xfs_fsop_counts_t .
> > @@ -506,6 +508,7 @@ as they are not of general use to applications.
> >
> > .SH SEE ALSO
> > .BR ioctl_xfs_fsgetxattr (2),
> > +.BR ioctl_xfs_fsop_geometry (2),
> > .BR fstatfs (2),
> > .BR statfs (2),
> > .BR xfs (5),
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 7/9] man: create a separate RESBLKS ioctl manpage
2019-07-05 16:02 ` Eric Sandeen
@ 2019-07-05 17:09 ` Darrick J. Wong
0 siblings, 0 replies; 26+ messages in thread
From: Darrick J. Wong @ 2019-07-05 17:09 UTC (permalink / raw)
To: Eric Sandeen; +Cc: linux-xfs
On Fri, Jul 05, 2019 at 11:02:40AM -0500, Eric Sandeen wrote:
> On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> >
> > Create a separate manual page for the xfs RESBLKS ioctls so we can
> > document how it works.
> >
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> > man/man2/ioctl_xfs_getresblks.2 | 65 +++++++++++++++++++++++++++++++++++++++
> > man/man2/ioctl_xfs_setresblks.2 | 1 +
> > man/man3/xfsctl.3 | 14 +++++++-
> > 3 files changed, 78 insertions(+), 2 deletions(-)
> > create mode 100644 man/man2/ioctl_xfs_getresblks.2
> > create mode 100644 man/man2/ioctl_xfs_setresblks.2
> >
> >
> > diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
> > new file mode 100644
> > index 00000000..694b4496
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getresblks.2
> > @@ -0,0 +1,65 @@
> > +.\" Copyright (c) 2019, Oracle. All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GETRESBLKS 2 2019-06-17 "XFS"
> > +.SH NAME
> > +ioctl_xfs_getresblks \- query XFS summary counter information
> ^^^^^^^^^^^^^^^
>
> "query and set XFS free space reservation information"
DOH.
Yes, thanks for fixing that. :)
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
> > +.SH DESCRIPTION
>
> I wonder if starting with a "don't use" right here would be wise, something like:
>
> "Note: This is a[n] test/debug ioctl intended only for use by XFS filesystem developers."
I'm partial to "This is an extraordinary way to eat your data!" :)
But yes it should have a warning label for SET_RESBLKS.
--D
> > +Query or set the free space reservation information.
> > +These blocks are reserved by the filesystem as a final attempt to prevent
> > +metadata update failures due to insufficient space.
> > +Only the system administrator can call these ioctls, because overriding the
> > +defaults is extremely dangerous and should never be tried by anyone.
> > +.PP
> > +The reservation information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_resblks {
> > + __u64 resblks;
> > + __u64 resblks_avail;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I resblks
> > +is the number of blocks that the filesystem will try to maintain to prevent
> > +critical out of space situations.
> > +.PP
> > +.I resblks_avail
> > +is the number of reserved blocks remaining.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +The specified allocation group number is not valid for this filesystem.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B EPERM
> > +Caller does not have permission to call this ioctl.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man2/ioctl_xfs_setresblks.2 b/man/man2/ioctl_xfs_setresblks.2
> > new file mode 100644
> > index 00000000..209bc0a8
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_setresblks.2
> > @@ -0,0 +1 @@
> > +.so man2/ioctl_xfs_getresblks.2
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index ee3188ec..89975a3c 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -396,12 +396,21 @@ See
> > .BR ioctl_xfs_fscounts (2)
> > for more information.
> >
> > +.TP
> > +.nf
> > +.B XFS_IOC_GET_RESBLKS
> > +.fi
> > +.TP
> > +.B XFS_IOC_SET_RESBLKS
> > +See
> > +.BR ioctl_xfs_getresblks (2)
> > +for more information.
> > +Save yourself a lot of frustration and avoid these ioctls.
> > +
> > .PP
> > .nf
> > .B XFS_IOC_THAW
> > .B XFS_IOC_FREEZE
> > -.B XFS_IOC_GET_RESBLKS
> > -.B XFS_IOC_SET_RESBLKS
> > .B XFS_IOC_FSGROWFSDATA
> > .B XFS_IOC_FSGROWFSLOG
> > .fi
> > @@ -419,6 +428,7 @@ as they are not of general use to applications.
> > .BR ioctl_xfs_scrub_metadata (2),
> > .BR ioctl_xfs_fsinumbers (2),
> > .BR ioctl_xfs_fscounts (2),
> > +.BR ioctl_xfs_getresblks (2),
> > .BR fstatfs (2),
> > .BR statfs (2),
> > .BR xfs (5),
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 9/9] man: create a separate xfs shutdown ioctl manpage
2019-07-05 16:08 ` Eric Sandeen
@ 2019-07-05 17:13 ` Darrick J. Wong
2019-07-05 17:58 ` Eric Sandeen
0 siblings, 1 reply; 26+ messages in thread
From: Darrick J. Wong @ 2019-07-05 17:13 UTC (permalink / raw)
To: Eric Sandeen; +Cc: linux-xfs
On Fri, Jul 05, 2019 at 11:08:54AM -0500, Eric Sandeen wrote:
> On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> >
> > Create a separate manual page for the xfs shutdown ioctl so we can
> > document how it works.
> >
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> > man/man2/ioctl_xfs_goingdown.2 | 63 ++++++++++++++++++++++++++++++++++++++++
> > man/man3/xfsctl.3 | 7 ++++
> > 2 files changed, 70 insertions(+)
> > create mode 100644 man/man2/ioctl_xfs_goingdown.2
> >
> >
> > diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
> > new file mode 100644
> > index 00000000..bedc85c8
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_goingdown.2
> > @@ -0,0 +1,63 @@
> > +.\" Copyright (c) 2019, Oracle. All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GOINGDOWN 2 2019-06-17 "XFS"
> > +.SH NAME
> > +ioctl_xfs_goingdown \- shut down an XFS filesystem
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
> > +.SH DESCRIPTION
> > +Shuts down a live XFS filesystem.
> > +This is a software initiated hard shutdown and should be avoided whenever
> > +possible.
> > +After this call completes, the filesystem will be totally unusable and must be
> > +unmounted.
>
> That almost sounds permanently destructive. Perhaps:
>
> "... will be totally unusable until the filesystem has been unmounted and remounted."
>
> ?
Sounds good to me.
> > +
> > +.PP
> > +.I flags
> > +can be one of the following:
> > +.RS 0.4i
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_DEFAULT
> > +Flush all dirty data and in-core state to disk, flush pending transactions to
> > +the log, and shut down.
>
> What exactly do we mean by "in-core state" here? I'm not sure the average
> reader will know (I'm not sure I know)
Hm... really it's any dirty cached state, like ... unflushed inodes and
dquots, dirty file data, etc. I didn't want to commit to that level of
specificity though.
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
> > +Flush all pending transactions to the log and shut down, leaving all dirty
> > +data unwritten.
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
> > +Shut down immediately, without writing pending transactions or dirty data
> > +to disk.
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
>
> Hm crud, now I wonder about auditing all your stated error codes.
> EPERM, EFAULT, and EINVAL seem to be the only options for this
> particular call. Maybe that can be a 2nd cleanup, documenting
> an error code that won't happen is harmless...
<urk> Ok, I'll go do that. :)
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +The specified allocation group number is not valid for this filesystem.
This one definitely was copypasta error. :(
--D
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B EPERM
> > +Caller did not have permission to shut down the filesystem.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 077dd411..7e6588b8 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -365,6 +365,12 @@ See
> > for more information.
> > Save yourself a lot of frustration and avoid these ioctls.
> >
> > +.TP
> > +.B XFS_IOC_GOINGDOWN
> > +See
> > +.BR ioctl_xfs_goingdown (2)
> > +for more information.
> > +
> > .PP
> > .nf
> > .B XFS_IOC_THAW
> > @@ -388,6 +394,7 @@ as they are not of general use to applications.
> > .BR ioctl_xfs_fscounts (2),
> > .BR ioctl_xfs_getresblks (2),
> > .BR ioctl_xfs_getbmap (2),
> > +.BR ioctl_xfs_goingdown (2),
> > .BR fstatfs (2),
> > .BR statfs (2),
> > .BR xfs (5),
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP ioctl manpage
2019-07-05 15:53 ` Eric Sandeen
@ 2019-07-05 17:19 ` Darrick J. Wong
0 siblings, 0 replies; 26+ messages in thread
From: Darrick J. Wong @ 2019-07-05 17:19 UTC (permalink / raw)
To: Eric Sandeen; +Cc: linux-xfs
On Fri, Jul 05, 2019 at 10:53:05AM -0500, Eric Sandeen wrote:
> On 6/20/19 11:51 AM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> >
> > Create a separate manual page for the xfs BMAP ioctls so we can document
> > how they work.
>
> Same drill ... ;)
>
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> > man/man2/ioctl_xfs_getbmap.2 | 1
> > man/man2/ioctl_xfs_getbmapa.2 | 1
> > man/man2/ioctl_xfs_getbmapx.2 | 172 +++++++++++++++++++++++++++++++++++++++++
> > man/man3/xfsctl.3 | 61 ++-------------
> > 4 files changed, 184 insertions(+), 51 deletions(-)
> > create mode 100644 man/man2/ioctl_xfs_getbmap.2
> > create mode 100644 man/man2/ioctl_xfs_getbmapa.2
> > create mode 100644 man/man2/ioctl_xfs_getbmapx.2
> >
> >
> > diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
> > new file mode 100644
> > index 00000000..909402fc
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getbmap.2
> > @@ -0,0 +1 @@
> > +.so man2/ioctl_xfs_getbmapx.2
> > diff --git a/man/man2/ioctl_xfs_getbmapa.2 b/man/man2/ioctl_xfs_getbmapa.2
> > new file mode 100644
> > index 00000000..909402fc
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getbmapa.2
> > @@ -0,0 +1 @@
> > +.so man2/ioctl_xfs_getbmapx.2
> > diff --git a/man/man2/ioctl_xfs_getbmapx.2 b/man/man2/ioctl_xfs_getbmapx.2
> > new file mode 100644
> > index 00000000..cf21ca32
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getbmapx.2
> > @@ -0,0 +1,172 @@
> > +.\" Copyright (c) 2019, Oracle. All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GETBMAPX 2 2019-06-17 "XFS"
> > +.SH NAME
> > +ioctl_xfs_getbmapx \- query extent information for an open file
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
> > +.br
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
> > +.SH DESCRIPTION
> > +Get the block map for a segment of a file in an XFS file system.
> > +The mapping information is conveyed in a structure of the following form:
>
> "conveyed via an array of structures of the following form"
>
> (otherwise below we suddenly refer to "the array" which might leave
> some heads scratching)
SGTM.
> > +.PP
> > +.in +4n
> > +.nf
> > +struct getbmap {
> > + __s64 bmv_offset;
> > + __s64 bmv_block;
> > + __s64 bmv_length;
> > + __s32 bmv_count;
> > + __s32 bmv_entries;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +The
> > +.B XFS_IOC_GETBMAPX
> > +ioctl uses a larger version of that structure:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct getbmapx {
> > + __s64 bmv_offset;
> > + __s64 bmv_block;
> > + __s64 bmv_length;
> > + __s32 bmv_count;
> > + __s32 bmv_entries;
> > + __s32 bmv_iflags;
> > + __s32 bmv_oflags;
> > + __s32 bmv_unused1;
> > + __s32 bmv_unused2;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +All sizes and offsets in the structure are in units of 512 bytes.
> > +.PP
> > +The first structure in the array is a header and the remaining structures in
> > +the array contain block map information on return.
> > +The header controls iterative calls to the command and should be filled out as
> > +follows:
> > +.TP
> > +.I bmv_offset
> > +The file offset of the area of interest in the file.
> > +.TP
> > +.I bmv_length
> > +The length of the area of interest in the file.
> > +If this value is set to -1, the length of the interesting area is the rest of
> > +the file.
> > +.TP
> > +.I bmv_count
> > +The length of the array, including this header.
>
> "The number of elements in the array, including this header. The minimum value is 2."
Yes!! having just tripped over this 2 days ago. :)
> > +.TP
> > +.I bmv_entries
> > +The number of entries actually filled in by the call.
> > +This does not need to be filled out before the call.
>
> I also wonder if we should say something about how to know when iterative
> calls are done. Perhaps:
>
> "This value may be zero if no extents were found in the requested
> range, or if iterated calls have reached the end of the requested
> range"
Ok.
> > +.TP
> > +.I bmv_iflags
> > +For the
> > +.B XFS_IOC_GETBMAPX
> > +function, this is a bitmask containing a combination of the following flags:
> > +.RS 0.4i
> > +.TP
> > +.B BMV_IF_ATTRFORK
> > +Return information about the extended attribute fork.
> > +.TP
> > +.B BMV_IF_PREALLOC
> > +Return information about unwritten pre-allocated segments.
> > +.TP
> > +.B BMV_IF_DELALLOC
> > +Return information about delayed allocation reservation segments.
> > +.TP
> > +.B BMV_IF_NO_HOLES
> > +Do not return information about holes.
> > +.RE
> > +.PD 1
> > +.PP
> > +The other
> > +.I bmv_*
> > +fields in the header are ignored.
> > +.PP
> > +On return from a call, the header is updated so that the command can be
> > +reused to obtain more information without re-initializing the structures.
>
> Perhaps:
>
> "On successful return from a call, the offset and length values in the header
> are updated so that the command can be reused to obtain more information."
Yes, that is much clearer.
>
> > +The remainder of the array will be filled out by the call as follows:
>
> "The remaining elements of the array will be filled out ..."
SGTM.
> > +
> > +.TP
> > +.I bmv_offset
> > +File offset of segment.
> > +.TP
> > +.I bmv_block
> > +Physical starting block of segment.
> > +If this is -1, then the segment is a hole.
> > +.TP
> > +.I bmv_length
> > +Length of segment.
> > +.TP
> > +.I bmv_oflags
> > +The
> > +.B XFS_IOC_GETBMAPX
> > +function will fill this field with a combination of the following flags:
> > +.RS 0.4i
> > +.TP
> > +.B BMV_OF_PREALLOC
> > +The segment is an unwritten pre-allocation.
> > +.TP
> > +.B BMV_OF_DELALLOC
> > +The segment is a delayed allocation reservation.
> > +.TP
> > +.B BMV_OF_LAST
> > +This segment is the last in the file.
> > +.TP
> > +.B BMV_OF_SHARED
> > +This segment shares blocks with other files.
> > +.RE
> > +.PD 1
> > +.PP
> > +The other
> > +.I bmv_*
> > +fields are ignored in the array of outputted records.
>
> "are unused in the array of output records."
Ok. :)
> -Eric
>
> > +.PP
> > +The
> > +.B XFS_IOC_GETBMAPA
> > +command is identical to
> > +.B XFS_IOC_GETBMAP
> > +except that information about the attribute fork of the file is returned.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 89975a3c..077dd411 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -144,59 +144,17 @@ See
> > .BR ioctl_xfs_fsgetxattr (2)
> > for more information.
> >
> > -.TP
> > -.B XFS_IOC_GETBMAP
> > -Get the block map for a segment of a file in an XFS file system.
> > -The final argument points to an arry of variables of type
> > -.BR "struct getbmap" .
> > -All sizes and offsets in the structure are in units of 512 bytes.
> > -The structure fields include:
> > -.B bmv_offset
> > -(file offset of segment),
> > -.B bmv_block
> > -(starting block of segment),
> > -.B bmv_length
> > -(length of segment),
> > -.B bmv_count
> > -(number of array entries, including the first), and
> > -.B bmv_entries
> > -(number of entries filled in).
> > -The first structure in the array is a header, and the remaining
> > -structures in the array contain block map information on return.
> > -The header controls iterative calls to the
> > +.PP
> > +.nf
> > .B XFS_IOC_GETBMAP
> > -command.
> > -The caller fills in the
> > -.B bmv_offset
> > -and
> > -.B bmv_length
> > -fields of the header to indicate the area of interest in the file,
> > -and fills in the
> > -.B bmv_count
> > -field to indicate the length of the array.
> > -If the
> > -.B bmv_length
> > -value is set to \-1 then the length of the interesting area is the rest
> > -of the file.
> > -On return from a call, the header is updated so that the command can be
> > -reused to obtain more information, without re-initializing the structures.
> > -Also on return, the
> > -.B bmv_entries
> > -field of the header is set to the number of array entries actually filled in.
> > -The non-header structures will be filled in with
> > -.BR bmv_offset ,
> > -.BR bmv_block ,
> > -and
> > -.BR bmv_length .
> > -If a region of the file has no blocks (is a hole in the file) then the
> > -.B bmv_block
> > -field is set to \-1.
> > -
> > -.TP
> > .B XFS_IOC_GETBMAPA
> > -Identical to
> > -.B XFS_IOC_GETBMAP
> > -except that information about the attribute fork of the file is returned.
> > +.fi
> > +.PD 0
> > +.TP
> > +.B XFS_IOC_GETBMAPX
> > +See
> > +.BR ioctl_getbmap (2)
> > +for more information.
> >
> > .PP
> > .B XFS_IOC_RESVSP
> > @@ -429,6 +387,7 @@ as they are not of general use to applications.
> > .BR ioctl_xfs_fsinumbers (2),
> > .BR ioctl_xfs_fscounts (2),
> > .BR ioctl_xfs_getresblks (2),
> > +.BR ioctl_xfs_getbmap (2),
> > .BR fstatfs (2),
> > .BR statfs (2),
> > .BR xfs (5),
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 9/9] man: create a separate xfs shutdown ioctl manpage
2019-07-05 17:13 ` Darrick J. Wong
@ 2019-07-05 17:58 ` Eric Sandeen
0 siblings, 0 replies; 26+ messages in thread
From: Eric Sandeen @ 2019-07-05 17:58 UTC (permalink / raw)
To: Darrick J. Wong; +Cc: linux-xfs
On 7/5/19 12:13 PM, Darrick J. Wong wrote:
> On Fri, Jul 05, 2019 at 11:08:54AM -0500, Eric Sandeen wrote:
>> On 6/20/19 11:51 AM, Darrick J. Wong wrote:
>>> From: Darrick J. Wong <darrick.wong@oracle.com>
...
>>> +
>>> +.PP
>>> +.I flags
>>> +can be one of the following:
>>> +.RS 0.4i
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_DEFAULT
>>> +Flush all dirty data and in-core state to disk, flush pending transactions to
>>> +the log, and shut down.
>>
>> What exactly do we mean by "in-core state" here? I'm not sure the average
>> reader will know (I'm not sure I know)
>
> Hm... really it's any dirty cached state, like ... unflushed inodes and
> dquots, dirty file data, etc. I didn't want to commit to that level of
> specificity though.
"Flush all dirty data and metadata to disk, flush pending transactions
to the log, and shut down." ?
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
>>> +Flush all pending transactions to the log and shut down, leaving all dirty
>>> +data unwritten.
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
>>> +Shut down immediately, without writing pending transactions or dirty data
>>> +to disk.
>>> +
>>> +.SH RETURN VALUE
>>> +On error, \-1 is returned, and
>>> +.I errno
>>> +is set to indicate the error.
>>> +.PP
>>> +.SH ERRORS
>>> +Error codes can be one of, but are not limited to, the following:
>>
>> Hm crud, now I wonder about auditing all your stated error codes.
>> EPERM, EFAULT, and EINVAL seem to be the only options for this
>> particular call. Maybe that can be a 2nd cleanup, documenting
>> an error code that won't happen is harmless...
>
> <urk> Ok, I'll go do that. :)
>
>>> +.TP
>>> +.B EFSBADCRC
>>> +Metadata checksum validation failed while performing the query.
>>> +.TP
>>> +.B EFSCORRUPTED
>>> +Metadata corruption was encountered while performing the query.
>>> +.TP
>>> +.B EINVAL
>>> +The specified allocation group number is not valid for this filesystem.
>
> This one definitely was copypasta error. :(
Oh oopsies. Ok that's worth fixing ....
-Eric
^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2019-07-05 17:58 UTC | newest]
Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-20 16:50 [PATCH v2 0/9] xfsprogs: document the ioctls scrub uses Darrick J. Wong
2019-06-20 16:50 ` [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage Darrick J. Wong
2019-07-03 22:48 ` Eric Sandeen
2019-07-04 2:04 ` Darrick J. Wong
2019-07-04 3:43 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 2/9] man: create a separate GEOMETRY " Darrick J. Wong
2019-07-05 15:01 ` Eric Sandeen
2019-07-05 16:25 ` Darrick J. Wong
2019-06-20 16:51 ` [PATCH 3/9] man: create a separate FSBULKSTAT " Darrick J. Wong
2019-07-05 16:22 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3 Darrick J. Wong
2019-07-05 16:23 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 5/9] man: create a separate INUMBERS ioctl manpage Darrick J. Wong
2019-07-05 15:16 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 6/9] man: create a separate FSCOUNTS " Darrick J. Wong
2019-07-05 15:15 ` Eric Sandeen
2019-06-20 16:51 ` [PATCH 7/9] man: create a separate RESBLKS " Darrick J. Wong
2019-07-05 16:02 ` Eric Sandeen
2019-07-05 17:09 ` Darrick J. Wong
2019-06-20 16:51 ` [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP " Darrick J. Wong
2019-07-05 15:53 ` Eric Sandeen
2019-07-05 17:19 ` Darrick J. Wong
2019-06-20 16:51 ` [PATCH 9/9] man: create a separate xfs shutdown " Darrick J. Wong
2019-07-05 16:08 ` Eric Sandeen
2019-07-05 17:13 ` Darrick J. Wong
2019-07-05 17:58 ` Eric Sandeen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.