From patchwork Thu Jun 20 16:50:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007473 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 1FA4913AF for ; Thu, 20 Jun 2019 16:51:04 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0D14228306 for ; Thu, 20 Jun 2019 16:51:04 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0159928895; Thu, 20 Jun 2019 16:51:03 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DD50D287FA for ; Thu, 20 Jun 2019 16:51:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726661AbfFTQvC (ORCPT ); Thu, 20 Jun 2019 12:51:02 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:43744 "EHLO userp2120.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvC (ORCPT ); Thu, 20 Jun 2019 12:51:02 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnlY3078166; Thu, 20 Jun 2019 16:50:57 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=oIR1Q7aKIr3ysKahMCe9BVP/Dwr/xzAYUBwzywKYsFw=; b=HcDkd75EshyzUp/8dJ9F9GJMYvEcAOFYY/TRMkfNQb2lu7K2CFEtwGBCeLiPRar+HCJL ehOU+qWOTi6KFsH73nTJJj9Ev8F06UF2mpI3Y8L2RaA6qWCbpblXSjBM00wzOal4rvpu CI8RRJOzHk8OzNEB4yRd8aH+ivIwzB2+1jVnu4V/Rp7hDk+SSo1ErOmVA9UC6SiP9Tbh hJ3loOrK+SSAm2Gp3cjgnjrevip1+y3Ne6KHKKpn7DYh2NTLOSUXxVeC8nTkEBuwnzq8 V7IIBu+ziQq2dC+MZwulyR/xaTX6Fxv3nmaAXgwNkjZ0qtBviswE2YpxTduSsvPjTL4A YA== Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2120.oracle.com with ESMTP id 2t7809j8qm-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:50:57 +0000 Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnerE057749; Thu, 20 Jun 2019 16:50:57 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userp3030.oracle.com with ESMTP id 2t77ynqpq6-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:50:56 +0000 Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGouZB025037; Thu, 20 Jun 2019 16:50:56 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:50:55 -0700 Subject: [PATCH 1/9] man: create a separate GETXATTR/SETXATTR ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:50:54 -0700 Message-ID: <156104945493.1174403.4930583691574810947.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong 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 --- 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 +.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), From patchwork Thu Jun 20 16:51:01 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007475 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 80C0414BB for ; Thu, 20 Jun 2019 16:51:08 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6FD8E28894 for ; Thu, 20 Jun 2019 16:51:08 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 63AC6288CB; Thu, 20 Jun 2019 16:51:08 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A1A7C288BF for ; Thu, 20 Jun 2019 16:51:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726551AbfFTQvH (ORCPT ); Thu, 20 Jun 2019 12:51:07 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:43882 "EHLO userp2130.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvG (ORCPT ); Thu, 20 Jun 2019 12:51:06 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnASU069692; Thu, 20 Jun 2019 16:51:04 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=f7t5hcjYdSiEMZgfcb/7RQKzeE9hYbaEq3Owa4qvuEE=; b=jIFToaPl4AKim0SR0RHLrtevuyhagt6nOD0XQVb9qNmwXjqxVc8aTfB40aZ+FOBs0y9M Ywdcuy9UVlkSj9E8YY+2Kuye/jgZ/bN8Z6074T7i7DPviRqlzht9FPRwJJwa/hWDMMX4 kSm0VdJxCd/vq6vQEm7QN9nELdiVN3EeK61TiHwg9WBnRzKVX5lTse7OPzLIdI2g04VV WUm9KSiOiABqual4CJkWvyULJhfn/kumi5toTX0aORI/c+OVGUnVD722UKBwAmHfoSH1 OZ/aiVhmF8zJeO6YIdxc/qlIFP66s5/TjuYcmtH/HPjqSPLQUGzZ30vYkpSKXAjZYRB3 Mw== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2130.oracle.com with ESMTP id 2t7809j9t9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:04 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnGA6182143; Thu, 20 Jun 2019 16:51:03 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3030.oracle.com with ESMTP id 2t7rdx934k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:03 +0000 Received: from abhmp0010.oracle.com (abhmp0010.oracle.com [141.146.116.16]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGp23l025080; Thu, 20 Jun 2019 16:51:02 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:02 -0700 Subject: [PATCH 2/9] man: create a separate GEOMETRY ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:01 -0700 Message-ID: <156104946127.1174403.3334245262659435539.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=2 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=2 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Break out the xfs geometry ioctl into a separate manpage so that we can document how it works. Signed-off-by: Darrick J. Wong --- 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 +.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), From patchwork Thu Jun 20 16:51:07 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007477 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id F154613AF for ; Thu, 20 Jun 2019 16:51:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DD15328864 for ; Thu, 20 Jun 2019 16:51:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C780B2887B; Thu, 20 Jun 2019 16:51:14 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 09E0328779 for ; Thu, 20 Jun 2019 16:51:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726654AbfFTQvN (ORCPT ); Thu, 20 Jun 2019 12:51:13 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:43966 "EHLO userp2120.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvN (ORCPT ); Thu, 20 Jun 2019 12:51:13 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnENX077940; Thu, 20 Jun 2019 16:51:11 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=NSDugIKi7JN5+HxLqVRP8OMqByQ8TG5PijClERl6YYw=; b=iTHl7+2ejLyUuerDQwLUW0FW3RtU7u3+0Bxy11fJ1ncYBuW8HKUFAcV992H9qK0GMI7C DNNj8HHcikoXFMEwikuNd7SXaiYPFCMHDweESYumYuy8OMeHHTfWEDKSUtrJ9N5lvCMf ywAvjqlok1gRtd0ZYjA7fGD2qoBJzwQeFzn6jjStA0Qtw4cwkqCe/KeN5mCBvPoPrYgH dBIwUw5ZK5v+GNIygicmfKv1ev5VA9DwqnomCRUseTFugkjxPzE77ba6+aOZcW2LRMJO s78BDEaV1nlkgKxy6EhF9dSrWEyaNdQ0MA82oTaOAqPhAV1rNrX0FGV6XCA1J/YBAJP/ yw== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2120.oracle.com with ESMTP id 2t7809j8sa-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:10 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGoYB6057429; Thu, 20 Jun 2019 16:51:10 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3020.oracle.com with ESMTP id 2t77ypfs69-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:09 +0000 Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGp8ot025146; Thu, 20 Jun 2019 16:51:09 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:08 -0700 Subject: [PATCH 3/9] man: create a separate FSBULKSTAT ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:07 -0700 Message-ID: <156104946746.1174403.13696786407524686878.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Break out the xfs bulkstat ioctl into a separate manpage so that we can document how it works. Signed-off-by: Darrick J. Wong Reviewed-by: Eric Sandeen --- 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 +.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), From patchwork Thu Jun 20 16:51:13 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007479 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id ABFEC14DB for ; Thu, 20 Jun 2019 16:51:19 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9CD06288BD for ; Thu, 20 Jun 2019 16:51:19 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 918C4288C4; Thu, 20 Jun 2019 16:51:19 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B71A3288BD for ; Thu, 20 Jun 2019 16:51:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726675AbfFTQvS (ORCPT ); Thu, 20 Jun 2019 12:51:18 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:44014 "EHLO userp2120.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvS (ORCPT ); Thu, 20 Jun 2019 12:51:18 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnGgE077957; Thu, 20 Jun 2019 16:51:16 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=qyfCHTsbncxlfUfF7s2eYhK+6IagBY4eqr2PrMcqCkQ=; b=Sgi7bg/83DASxG0cBBIxUOIhZsBPztdpA3DeBBuPu321siNMIvYXiMX9CJ5nu11p4WPs GRf3XVsUm2+WmQPBTHIQwQubBfpQWn1IPI/f0O6zl5cdhcyQtbmIOqN8ufZflZ8ifyDG a3RoOaiU7tnIf72P2oFwcBjyI1ih4Qw7Knunpl3ttULoRDwui320IuKcyR3ISFM0pIlc 6IBQCTRy6VQhIVSBvnx6L4+QcNUPLjISort97P+PIMoB3tS1/VMTWjIfY2yRsdWGgPh+ adewZOY3RQzLiuPczArVxyhzOyk5kQoWzhXsxxkZBfBiVGgJr85U3exojT1jPKUAX63g nQ== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2120.oracle.com with ESMTP id 2t7809j8sj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:16 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGoWvw057346; Thu, 20 Jun 2019 16:51:15 GMT Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserp3020.oracle.com with ESMTP id 2t77ypfs7g-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:15 +0000 Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x5KGpEgr020508; Thu, 20 Jun 2019 16:51:15 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:14 -0700 Subject: [PATCH 4/9] man: link to the SCRUB_METADATA ioctl manpage from xfsctl.3 From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:13 -0700 Message-ID: <156104947386.1174403.3374265373047115552.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=879 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=923 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Link to the scrub ioctl documentation from xfsctl. Signed-off-by: Darrick J. Wong Reviewed-by: Eric Sandeen --- 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), From patchwork Thu Jun 20 16:51:20 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007481 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 3B7CB13AF for ; Thu, 20 Jun 2019 16:51:26 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2A775287FA for ; Thu, 20 Jun 2019 16:51:26 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1F519288BD; Thu, 20 Jun 2019 16:51:26 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 04776287FA for ; Thu, 20 Jun 2019 16:51:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726814AbfFTQvY (ORCPT ); Thu, 20 Jun 2019 12:51:24 -0400 Received: from aserp2120.oracle.com ([141.146.126.78]:55554 "EHLO aserp2120.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvY (ORCPT ); Thu, 20 Jun 2019 12:51:24 -0400 Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnAm9173680; Thu, 20 Jun 2019 16:51:22 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=mrbe2OAf7UBdh93di6o5TCqwjKfaKSB84Awh+KEJj18=; b=bHqucO5atXW4hr+OeL2Q0hjxwJkDkPat1ox2OL/X7Mlp7Buinhiuv7GkJi5htWYYyDZ1 JPoqbdRiZgqZ4ocWqDy14ZdjZ9i8hueQAwBCvfBBIWa8wBZo/IlT0fPDVGQllh6MvEvc 3fuPKaHe43knAyEik56ntoHio3pxEU8O5W5frKnciPWbuvOzdk0vhCiXZL5oDpszyIhT L07g0R3krWBKmqk7JmEw1ekA0wIX7LYC5Ql+VtF3GGUelFEL1y63p7PtxwVZzAkginxC 8J67NdL0JSRbSYPeVF7RLUEAKtOyaGDSK4NJzvZyljKmVj7DMeZo59r09+bDuA/qJFz2 SA== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by aserp2120.oracle.com with ESMTP id 2t7809j7d3-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:22 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGoVtA057208; Thu, 20 Jun 2019 16:51:21 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3020.oracle.com with ESMTP id 2t77ypfs8r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:21 +0000 Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGpLQk021787; Thu, 20 Jun 2019 16:51:21 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:21 -0700 Subject: [PATCH 5/9] man: create a separate INUMBERS ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:20 -0700 Message-ID: <156104948000.1174403.11692931049872468663.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Create a separate manual page for the xfs INUMBERS ioctl so we can document how it works. Signed-off-by: Darrick J. Wong Reviewed-by: Eric Sandeen --- 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 +.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), From patchwork Thu Jun 20 16:51:26 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007483 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 1FF5F13AF for ; Thu, 20 Jun 2019 16:51:36 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 10C0E287FA for ; Thu, 20 Jun 2019 16:51:36 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0584E288BF; Thu, 20 Jun 2019 16:51:36 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8CB02287FA for ; Thu, 20 Jun 2019 16:51:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726934AbfFTQvf (ORCPT ); Thu, 20 Jun 2019 12:51:35 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:44272 "EHLO userp2130.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726530AbfFTQvf (ORCPT ); Thu, 20 Jun 2019 12:51:35 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnAOU069698; Thu, 20 Jun 2019 16:51:33 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=YgXlZArZKS/T0BCQGFr6HUR8R5l5m5wkofr8sEOWKZw=; b=11PIwLU7UWLO4TwSj/NvZbceTNG2r7DjZ/HH2uHqOwbA0B8T5AQ4q16h+JwJlWfhu3nY UCaQqZ8dj5l/lSG7Tv5b8ReJaMqm4NJlK2lUf/QD0cIFmVi07rf3+xR8vJ51Z6cEf7L0 KyqG3w6EZyk8PN1sJr1KRy4d37ZkLlm+Z9d8vn6zr6N7EBVgpFKTnt0L0RuGhbcS4LeL hJ0/KnVDICHNhzaxcqMtLn6PG8RjkEg1lVmelIErp9JRJsW2yW5LNBMqZZaxT0OZCNY6 EzyoDofu4yxHFps+DKJ7IYFr7H0Pcei67e5ULK5gwtzzzjFeAd9Pc5RrV/DHMGGi/Ygs DQ== Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2130.oracle.com with ESMTP id 2t7809j9vm-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:32 +0000 Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnkbJ058056; Thu, 20 Jun 2019 16:51:32 GMT Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userp3030.oracle.com with ESMTP id 2t77ynqq07-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:32 +0000 Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x5KGpV9h013596; Thu, 20 Jun 2019 16:51:31 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:31 -0700 Subject: [PATCH 6/9] man: create a separate FSCOUNTS ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:26 -0700 Message-ID: <156104948638.1174403.13393187882783073949.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=2 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=2 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Create a separate manual page for the xfs FSCOUNTS ioctl so we can document how it works. Signed-off-by: Darrick J. Wong Reviewed-by: Eric Sandeen --- 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 +.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), From patchwork Thu Jun 20 16:51:36 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007489 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 1EEEA13AF for ; Thu, 20 Jun 2019 16:51:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0F222288D0 for ; Thu, 20 Jun 2019 16:51:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0377628884; Thu, 20 Jun 2019 16:51:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8759F288BD for ; Thu, 20 Jun 2019 16:51:43 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726940AbfFTQvn (ORCPT ); Thu, 20 Jun 2019 12:51:43 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:44334 "EHLO userp2120.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726881AbfFTQvm (ORCPT ); Thu, 20 Jun 2019 12:51:42 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnGgH077957; Thu, 20 Jun 2019 16:51:40 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=femXacRjv1UTknVNm0dfB2Tlm2P3vC7vtfgbQ9dUzPQ=; b=j5pt1NAG1wiALE/OwVAoiyf4KI7Fw31gA6vM11ROUw09mdn3mR6dWTj1ED6+VAXzLql7 xqs/f105iShNgpvO0DVEcb4QHNE7iTVZlSyw9qmbKODnSXzBwvjL53VmI+0TnEb3sp2l 9Sd8Z8H3x0yF/o5NurDQU1ugP/id5QE/iqmqGFsRKdq0gUdqOLZnBHvG38Y4wTjjnV9B sgClBS8/YJc3PDVazeoJlFdrgeVh0ZlouNoYgAqhK8id+IEgbcS83fblQNI+Fjp6C+7M HiLsYdtNiNl77+3vVNJ+ySVuAPO4TEu+QjT6VBPeGZQWPPYsn3wsvAh2B+UG2Tt11F7L 8w== Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2120.oracle.com with ESMTP id 2t7809j8uc-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:40 +0000 Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGpe9r063614; Thu, 20 Jun 2019 16:51:40 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userp3030.oracle.com with ESMTP id 2t77ynqq1r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:40 +0000 Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGpbsw025417; Thu, 20 Jun 2019 16:51:38 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 16:51:37 +0000 Subject: [PATCH 7/9] man: create a separate RESBLKS ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:36 -0700 Message-ID: <156104949681.1174403.3533354992259074908.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=789 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=845 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Create a separate manual page for the xfs RESBLKS ioctls so we can document how it works. Signed-off-by: Darrick J. Wong --- 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 +.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), From patchwork Thu Jun 20 16:51:43 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007491 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id F0C431398 for ; Thu, 20 Jun 2019 16:51:48 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DF7E32860C for ; Thu, 20 Jun 2019 16:51:48 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D35332887B; Thu, 20 Jun 2019 16:51:48 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2646B2860C for ; Thu, 20 Jun 2019 16:51:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731567AbfFTQvr (ORCPT ); Thu, 20 Jun 2019 12:51:47 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:44550 "EHLO userp2130.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726881AbfFTQvr (ORCPT ); Thu, 20 Jun 2019 12:51:47 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnN5M070048; Thu, 20 Jun 2019 16:51:45 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=1FzCm0CE54XLB8C4DZ5Gxh+7oA/e17fpcYIHfd55Uyg=; b=4D8k8kdbTh46MbdMJ+81wLhaOoUB3H/dR1fhkK9Gh/pHabq+U2gRrWhseSf4N/4+yWa0 QKVB5F5vUfH7iU8V22n1vMr787QcXwkc1pHhwJEKOGfK98JqhdZMfmzp6osj+QjyjW0j RSl+VTBWUR5jCUWqUbdNbru6n6wYSSAvN2VNHDAx8/oRStzf32bvk5IGioGT8VRw9p45 HXCi0Co2c9n1p0Z/qN/U7ka2w0oRw1q4YMjOTCiLKXiU5iEwq2qp1qI69C+aDgqWlWTD F8yvhOkFng8xDHlOm6lVzizsegv7FdvkCHbme00riEvCMywPggJSp/ictj3F3rT3OXr4 hA== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2130.oracle.com with ESMTP id 2t7809j9ws-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:45 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGoWsl057249; Thu, 20 Jun 2019 16:51:44 GMT Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserp3020.oracle.com with ESMTP id 2t77ypfsfb-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:44 +0000 Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x5KGpimT020837; Thu, 20 Jun 2019 16:51:44 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:43 -0700 Subject: [PATCH 8/9] man: create a separate GETBMAPX/GETBMAPA/GETBMAP ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:43 -0700 Message-ID: <156104950296.1174403.15218317280608955242.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Create a separate manual page for the xfs BMAP ioctls so we can document how they work. Signed-off-by: Darrick J. Wong --- 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 +.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), From patchwork Thu Jun 20 16:51:49 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 11007493 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id ED55F13AF for ; Thu, 20 Jun 2019 16:51:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DD659287FA for ; Thu, 20 Jun 2019 16:51:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D1CEC28884; Thu, 20 Jun 2019 16:51:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6C096288CB for ; Thu, 20 Jun 2019 16:51:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726740AbfFTQvy (ORCPT ); Thu, 20 Jun 2019 12:51:54 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:44668 "EHLO userp2130.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726661AbfFTQvx (ORCPT ); Thu, 20 Jun 2019 12:51:53 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGnGaZ069756; Thu, 20 Jun 2019 16:51:51 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=subject : from : to : cc : date : message-id : in-reply-to : references : mime-version : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=mofIEMK4vNTkcKxCjRoez17o39I3+bIzNe25rfxM00g=; b=oVMjYY6B/ccFk7QqeS68YCuj4YbJFPpQ4vwSD4CcNIKTOOxCdyt1gdAobqZJzoVP31J5 F8ghngUYtF0n48Uy7Ii0tpuZIE7sHt+QHQ1BI4juJokxgSeZ7aWTrGM8VZ4p5TJY7laq 9Nfs7U+L/06IKVKxvThkDHMdIVRn6I9YMrFoPlht00J/m++2YQshcj8I1Cj1Hs+kZfnE mYnQcxfBQrSKMAo69WhYJFTBmed3DsOtA8OtXhbzUDj4wS6bbPfA9H4P0jCjOT+f5boN YqbVA3DEg02psJgD+XcjMByuV35XxlGJKvZLBWiqIEV3MT35LcDZIadqyzkK+0XgoHAR Xw== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2130.oracle.com with ESMTP id 2t7809j9x9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:51 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5KGpIoD187377; Thu, 20 Jun 2019 16:51:50 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3030.oracle.com with ESMTP id 2t7rdx93g3-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 20 Jun 2019 16:51:50 +0000 Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x5KGpo6i021996; Thu, 20 Jun 2019 16:51:50 GMT Received: from localhost (/67.169.218.210) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 20 Jun 2019 09:51:50 -0700 Subject: [PATCH 9/9] man: create a separate xfs shutdown ioctl manpage From: "Darrick J. Wong" To: sandeen@sandeen.net, darrick.wong@oracle.com Cc: linux-xfs@vger.kernel.org Date: Thu, 20 Jun 2019 09:51:49 -0700 Message-ID: <156104950912.1174403.4990641877651635072.stgit@magnolia> In-Reply-To: <156104944877.1174403.14568482035189263260.stgit@magnolia> References: <156104944877.1174403.14568482035189263260.stgit@magnolia> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9294 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1906200122 Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Darrick J. Wong Create a separate manual page for the xfs shutdown ioctl so we can document how it works. Signed-off-by: Darrick J. Wong --- 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 +.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),