XFSCTL(3) XFSCTL(3)
NAME
xfsctl - control XFS filesystems and individual files
C SYNOPSIS
#include <xfs/libxfs.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(1,n) descriptor (both must be supplied) do indeed rep-
resent a file(1,n) 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(1,n) descriptor belong to an XFS filesystem. These are not portable
however, so the routines platform_test_xfs_fd and plat-
form_test_xfs_path provide a platform-independent mechanism.
FILE OPERATIONS
In order to effect an operation on an individual file(1,n), the pathname and
descriptor arguments passed to xfsctl identifies the file(1,n) being oper-
ated on. The final argument described below refers to the final argu-
ment of xfsctl. All of the data structures and macros mentioned below
are defined in(1,8) the <xfs/xfs_fs.h> header file.
XFS_IOC_FREESP
XFS_IOC_FREESP64
XFS_IOC_ALLOCSP
XFS_IOC_ALLOCSP64
Alter storage space associated with a section of the ordinary
file(1,n) 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 mea-
sured from the start of the file(1,n), the current position, or the
end of the file(1,n), respectively. l_start is the offset from the
position specified in(1,8) l_whence. l_len is the size of the sec-
tion. An l_len value of zero frees up to the end of the file(1,n);
in(1,8) this case, the end of file(1,n) (i.e., file(1,n) size) is set(7,n,1 builtins) to the
beginning of the section freed. Any data previously written
into this section is no longer accessible. If the section spec-
ified is beyond the current end of file(1,n), the file(1,n) is grown and
filled with zeroes. The l_len field is currently ignored, and
should be set(7,n,1 builtins) to zero.
XFS_IOC_FREESP and XFS_IOC_FREESP64 are identical, as are the
XFS_IOC_ALLOCSP and XFS_IOC_ALLOCSP64 operations.
XFS_IOC_FSSETDM
Set the di_dmevmask and di_dmstate fields in(1,8) an XFS on-disk
inode. The only legitimate values for these fields are those
previously returned in(1,8) the bs_dmevmask and bs_dmstate fields of
the bulkstat structure. The data referred to by the final argu-
ment is a struct fsdmidata. This structure's members are
fsd_dmevmask and fsd_dmstate. The di_dmevmask field is set(7,n,1 builtins) to
the value in(1,8) fsd_dmevmask. The di_dmstate field is set(7,n,1 builtins) to the
value in(1,8) 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 aforemen-
tioned critical on-disk inode fields.
XFS_IOC_DIOINFO
Get information required to perform direct I/O on the specified
file(1,n) 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(3x,7,8,3x cbreak)
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(1,2,n) 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(1,n) descriptor. If an I/O request does not meet these
constraints, the read(2,n,1 builtins)(2) or write(1,2)(2) will fail with EINVAL. All
I/O requests are kept consistent with any data brought into the
cache with an access(2,5) through a non-direct I/O file(1,n) descriptor.
XFS_IOC_FSGETXATTR
Get additional attributes associated with files in(1,8) XFS file(1,n) sys-
tems. The final argument points to a variable of type struct
fsxattr, whose fields include: fsx_xflags (extended flag bits),
fsx_extsize (nominal extent size in(1,8) file(1,n) system blocks),
fsx_nextents (number of data extents in(1,8) the file(1,n)). A fsx_ext-
size value returned indicates that a preferred extent size was
previously set(7,n,1 builtins) on the file(1,n), a fsx_extsize of zero indicates that
the defaults for that filesystem will be used. Currently the
meaningful bits for the fsx_xflags field are:
Bit 0 (0x1) - XFS_XFLAG_REALTIME
The file(1,n) is a realtime file.
Bit 1 (0x2) - XFS_XFLAG_PREALLOC
The file(1,n) has preallocated space.
Bit 3 (0x8) - XFS_XFLAG_IMMUTABLE
The file(1,n) is immutable - it cannot be modified, deleted
or renamed, no link(1,2) can be created to this file(1,n) and no
data can be written to the file. Only the superuser
or a process possessing the CAP_LINUX_IMMUTABLE capa-
bility can set(7,n,1 builtins) or clear(1,3x,3x clrtobot) this flag.
Bit 4 (0x10) - XFS_XFLAG_APPEND
The file(1,n) is append-only - it can only be open(2,3,n) in(1,8)
append mode for writing. Only the superuser or a
process possessing the CAP_LINUX_IMMUTABLE capability
can set(7,n,1 builtins) or clear(1,3x,3x clrtobot) this flag.
Bit 5 (0x20) - XFS_XFLAG_SYNC
All writes to the file(1,n) are synchronous.
Bit 6 (0x40) - XFS_XFLAG_NOATIME
When the file(1,n) is accessed, its atime record is not
modified.
Bit 7 (0x80) - XFS_XFLAG_NODUMP
The file(1,n) should be skipped by backup utilities.
Bit 8 (0x100) - XFS_XFLAG_RTINHERIT
Realtime inheritance bit - new files created in(1,8) the
directory will be automatically realtime, and new
directories created in(1,8) the directory will inherit the
inheritance bit.
Bit 9 (0x200) - XFS_XFLAG_PROJINHERIT
Project inheritance bit - new files and directories
created in(1,8) the directory will inherit the parents
project ID. New directories also inherit the project
inheritance bit.
Bit 10 (0x400) - XFS_XFLAG_NOSYMLINKS
Can only be set(7,n,1 builtins) on a directory and disallows creation
of symbolic links in(1,8) that directory.
Bit 31 (0x80000000) - XFS_XFLAG_HASATTR
The file(1,n) has extended attributes associated with it.
XFS_IOC_FSGETXATTRA
Identical to XFS_IOC_FSGETXATTR except that the fsx_nextents
field contains the number of attribute extents in(1,8) the file.
XFS_IOC_FSSETXATTR
Set additional attributes associated with files in(1,8) XFS file(1,n) sys-
tems. The final argument points to a variable of type struct
fsxattr, but only the following fields are used in(1,8) this call:
fsx_xflags and fsx_extsize. The fsx_xflags realtime file(1,n) bit,
and the file(1,n)'s extent size, may be changed only when the file(1,n) is
empty.
XFS_IOC_GETBMAP
Get the block map for a segment of a file(1,n) in(1,8) an XFS file(1,n) system.
The final argument points to an arry of variables of type struct
getbmap. All sizes and offsets in(1,8) the structure are in(1,8) units(1,7) of
512 bytes. The structure fields include: bmv_offset (file(1,n) off-
set(7,n,1 builtins) of segment), bmv_block (starting block of segment),
bmv_length (length of segment), bmv_count (number of array
entries, including the first), and bmv_entries (number of
entries filled in(1,8)). The first structure in(1,8) the array is a
header, and the remaining structures in(1,8) the array contain block
map information on return. The header controls iterative calls
to the XFS_IOC_GETBMAP command. The caller fills in(1,8) the
bmv_offset and bmv_length fields of the header to indicate the
area of interest in(1,8) the file(1,n), and fills in(1,8) the bmv_count field
to indicate the length of the array. If the bmv_length value is
set(7,n,1 builtins) 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 bmv_entries
field of the header is set(7,n,1 builtins) to the number of array entries actu-
ally filled in. The non-header structures will be filled in(1,8)
with bmv_offset, bmv_block, and bmv_length. If a region of the
file(1,n) has no blocks (is a hole in(1,8) the file(1,n)) then the bmv_block
field is set(7,n,1 builtins) to -1.
XFS_IOC_GETBMAPA
Identical to XFS_IOC_GETBMAP except that information about the
attribute fork of the file(1,n) is returned.
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(1,8) the final argument. The blocks are allocated,
but not zeroed, and the file(1,n) size does not change. If the XFS
filesystem is configured to flag unwritten file(1,n) extents, perfor-
mance will be negatively affected when writing to preallocated
space, since extra filesystem transactions are required to con-
vert extent flags on the range of the file(1,n) 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(1,8) the final argument. Partial filesystem blocks
are zeroed, and whole filesystem blocks are removed from the
file. The file(1,n) size does not change.
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 lib-
handle functions (see open_by_handle(3)). They are all subject
to change and should not be called directly by applications.
FILESYSTEM OPERATIONS
In order to effect one of the following operations, the pathname and
descriptor arguments passed to xfsctl can be any open(2,3,n) file(1,n) in(1,8) the XFS
filesystem in(1,8) question.
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 itera-
tively, to obtain the entire set(7,n,1 builtins) of inodes. The information is
passed in(1,8) and out via a structure of type xfs_fsop_bulkreq_t
pointed to by the final argument. lastip is a pointer to a
variable containing the last inode number returned, initially it
should be zero. icount is the size of the array of structures
specified by ubuffer. ubuffer is the address of an array of
structures, of type xfs_inogrp_t. This structure has the fol-
lowing elements: xi_startino (starting inode number), xi_alloc-
count (count of bits set(7,n,1 builtins) in(1,8) xi_allocmask), and xi_allocmask
(mask of allocated inodes in(1,8) this group). The bitmask is 64
bits long, and the least significant bit corresponds to inode
xi_startino. Each bit is set(7,n,1 builtins) if(3,n) the corresponding inode is in(1,8)
use. ocount is a pointer to a count of returned values, filled
in(1,8) by the call. An output ocount value of zero means that the
inode table has been exhausted.
XFS_IOC_FSBULKSTAT
This interface is used to extract inode information (stat(1,2) infor-
mation) "in(1,8) bulk" from a filesystem. It is intended to be
called iteratively, to obtain information about the entire set(7,n,1 builtins)
of inodes in(1,8) a filesystem. The information is passed in(1,8) and out
via a structure of type xfs_fsop_bulkreq_t pointed to by the
final argument. lastip is a pointer to a variable containing
the last inode number returned, initially it should be zero.
icount indicates the size of the array of structures specified
by ubuffer. ubuffer is the address of an array of structures of
type xfs_bstat_t. Many of the elements in(1,8) the structure are the
same as for the stat(1,2) structure. The structure has the following
elements: bs_ino (inode number), bs_mode (type and mode),
bs_nlink (number of links), bs_uid (user id), bs_gid (group id),
bs_rdev (device value), bs_blksize (block size of the filesys-
tem), bs_size (file(1,n) size in(1,8) bytes), bs_atime (access(2,5) time(1,2,n)),
bs_mtime (modify time(1,2,n)), bs_ctime (inode change time(1,2,n)), bs_blocks
(number of blocks used by the file(1,n)), bs_xflags (extended flags),
bs_extsize (extent size), bs_extents (number of extents), bs_gen
(generation count), bs_projid (project id), bs_dmevmask (DMIG
event mask), bs_dmstate (DMIG state information), and bs_aex-
tents (attribute extent count). ocount is a pointer to a count
of returned values, filled in(1,8) by the call. An output ocount
value of zero means that the inode table has been exhausted.
XFS_IOC_FSBULKSTAT_SINGLE
This interface is a variant of the XFS_IOC_FSBULKSTAT interface,
used to obtain information about a single inode. for an open(2,3,n)
file(1,n) in(1,8) the filesystem of interest. The same structure is used
to pass information in(1,8) and out of the kernel, except no output
count parameter is used (should be initialized to zero). An
error(8,n) is returned if(3,n) the inode number is invalid.
XFS_IOC_THAW
XFS_IOC_FREEZE
XFS_IOC_GET_RESBLKS
XFS_IOC_SET_RESBLKS
XFS_IOC_FSGROWFSDATA
XFS_IOC_FSGROWFSLOG
XFS_IOC_FSGROWFSRT
XFS_IOC_FSCOUNTS
These interfaces are used to implement various filesystem inter-
nal operations on XFS filesystems. For XFS_IOC_FSGEOMETRY (get
filesystem mkfs time(1,2,n) information), the output structure is of
type xfs_fsop_geom_t. For XFS_FS_COUNTS (get filesystem dynamic
global information), the output structure is of type
xfs_fsop_counts_t. The remainder of these operations will not
be described further as they are not of general use to applica-
tions.
SEE ALSO
fstatfs(2), statfs(2), xfs(5), xfs_info(8).
XFSCTL(3)