xfsctl(3) — Linux manual page


XFSCTL(3)                 Library Functions Manual                 XFSCTL(3)

NAME         top

       xfsctl - control XFS filesystems and individual files

C SYNOPSIS         top

       #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         top

       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.

              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

              XFS_IOC_FREESP64 operations are all identical.

              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.

              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

              See ioctl_xfs_fsgetxattr(2) for more information.

              See ioctl_getbmap(2) for more information.

              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.

              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.

              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.

              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

   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.

              See ioctl_xfs_fsinumbers(2) for more information.

              See ioctl_xfs_fsop_geometry(2) for more information.

              See ioctl_xfs_ag_geometry(2) for more information.

              See ioctl_xfs_fsbulkstat(2) for more information.

              See ioctl_xfs_scrub_metadata(2) for more information.

              See ioctl_xfs_fscounts(2) for more information.

              See ioctl_xfs_getresblks(2) for more information.  Save
              yourself a lot of frustration and avoid these ioctls.

              See ioctl_xfs_goingdown(2) for more information.

              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.

SEE ALSO         top

       ioctl_xfs_fsgetxattr(2), ioctl_xfs_fsop_geometry(2),
       ioctl_xfs_fsbulkstat(2), ioctl_xfs_scrub_metadata(2),
       ioctl_xfs_fsinumbers(2), ioctl_xfs_fscounts(2),
       ioctl_xfs_getresblks(2), ioctl_xfs_getbmap(2),
       ioctl_xfs_goingdown(2), fstatfs(2), statfs(2), xfs(5), xfs_info(8).

COLOPHON         top

       This page is part of the xfsprogs (utilities for XFS filesystems)
       project.  Information about the project can be found at 
       ⟨http://xfs.org/⟩.  If you have a bug report for this manual page,
       send it to linux-xfs@vger.kernel.org.  This page was obtained from
       the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
       2020-08-13.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-07-24.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to


Pages that refer to this page: creat(2)open(2)openat(2)attr_list_by_handle(3)attr_multi_by_handle(3)fd_to_handle(3)free_handle(3)fssetdm_by_handle(3)getparentpaths_by_handle(3)getparents_by_handle(3)handle(3)handle_to_fshandle(3)open_by_handle(3)path_to_fshandle(3)path_to_handle(3)readlink_by_handle(3)projects(5)projid(5)xfs(5)xfs_io(8)