# ioctl_xfs_bulkstat

## NAME



           ioctl_xfs_bulkstat - query information for a batch of XFS inodes
    


## SYNOPSIS



           **#include <xfs/xfs_fs.h>**
    
           **int ioctl(int** _fd_**, XFS_IOC_BULKSTAT, struct xfs_bulkstat_req ***_arg_**);**
    


## DESCRIPTION



           Query stat information for a group of XFS inodes.  This ioctl uses
           **struct xfs_bulkstat_req** to set up a bulk transfer from the kernel:
    
               struct xfs_bulkstat_req {
                    struct xfs_bulk_ireq    hdr;
                    struct xfs_bulkstat     bulkstat[];
               };
    
           See below for the **xfs_bulkstat** structure definition.
    
               struct xfs_bulk_ireq {
                    uint64_t                ino;
                    uint32_t                flags;
                    uint32_t                icount;
                    uint32_t                ocount;
                    uint32_t                agno;
                    uint64_t                reserved[5];
               };
    
           _hdr.ino_ should be set to the number of the first inode for which
           the caller wants information; or zero to start with the first
           inode in the filesystem; or a special value if
           **XFS_BULK_IREQ_SPECIAL** is set in the flags field.  Note that this
           is a different semantic than the **lastip** in the old **FSBULKSTAT**
           ioctl.  After the call, this value will be set to the number of
           the next inode for which information could supplied.  This sets up
           the next call for an iteration loop.
    
           If the **XFS_BULK_IREQ_SPECIAL** flag is set in the flags field, the
           _ino_ field is interpreted according to the following special
           values:
    
               **XFS_BULK_IREQ_SPECIAL_ROOT**
                      Return stat information for the root directory inode.
    
           _hdr.flags_ is a bit set of operational flags:
    
               **XFS_BULK_IREQ_AGNO**
                      If this is set, the call will only return results for
                      the allocation group (AG) set in **hdr.agno**.  If **hdr.ino**
                      is set to zero, results will be returned starting with
                      the first inode in the AG.  This flag may not be set at
                      the same time as the **XFS_BULK_IREQ_SPECIAL** flag.
    
               **XFS_BULK_IREQ_SPECIAL**
                      If this is set, results will be returned for only the
                      special inode specified in the **hdr.ino** field.  This
                      flag may not be set at the same time as the
                      **XFS_BULK_IREQ_AGNO** flag.
    
               **XFS_BULK_IREQ_NREXT64**
                      If this is set, data fork extent count is returned via
                      bs_extents64 field and 0 is assigned to bs_extents.
                      Otherwise, data fork extent count is returned via
                      bs_extents field and bs_extents64 is assigned a value
                      of 0. In the second case, bs_extents is set to (2^31 -
                      1) if data fork extent count is larger than 2^31. This
                      flag may be set independently of whether other flags
                      have been set.
    
               **XFS_BULK_IREQ_METADIR**
                      Return metadata directory tree inodes in the stat
                      output as well.  The only fields that will be populated
                      are _bs_ino_ , _bs_gen_ , _bs_mode_ , _bs_sick_ , and _bs_checked._
                      All other fields, notably _bs_blksize_ , will be zero.
    
           _hdr.icount_ is the maximum number of records to return.  This
           should be the size of the array that comes after the header.
    
           _hdr.ocount_ will be set to the number of records actually returned.
    
           _hdr.agno_ is the number of the allocation group (AG) for which we
           want results.  If the **XFS_BULK_IREQ_AGNO** flag is not set, this
           field is ignored.
    
           _hdr.reserved_ must be set to zero.
    
           _bulkstat_ is an array of **struct xfs_bulkstat** which is described
           below.  The array must have at least _icount_ elements.
    
               struct xfs_bulkstat {
                    uint64_t                bs_ino;
                    uint64_t                bs_size;
    
                    uint64_t                bs_blocks;
                    uint64_t                bs_xflags;
    
                    uint64_t                bs_atime;
                    uint64_t                bs_mtime;
    
                    uint64_t                bs_ctime;
                    uint64_t                bs_btime;
    
                    uint32_t                bs_gen;
                    uint32_t                bs_uid;
                    uint32_t                bs_gid;
                    uint32_t                bs_projectid;
    
                    uint32_t                bs_atime_nsec;
                    uint32_t                bs_mtime_nsec;
                    uint32_t                bs_ctime_nsec;
                    uint32_t                bs_btime_nsec;
    
                    uint32_t                bs_blksize;
                    uint32_t                bs_rdev;
                    uint32_t                bs_cowextsize_blks;
                    uint32_t                bs_extsize_blks;
    
                    uint32_t                bs_nlink;
                    uint32_t                bs_extents;
                    uint32_t                bs_aextents;
                    uint16_t                bs_version;
                    uint16_t                bs_forkoff;
    
                    uint16_t                bs_sick;
                    uint16_t                bs_checked;
                    uint16_t                bs_mode;
                    uint16_t                bs_pad2;
                    uint64_t                bs_extents64;
    
                    uint64_t                bs_pad[6];
               };
    
           _bs_ino_ is the inode number of this record.
    
           _bs_size_ is the size of the file, in bytes.
    
           _bs_blocks_ is the number of filesystem blocks allocated to this
           file, including metadata.
    
           _bs_xflags_ tell us what extended flags are set this inode.  These
           flags are the same values as those defined in the **XFS INODE FLAGS**
           section of the ioctl_xfs_fsgetxattr(2) manpage.
    
           _bs_atime_ is the last time this file was accessed, in seconds.
    
           _bs_mtime_ is the last time the contents of this file were modified,
           in seconds.
    
           _bs_ctime_ is the last time this inode record was modified, in
           seconds.
    
           _bs_btime_ is the time this inode record was created, in seconds.
    
           _bs_gen_ is the generation number of the inode record.
    
           _bs_uid_ is the user id.
    
           _bs_gid_ is the group id.
    
           _bs_projectid_ is the the project id.
    
           _bs_atime_nsec_ is the nanoseconds component of the last time this
           file was accessed.
    
           _bs_mtime_nsec_ is the nanoseconds component of the last time the
           contents of this file were modified.
    
           _bs_ctime_nsec_ is the nanoseconds component of the last time this
           inode record was modified.
    
           _bs_btime_nsec_ is the nanoseconds component of the time this inode
           record was created.
    
           _bs_blksize_ is the size of a data block for this file, in units of
           bytes.
    
           _bs_rdev_ is the encoded device id if this is a special file.
    
           _bs_cowextsize_blks_ is the Copy on Write extent size hint for this
           file, in units of data blocks.
    
           _bs_extsize_blks_ is the extent size hint for this file, in units of
           data blocks.
    
           _bs_nlink_ is the number of hard links to this inode.
    
           _bs_extents_ is the number of storage mappings associated with this
           file's data.
    
           _bs_aextents_ is the number of storage mappings associated with this
           file's extended attributes.
    
           _bs_version_ is the version of this data structure.  This will be
           set to _XFS_BULKSTAT_VERSION_V5_ by the kernel.
    
           _bs_forkoff_ is the offset of the attribute fork in the inode
           record, in bytes.
    
           The fields _bs_sick_ and _bs_checked_ indicate the relative health of
           various allocation group metadata.  Please see the section **XFS**
           **INODE METADATA HEALTH REPORTING** for more information.
    
           _bs_mode_ is the file type and mode.
    
           _bs_pad[7]_ is zeroed.
    


## RETURN VALUE



           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## XFS INODE METADATA HEALTH REPORTING



           The online filesystem checking utility scans inode metadata and
           records what it finds in the kernel incore state.  The following
           scheme is used for userspace to read the incore health status of
           an inode:
    
           • If a given sick flag is set in _bs_sick_ , then that piece of
             metadata has been observed to be damaged.  The same bit should
             be set in _bs_checked_.
    
           • If a given sick flag is set in _bs_checked_ but is not set in
             _bs_sick_ , then that piece of metadata has been checked and is not
             faulty.
    
           • If a given sick flag is not set in _bs_checked_ , then no
             conclusion can be made.
    
           The following flags apply to these fields:
    
               **XFS_BS_SICK_INODE**
                      The inode's record itself.
    
               **XFS_BS_SICK_BMBTD**
                      File data extent mappings.
    
               **XFS_BS_SICK_BMBTA**
                      Extended attribute extent mappings.
    
               **XFS_BS_SICK_BMBTC**
                      Copy on Write staging extent mappings.
    
               **XFS_BS_SICK_DIR**
                      Directory information.
    
               **XFS_BS_SICK_XATTR**
                      Extended attribute data.
    
               **XFS_BS_SICK_SYMLINK**
                      Symbolic link target.
    
               **XFS_BS_SICK_PARENT**
                      Parent pointers.
    
               **XFS_BS_SICK_DIRTREE**
                      Directory is the source of corruption in the directory
                      tree.
    


## ERRORS



           Error codes can be one of, but are not limited to, the following:
    
           **EFAULT** The kernel was not able to copy into the userspace buffer.
    
           **EFSBADCRC**
                  Metadata checksum validation failed while performing the
                  query.
    
           **EFSCORRUPTED**
                  Metadata corruption was encountered while performing the
                  query.
    
           **EINVAL** One of the arguments was not valid.
    
           **EIO** An I/O error was encountered while performing the query.
    
           **ENOMEM** There was insufficient memory to perform the query.
    


## CONFORMING TO



           This API is specific to XFS filesystem on the Linux kernel.
    


* * *