1XFSCTL(3) Library Functions Manual XFSCTL(3)
2
6 xfsctl - control XFS filesystems and individual files
7
9 #include <xfs/xfs.h>
10 int xfsctl(const char *path, int fd, int cmd, void *ptr);
12 int platform_test_xfs_fd(int fd);
14 int platform_test_xfs_path(const char *path);
15
17 Some functionality specific to the XFS filesystem is accessible to ap‐
18 plications through platform-specific system call interfaces. These op‐
19 erations can be divided into two sections - operations that operate on
20 individual files, and operations that operate on the filesystem itself.
21 Care should be taken when issuing xfsctl() calls to ensure the target
22 path and file descriptor (both must be supplied) do indeed represent a
23 file from an XFS filesystem. The statfs(2) and fstatfs(2) system calls
24 can be used to determine whether or not an arbitrary path or file de‐
25 scriptor belong to an XFS filesystem. These are not portable however,
26 so the routines platform_test_xfs_fd() and platform_test_xfs_path()
27 provide a platform-independent mechanism.
28 File Operations
30 In order to effect an operation on an individual file, the pathname and
31 descriptor arguments passed to xfsctl identifies the file being oper‐
32 ated on. The final argument described below refers to the final argu‐
33 ment of xfsctl. All of the data structures and macros mentioned below
34 are defined in the <xfs/xfs_fs.h> header file.
35 XFS_IOC_ALLOCSP
37 XFS_IOC_ALLOCSP64
38 XFS_IOC_FREESP
39 XFS_IOC_FREESP64
40 Alter storage space associated with a section of the ordinary
41 file specified. The section is specified by a variable of type
42 xfs_flock64_t, pointed to by the final argument. The data type
43 xfs_flock64_t contains the following members: l_whence is 0, 1,
44 or 2 to indicate that the relative offset l_start will be mea‐
45 sured from the start of the file, the current position, or the
46 end of the file, respectively (i.e., l_start is the offset from
47 the position specified in l_whence). If the offset specified is
48 before the current end of file, any data previously written into
49 this section is no longer accessible. If the offset specified
50 is beyond the current end of file, the file is grown and filled
51 with zeroes. The l_len field is currently ignored, and should
52 be set to zero.
53 XFS_IOC_ALLOCSP, XFS_IOC_ALLOCSP64, XFS_IOC_FREESP and
55 XFS_IOC_FREESP64 operations are all identical.
56 These ioctls are no longer supported as of Linux 5.17.
58 XFS_IOC_FSSETDM
60 Set the di_dmevmask and di_dmstate fields in an XFS on-disk in‐
61 ode. The only legitimate values for these fields are those pre‐
62 viously returned in the bs_dmevmask and bs_dmstate fields of the
63 bulkstat structure. The data referred to by the final argument
64 is a struct fsdmidata. This structure's members are fsd_dmev‐
65 mask and fsd_dmstate. The di_dmevmask field is set to the value
66 in fsd_dmevmask. The di_dmstate field is set to the value in
67 fsd_dmstate. This command is restricted to root or to processes
68 with device management capabilities. Its sole purpose is to al‐
69 low backup and restore programs to restore the aforementioned
70 critical on-disk inode fields. This ioctl is not supported as
71 of Linux 5.5.
72 XFS_IOC_DIOINFO
74 Get information required to perform direct I/O on the specified
75 file descriptor. Direct I/O is performed directly to and from a
76 user's data buffer. Since the kernel's buffer cache is no
77 longer between the two, the user's data buffer must conform to
78 the same type of constraints as required for accessing a raw
79 disk partition. The final argument points to a variable of type
80 struct dioattr, which contains the following members: d_mem is
81 the memory alignment requirement of the user's data buffer.
82 d_miniosz specifies block size, minimum I/O request size, and
83 I/O alignment. The size of all I/O requests must be a multiple
84 of this amount and the value of the seek pointer at the time of
85 the I/O request must also be an integer multiple of this amount.
86 d_maxiosz is the maximum I/O request size which can be performed
87 on the file descriptor. If an I/O request does not meet these
88 constraints, the read(2) or write(2) will fail with EINVAL. All
89 I/O requests are kept consistent with any data brought into the
90 cache with an access through a non-direct I/O file descriptor.
91 XFS_IOC_FSGETXATTR
93 XFS_IOC_FSGETXATTRA
94 XFS_IOC_FSSETXATTR
95 See ioctl_xfs_fsgetxattr(2) for more information.
96 XFS_IOC_GETBMAP
98 XFS_IOC_GETBMAPA
99 XFS_IOC_GETBMAPX
100 See ioctl_getbmap(2) for more information.
101 XFS_IOC_RESVSP
103 XFS_IOC_RESVSP64
104 This command is used to allocate space to a file. A range of
105 bytes is specified using a pointer to a variable of type
106 xfs_flock64_t in the final argument. The blocks are allocated,
107 but not zeroed, and the file size does not change. If the XFS
108 filesystem is configured to flag unwritten file extents, perfor‐
109 mance will be negatively affected when writing to preallocated
110 space, since extra filesystem transactions are required to con‐
111 vert extent flags on the range of the file written. If
112 xfs_info(8) reports unwritten=1, then the filesystem was made to
113 flag unwritten extents.
114 XFS_IOC_UNRESVSP
116 XFS_IOC_UNRESVSP64
117 This command is used to free space from a file. A range of
118 bytes is specified using a pointer to a variable of type
119 xfs_flock64_t in the final argument. Partial filesystem blocks
120 are zeroed, and whole filesystem blocks are removed from the
121 file. The file size does not change.
122 XFS_IOC_ZERO_RANGE
124 This command is used to convert a range of a file to zeros with‐
125 out issuing data IO. A range of bytes is specified using a
126 pointer to a variable of type xfs_flock64_t in the final argu‐
127 ment. Blocks are preallocated for regions that span holes in
128 the file, and the entire range is converted to unwritten ex‐
129 tents. This operation is a fast method of overwriting any from
130 the range specified with zeros without removing any blocks or
131 having to write zeros to disk. Any subsequent read in the given
132 range will return zeros until new data is written. This func‐
133 tionality requires filesystems to support unwritten extents. If
134 xfs_info(8) reports unwritten=1, then the filesystem was made to
135 flag unwritten extents.
136 XFS_IOC_PATH_TO_HANDLE
139 XFS_IOC_PATH_TO_FSHANDLE
140 XFS_IOC_FD_TO_HANDLE
141 XFS_IOC_OPEN_BY_HANDLE
142 XFS_IOC_READLINK_BY_HANDLE
143 XFS_IOC_ATTR_LIST_BY_HANDLE
144 XFS_IOC_ATTR_MULTI_BY_HANDLE
145 XFS_IOC_FSSETDM_BY_HANDLE
146 These are all interfaces that are used to implement various lib‐
147 handle functions (see open_by_handle(3)). They are all subject
148 to change and should not be called directly by applications.
149 XFS_IOC_FSSETDM_BY_HANDLE is not supported as of Linux 5.5.
150 Filesystem Operations
152 In order to effect one of the following operations, the pathname and
153 descriptor arguments passed to xfsctl() can be any open file in the XFS
154 filesystem in question.
155 XFS_IOC_FSINUMBERS
157 See ioctl_xfs_fsinumbers(2) for more information.
158 XFS_IOC_FSGEOMETRY
160 See ioctl_xfs_fsgeometry(2) for more information.
161 XFS_IOC_AG_GEOMETRY
163 See ioctl_xfs_ag_geometry(2) for more information.
164 XFS_IOC_FSBULKSTAT or XFS_IOC_FSBULKSTAT_SINGLE
166 See ioctl_xfs_fsbulkstat(2) for more information.
167 XFS_IOC_SCRUB_METADATA
169 See ioctl_xfs_scrub_metadata(2) for more information.
170 XFS_IOC_FSCOUNTS
172 See ioctl_xfs_fscounts(2) for more information.
173 XFS_IOC_GET_RESBLKS
175 XFS_IOC_SET_RESBLKS
176 See ioctl_xfs_getresblks(2) for more information. Save yourself
177 a lot of frustration and avoid these ioctls.
178 XFS_IOC_GOINGDOWN
180 See ioctl_xfs_goingdown(2) for more information.
181 XFS_IOC_THAW
183 XFS_IOC_FREEZE
184 XFS_IOC_FSGROWFSDATA
185 XFS_IOC_FSGROWFSLOG
186 XFS_IOC_FSGROWFSRT
187 These interfaces are used to implement various filesystem inter‐
188 nal operations on XFS filesystems. The remainder of these oper‐
189 ations will not be described further as they are not of general
190 use to applications.
191
193 ioctl_xfs_fsgetxattr(2), ioctl_xfs_fsgeometry(2), ioctl_xfs_fsbulk‐
194 stat(2), ioctl_xfs_scrub_metadata(2), ioctl_xfs_fsinumbers(2),
195 ioctl_xfs_fscounts(2), ioctl_xfs_getresblks(2), ioctl_xfs_getbmap(2),
196 ioctl_xfs_goingdown(2), fstatfs(2), statfs(2), xfs(5), xfs_info(8).
197 XFSCTL(3)