# xfsctl

## NAME



           xfsctl - control XFS filesystems and individual files
    


## C SYNOPSIS



           **#include <xfs/xfs.h>**
    
           **int xfsctl(const char ***_path_**, int** _fd_**, int** _cmd_**, void ***_ptr_**);**
    
           **int platform_test_xfs_fd(int** _fd_**);**
           **int platform_test_xfs_path(const char ***_path_**);**
    


## DESCRIPTION



           Some functionality specific to the XFS filesystem is accessible to
           applications through platform-specific system call interfaces.
           These operations can be divided into two sections - operations
           that operate on individual files, and operations that operate on
           the filesystem itself. Care should be taken when issuing **xfsctl**()
           calls to ensure the target path and file descriptor (both must be
           supplied) do indeed represent a file from an XFS filesystem.  The
           statfs(2) and fstatfs(2) system calls can be used to determine
           whether or not an arbitrary path or file descriptor belong to an
           XFS filesystem.  These are not portable however, so the routines
           **platform_test_xfs_fd**() and **platform_test_xfs_path**() provide a
           platform-independent mechanism.
    
       **File Operations**
           In order to effect an operation on an individual file, the
           pathname and descriptor arguments passed to **xfsctl** identifies the
           file being operated on.  The final argument described below refers
           to the final argument of **xfsctl**.  All of the data structures and
           macros mentioned below are defined in the <_xfs/xfs_fs.h_ > header
           file.
    
           **XFS_IOC_ALLOCSP**
           **XFS_IOC_ALLOCSP64**
           **XFS_IOC_FREESP**
           **XFS_IOC_FREESP64**
                  Alter storage space associated with a section of the
                  ordinary file specified.  The section is specified by a
                  variable of type **xfs_flock64_t** , pointed to by the final
                  argument.  The data type **xfs_flock64_t** contains the
                  following members: **l_whence** is 0, 1, or 2 to indicate that
                  the relative offset **l_start** will be measured from the start
                  of the file, the current position, or the end of the file,
                  respectively (i.e., **l_start** is the offset from the position
                  specified in **l_whence**).  If the offset specified is before
                  the current end of file, any data previously written into
                  this section is no longer accessible.  If the offset
                  specified is beyond the current end of file, the file is
                  grown and filled with zeroes.  The **l_len** field is currently
                  ignored, and should be set to zero.
    
                  **XFS_IOC_ALLOCSP** , **XFS_IOC_ALLOCSP64** , **XFS_IOC_FREESP** and
                  **XFS_IOC_FREESP64** operations are all identical.
    
                  These ioctls are no longer supported as of Linux 5.17.
    
           **XFS_IOC_FSSETDM**
                  Set the di_dmevmask and di_dmstate fields in an XFS on-disk
                  inode.  The only legitimate values for these fields are
                  those previously returned in the **bs_dmevmask** and **bs_dmstate**
                  fields of the bulkstat structure.  The data referred to by
                  the final argument is a **struct fsdmidata**.  This structure's
                  members are **fsd_dmevmask** and **fsd_dmstate**.  The di_dmevmask
                  field is set to the value in **fsd_dmevmask**.  The di_dmstate
                  field is set to the value in **fsd_dmstate**.  This command is
                  restricted to root or to processes with device management
                  capabilities.  Its sole purpose is to allow backup and
                  restore programs to restore the aforementioned critical on-
                  disk inode fields.  This ioctl is not supported as of Linux
                  5.5.
    
           **XFS_IOC_DIOINFO**
                  Get information required to perform direct I/O on the
                  specified file descriptor.  Direct I/O is performed
                  directly to and from a user's data buffer.  Since the
                  kernel's buffer cache is no longer between the two, the
                  user's data buffer must conform to the same type of
                  constraints as required for accessing a raw disk partition.
                  The final argument points to a variable of type **struct**
                  **dioattr** , which contains the following members: **d_mem** is the
                  memory alignment requirement of the user's data buffer.
                  **d_miniosz** specifies block size, minimum I/O request size,
                  and I/O alignment.  The size of all I/O requests must be a
                  multiple of this amount and the value of the seek pointer
                  at the time of the I/O request must also be an integer
                  multiple of this amount.  **d_maxiosz** is the maximum I/O
                  request size which can be performed on the file descriptor.
                  If an I/O request does not meet these constraints, the
                  read(2) or write(2) 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.
    
           **XFS_IOC_FSGETXATTR**
           **XFS_IOC_FSGETXATTRA**
           **XFS_IOC_FSSETXATTR**
                  See ioctl_xfs_fsgetxattr(2) for more information.
    
           **XFS_IOC_GETBMAP**
           **XFS_IOC_GETBMAPA**
           **XFS_IOC_GETBMAPX**
                  See **ioctl_getbmap**(2) for more information.
    
           **XFS_IOC_RESVSP**
           **XFS_IOC_RESVSP64**
                  This command is used to allocate space to a file.  A range
                  of bytes is specified using a pointer to a variable of type
                  **xfs_flock64_t** in the final argument.  The blocks are
                  allocated, but not zeroed, and the file size does not
                  change.  If the XFS filesystem is configured to flag
                  unwritten file extents, performance will be negatively
                  affected when writing to preallocated space, since extra
                  filesystem transactions are required to convert extent
                  flags on the range of the file written.  If xfs_info(8)
                  reports unwritten=1, then the filesystem was made to flag
                  unwritten extents.
    
           **XFS_IOC_UNRESVSP**
           **XFS_IOC_UNRESVSP64**
                  This command is used to free space from a file.  A range of
                  bytes is specified using a pointer to a variable of type
                  **xfs_flock64_t** in the final argument.  Partial filesystem
                  blocks are zeroed, and whole filesystem blocks are removed
                  from the file.  The file size does not change.
    
           **XFS_IOC_ZERO_RANGE**
                  This command is used to convert a range of a file to zeros
                  without issuing data IO.  A range of bytes is specified
                  using a pointer to a variable of type **xfs_flock64_t** in the
                  final argument.  Blocks are preallocated for regions that
                  span holes in the file, and the entire range is converted
                  to unwritten extents.  This operation is a fast method of
                  overwriting any from the range specified with zeros without
                  removing any blocks or having to write zeros to disk.  Any
                  subsequent read in the given range will return zeros until
                  new data is written.  This functionality requires
                  filesystems to support unwritten extents.  If xfs_info(8)
                  reports unwritten=1, then the filesystem was made to flag
                  unwritten extents.
    
           **XFS_IOC_PATH_TO_HANDLE**
           **XFS_IOC_PATH_TO_FSHANDLE**
           **XFS_IOC_FD_TO_HANDLE**
           **XFS_IOC_OPEN_BY_HANDLE**
           **XFS_IOC_READLINK_BY_HANDLE**
           **XFS_IOC_ATTR_LIST_BY_HANDLE**
           **XFS_IOC_ATTR_MULTI_BY_HANDLE**
           **XFS_IOC_FSSETDM_BY_HANDLE**
                  These are all interfaces that are used to implement various
                  _libhandle_ functions (see open_by_handle(3)).  They are all
                  subject to change and should not be called directly by
                  applications.  XFS_IOC_FSSETDM_BY_HANDLE is not supported
                  as of Linux 5.5.
    
       **Filesystem Operations**
           In order to effect one of the following operations, the pathname
           and descriptor arguments passed to **xfsctl**() can be any open file
           in the XFS filesystem in question.
    
           **XFS_IOC_FSINUMBERS**
                  See ioctl_xfs_fsinumbers(2) for more information.
    
           **XFS_IOC_FSGEOMETRY**
                  See ioctl_xfs_fsgeometry(2) for more information.
    
           **XFS_IOC_AG_GEOMETRY**
                  See ioctl_xfs_ag_geometry(2) for more information.
    
           **XFS_IOC_FSBULKSTAT** or **XFS_IOC_FSBULKSTAT_SINGLE**
                  See ioctl_xfs_fsbulkstat(2) for more information.
    
           **XFS_IOC_SCRUB_METADATA**
                  See ioctl_xfs_scrub_metadata(2) for more information.
    
           **XFS_IOC_FSCOUNTS**
                  See ioctl_xfs_fscounts(2) for more information.
    
           **XFS_IOC_GET_RESBLKS**
           **XFS_IOC_SET_RESBLKS**
                  See ioctl_xfs_getresblks(2) for more information.  Save
                  yourself a lot of frustration and avoid these ioctls.
    
           **XFS_IOC_GOINGDOWN**
                  See ioctl_xfs_goingdown(2) for more information.
    
           **XFS_IOC_THAW**
           **XFS_IOC_FREEZE**
           **XFS_IOC_FSGROWFSDATA**
           **XFS_IOC_FSGROWFSLOG**
           **XFS_IOC_FSGROWFSRT**
                  These interfaces are used to implement various filesystem
                  internal operations on XFS filesystems.  The remainder of
                  these operations will not be described further as they are
                  not of general use to applications.
    


* * *