.TH XFSCTL 3
.SH NAME
xfsctl \- control XFS filesystems and individual files
.SH C SYNOPSIS
.B #include <xfs/xfs.h>
.HP
.BI "int\ xfsctl(const char *" path ", int " fd ", int " cmd ", void *" ptr );
.PP
.BI "int platform_test_xfs_fd(int " fd );
.br
.BI "int platform_test_xfs_path(const char *" path );
.SH 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
.BR xfsctl ()
calls to ensure the target path and file descriptor (both must
be supplied) do indeed represent a file from an XFS filesystem.
The
.BR statfs (2)
and
.BR 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
.BR platform_test_xfs_fd ()
and
.BR platform_test_xfs_path ()
provide a platform-independent mechanism.
.SS File Operations
In order to effect an operation on an individual file, the pathname
and descriptor arguments passed to
.B xfsctl
identifies the file being operated on.
The final argument described below refers to the final argument of
.BR xfsctl .
All of the data structures and macros mentioned below are defined in the
.RI < xfs/xfs_fs.h >
header file.
.PP
.B XFS_IOC_ALLOCSP
.br
.B XFS_IOC_ALLOCSP64
.br
.B XFS_IOC_FREESP
.PD 0
.TP
.B XFS_IOC_FREESP64
Alter storage space associated with a section of the ordinary
file specified.  The section is specified by a variable of type
.BR xfs_flock64_t ,
pointed to by the final argument.
The data type
.B xfs_flock64_t
contains the following members:
.B l_whence
is 0, 1, or 2 to indicate that the relative offset
.B l_start
will be measured from the start of the file, the current position, or
the end of the file, respectively (i.e.,
.B l_start
is the offset from the position specified in
.BR 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
.B l_len
field is currently ignored, and should be set to zero.

.BR XFS_IOC_ALLOCSP ,
.BR XFS_IOC_ALLOCSP64 ,
.B XFS_IOC_FREESP
and
.B XFS_IOC_FREESP64
operations are all identical.

.TP
.B 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
.B bs_dmevmask
and
.B bs_dmstate
fields of the bulkstat structure.
The data referred to by the final argument is a
.BR "struct fsdmidata" .
This structure's members are
.B fsd_dmevmask
and
.BR fsd_dmstate .
The di_dmevmask
field is set to the value in
.BR fsd_dmevmask .
The di_dmstate field is set to the value in
.BR 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.

.TP
.B 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
.BR "struct dioattr" ,
which contains the following members:
.B d_mem
is the memory alignment requirement of the user's data buffer.
.B 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.
.B 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
.BR read (2)
or
.BR 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.

.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
.B XFS_IOC_FSGETXATTR
except that the
.B fsx_nextents
field contains the number of attribute extents in the file.

.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.

.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
.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.

.PP
.B XFS_IOC_RESVSP
.TP
.B 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
.B 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
.BR xfs_info (8)
reports unwritten=1, then the filesystem was made to flag unwritten extents.

.PP
.B XFS_IOC_UNRESVSP
.TP
.B 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
.B 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.

.TP
.B 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
.B 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
.BR xfs_info (8)
reports unwritten=1, then the filesystem was made to flag unwritten extents.

.\" .TP
.\" .B XFS_IOC_GETBIOSIZE
.\" This command gets information about the preferred buffered I/O
.\" size used by the system when performing buffered I/O (e.g.
.\" standard Unix non-direct I/O) to and from the file.
.\" The information is passed back in a structure of type
.\" .B "struct biosize"
.\" pointed to by the final argument.
.\" biosize lengths are expressed in log base 2.
.\" That is if the value is 14, then the true size is 2^14 (2 raised to
.\" the 14th power).
.\" The
.\" .B biosz_read
.\" field will contain the current value used by the system when reading
.\" from the file.
.\" Except at the end-of-file, the system will read from the file in
.\" multiples of this length.
.\" The
.\" .B biosz_write
.\" field will contain the current value used by the system when writing
.\" to the file.
.\" Except at the end-of-file, the system will write to the file in
.\" multiples of this length.
.\" The
.\" .B dfl_biosz_read
.\" and
.\" .B dfl_biosz_write
.\" will be set to the system default values for the opened file.
.\" The
.\" .B biosz_flags
.\" field will be set to 1 if the current read or write value has been
.\" explicitly set.
.\"
.\" .TP
.\" .B XFS_IOC_SETBIOSIZE
.\" This command sets information about the preferred buffered I/O size
.\" used by the system when performing buffered I/O (e.g. standard Unix
.\" non-direct I/O) to and from the file.
.\" The information is passed in a structure of type
.\" .B "struct biosize"
.\" pointed to by the final argument.
.\" Using smaller preferred I/O sizes can result in performance
.\" improvements if the file is typically accessed using small
.\" synchronous I/Os or if only a small amount of the file is accessed
.\" using small random I/Os, resulting in little or no use of the
.\" additional data read in near the random I/Os.
.\"
.\" To explicitly set the preferred I/O sizes, the
.\" .B biosz_flags
.\" field should be set to zero and the
.\" .B biosz_read
.\" and
.\" .B biosz_write
.\" fields should be set to the log base 2 of the desired read and
.\" write lengths, respectively (e.g. 13 for 8K bytes, 14 for 16K
.\" bytes, 15 for 32K bytes, etc.).  Valid values are 13-16
.\" inclusive for machines with a 4K byte pagesize and 14-16 for
.\" machines with a 16K byte pagesize.  The specified read and
.\" write values must also result in lengths that are greater than
.\" or equal to the filesystem block size.
.\" The
.\" .B dfl_biosz_read
.\" and
.\" .B dfl_biosz_write
.\" fields are ignored.
.\"
.\" If biosizes have already been explicitly set due to a prior use
.\" of
.\" .BR XFS_IOC_SETBIOSIZE ,
.\" and the requested sizes are larger than the
.\" existing sizes, the
.\" .I xfsctl
.\" call will return successfully and the
.\" system will use the smaller of the two sizes.  However, if
.\" .B biosz_flags
.\" is set to 1, the system will use the new values
.\" regardless of whether the new sizes are larger or smaller than the old.
.\"
.\" To reset the biosize values to the defaults for the filesystem
.\" that the file resides in, the
.\" .B biosz_flags
.\" field should be set to 2.
.\" The remainder of the fields will be ignored in that case.
.\"
.\" Changes made by
.\" .B XFS_IOC_SETBIOSIZE
.\" are transient.
.\" The sizes are reset to the default values once the reference count on the
.\" file drops to zero (e.g. all open file descriptors to that file
.\" have been closed).
.\" See
.\" .I mount(8)
.\" for details on how to set the
.\" default biosize values for a filesystem.

.PP
.nf
.B XFS_IOC_PATH_TO_HANDLE
.B XFS_IOC_PATH_TO_FSHANDLE
.B XFS_IOC_FD_TO_HANDLE
.B XFS_IOC_OPEN_BY_HANDLE
.B XFS_IOC_READLINK_BY_HANDLE
.B XFS_IOC_ATTR_LIST_BY_HANDLE
.B XFS_IOC_ATTR_MULTI_BY_HANDLE
.fi
.PD 0
.TP
.B XFS_IOC_FSSETDM_BY_HANDLE
These are all interfaces that are used to implement various
.I libhandle
functions (see
.BR open_by_handle (3)).
They are all subject to change and should not be called directly
by applications.

.SS Filesystem Operations
In order to effect one of the following operations, the pathname
and descriptor arguments passed to
.BR xfsctl ()
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.

.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.

.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
.B XFS_IOC_FSGROWFSRT
.fi
.TP
.B XFS_IOC_FSCOUNTS
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 xfs_fsop_geom_t .
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.

.SH SEE ALSO
.BR fstatfs (2),
.BR statfs (2),
.BR xfs (5),
.BR xfs_info (8).