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
18 applications through platform-specific system call interfaces. These
19 operations can be divided into two sections - operations that operate
20 on individual files, and operations that operate on the filesystem
21 itself. Care should be taken when issuing xfsctl() calls to ensure the
22 target path and file descriptor (both must be supplied) do indeed rep‐
23 resent a file from an XFS filesystem. The statfs(2) and fstatfs(2)
24 system calls can be used to determine whether or not an arbitrary path
25 or file descriptor belong to an XFS filesystem. These are not portable
26 however, so the routines platform_test_xfs_fd() and plat‐
27 form_test_xfs_path() 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 XFS_IOC_FSSETDM
58 Set the di_dmevmask and di_dmstate fields in an XFS on-disk
59 inode. The only legitimate values for these fields are those
60 previously returned in the bs_dmevmask and bs_dmstate fields of
61 the bulkstat structure. The data referred to by the final argu‐
62 ment is a struct fsdmidata. This structure's members are
63 fsd_dmevmask and fsd_dmstate. The di_dmevmask field is set to
64 the value in fsd_dmevmask. The di_dmstate field is set to the
65 value in fsd_dmstate. This command is restricted to root or to
66 processes with device management capabilities. Its sole purpose
67 is to allow backup and restore programs to restore the aforemen‐
68 tioned critical on-disk inode fields.
69 XFS_IOC_DIOINFO
71 Get information required to perform direct I/O on the specified
72 file descriptor. Direct I/O is performed directly to and from a
73 user's data buffer. Since the kernel's buffer cache is no
74 longer between the two, the user's data buffer must conform to
75 the same type of constraints as required for accessing a raw
76 disk partition. The final argument points to a variable of type
77 struct dioattr, which contains the following members: d_mem is
78 the memory alignment requirement of the user's data buffer.
79 d_miniosz specifies block size, minimum I/O request size, and
80 I/O alignment. The size of all I/O requests must be a multiple
81 of this amount and the value of the seek pointer at the time of
82 the I/O request must also be an integer multiple of this amount.
83 d_maxiosz is the maximum I/O request size which can be performed
84 on the file descriptor. If an I/O request does not meet these
85 constraints, the read(2) or write(2) will fail with EINVAL. All
86 I/O requests are kept consistent with any data brought into the
87 cache with an access through a non-direct I/O file descriptor.
88 XFS_IOC_FSGETXATTR
90 Get additional attributes associated with files in XFS file sys‐
91 tems. The final argument points to a variable of type struct
92 fsxattr, whose fields include: fsx_xflags (extended flag bits),
93 fsx_extsize (nominal extent size in file system blocks),
94 fsx_nextents (number of data extents in the file). A fsx_ext‐
95 size value returned indicates that a preferred extent size was
96 previously set on the file, a fsx_extsize of zero indicates that
97 the defaults for that filesystem will be used. A fsx_cowextsize
98 value returned indicates that a preferred copy on write extent
99 size was previously set on the file, whereas a fsx_cowextsize of
100 zero indicates that the defaults for that filesystem will be
101 used. The current default for fsx_cowextsize is 128 blocks.
102 Currently the meaningful bits for the fsx_xflags field are:
103 Bit 0 (0x1) - XFS_XFLAG_REALTIME
104 The file is a realtime file.
105 Bit 1 (0x2) - XFS_XFLAG_PREALLOC
106 The file has preallocated space.
107 Bit 3 (0x8) - XFS_XFLAG_IMMUTABLE
108 The file is immutable - it cannot be modified, deleted
109 or renamed, no link can be created to this file and no
110 data can be written to the file. Only the superuser
111 or a process possessing the CAP_LINUX_IMMUTABLE capa‐
112 bility can set or clear this flag.
113 Bit 4 (0x10) - XFS_XFLAG_APPEND
114 The file is append-only - it can only be open in
115 append mode for writing. Only the superuser or a
116 process possessing the CAP_LINUX_IMMUTABLE capability
117 can set or clear this flag.
118 Bit 5 (0x20) - XFS_XFLAG_SYNC
119 All writes to the file are synchronous.
120 Bit 6 (0x40) - XFS_XFLAG_NOATIME
121 When the file is accessed, its atime record is not
122 modified.
123 Bit 7 (0x80) - XFS_XFLAG_NODUMP
124 The file should be skipped by backup utilities.
125 Bit 8 (0x100) - XFS_XFLAG_RTINHERIT
126 Realtime inheritance bit - new files created in the
127 directory will be automatically realtime, and new
128 directories created in the directory will inherit the
129 inheritance bit.
130 Bit 9 (0x200) - XFS_XFLAG_PROJINHERIT
131 Project inheritance bit - new files and directories
132 created in the directory will inherit the parents
133 project ID. New directories also inherit the project
134 inheritance bit.
135 Bit 10 (0x400) - XFS_XFLAG_NOSYMLINKS
136 Can only be set on a directory and disallows creation
137 of symbolic links in that directory.
138 Bit 11 (0x800) - XFS_XFLAG_EXTSIZE
139 Extent size bit - if a basic extent size value is set
140 on the file then the allocator will allocate in multi‐
141 ples of the set size for this file (see
142 XFS_IOC_FSSETXATTR below).
143 Bit 12 (0x1000) - XFS_XFLAG_EXTSZINHERIT
144 Extent size inheritance bit - new files and directo‐
145 ries created in the directory will inherit the parents
146 basic extent size value (see XFS_IOC_FSSETXATTR
147 below). Can only be set on a directory.
148 Bit 13 (0x2000) - XFS_XFLAG_NODEFRAG
149 No defragment file bit - the file should be skipped
150 during a defragmentation operation. When applied to a
151 directory, new files and directories created will
152 inherit the no-defrag bit.
153 Bit 14 (0x4000) - XFS_XFLAG_FILESTREAM
154 Filestream allocator bit - allows a directory to
155 reserve an allocation group for exclusive use by files
156 created within that directory. Files being written in
157 other directories will not use the same allocation
158 group and so files within different directories will
159 not interleave extents on disk. The reservation is
160 only active while files are being created and written
161 into the directory.
162 Bit 15 (0x8000) - XFS_XFLAG_DAX
163 If the filesystem lives on directly accessible persis‐
164 tent memory, reads and writes to this file will go
165 straight to the persistent memory, bypassing the page
166 cache. A file cannot be reflinked and have the
167 XFS_XFLAG_DAX set at the same time. That is to say
168 that DAX files cannot share blocks.
169 Bit 16 (0x10000) - XFS_XFLAG_COWEXTSIZE
170 Copy on Write Extent size bit - if a CoW extent size
171 value is set on the file, the allocator will allocate
172 extents for staging a copy on write operation in mul‐
173 tiples of the set size for this file (see
174 XFS_IOC_FSSETXATTR below). If the CoW extent size is
175 set on a directory, then new file and directories cre‐
176 ated in the directory will inherit the parent's CoW
177 extent size value.
178 Bit 31 (0x80000000) - XFS_XFLAG_HASATTR
179 The file has extended attributes associated with it.
180 XFS_IOC_FSGETXATTRA
181 Identical to XFS_IOC_FSGETXATTR except that the fsx_nextents
182 field contains the number of attribute extents in the file.
183 XFS_IOC_FSSETXATTR
186 Set additional attributes associated with files in XFS file sys‐
187 tems. The final argument points to a variable of type struct
188 fsxattr, but only the following fields are used in this call:
189 fsx_xflags, fsx_extsize, fsx_cowextsize, and fsx_projid. The
190 fsx_xflags realtime file bit and the file's extent size may be
191 changed only when the file is empty, except in the case of a
192 directory where the extent size can be set at any time (this
193 value is only used for regular file allocations, so should only
194 be set on a directory in conjunction with the XFS_XFLAG_EXTSZIN‐
195 HERIT flag). The copy on write extent size, fsx_cowextsize, can
196 be set at any time.
197 XFS_IOC_GETBMAP
200 Get the block map for a segment of a file in an XFS file system.
201 The final argument points to an arry of variables of type struct
202 getbmap. All sizes and offsets in the structure are in units of
203 512 bytes. The structure fields include: bmv_offset (file off‐
204 set of segment), bmv_block (starting block of segment),
205 bmv_length (length of segment), bmv_count (number of array
206 entries, including the first), and bmv_entries (number of
207 entries filled in). The first structure in the array is a
208 header, and the remaining structures in the array contain block
209 map information on return. The header controls iterative calls
210 to the XFS_IOC_GETBMAP command. The caller fills in the
211 bmv_offset and bmv_length fields of the header to indicate the
212 area of interest in the file, and fills in the bmv_count field
213 to indicate the length of the array. If the bmv_length value is
214 set to -1 then the length of the interesting area is the rest of
215 the file. On return from a call, the header is updated so that
216 the command can be reused to obtain more information, without
217 re-initializing the structures. Also on return, the bmv_entries
218 field of the header is set to the number of array entries actu‐
219 ally filled in. The non-header structures will be filled in
220 with bmv_offset, bmv_block, and bmv_length. If a region of the
221 file has no blocks (is a hole in the file) then the bmv_block
222 field is set to -1.
223 XFS_IOC_GETBMAPA
226 Identical to XFS_IOC_GETBMAP except that information about the
227 attribute fork of the file is returned.
228 XFS_IOC_RESVSP
231 XFS_IOC_RESVSP64
233 This command is used to allocate space to a file. A range of
234 bytes is specified using a pointer to a variable of type
235 xfs_flock64_t in the final argument. The blocks are allocated,
236 but not zeroed, and the file size does not change. If the XFS
237 filesystem is configured to flag unwritten file extents, perfor‐
238 mance will be negatively affected when writing to preallocated
239 space, since extra filesystem transactions are required to con‐
240 vert extent flags on the range of the file written. If
241 xfs_info(8) reports unwritten=1, then the filesystem was made to
242 flag unwritten extents.
243 XFS_IOC_UNRESVSP
246 XFS_IOC_UNRESVSP64
248 This command is used to free space from a file. A range of
249 bytes is specified using a pointer to a variable of type
250 xfs_flock64_t in the final argument. Partial filesystem blocks
251 are zeroed, and whole filesystem blocks are removed from the
252 file. The file size does not change.
253 XFS_IOC_ZERO_RANGE
256 This command is used to convert a range of a file to zeros with‐
257 out issuing data IO. A range of bytes is specified using a
258 pointer to a variable of type xfs_flock64_t in the final argu‐
259 ment. Blocks are preallocated for regions that span holes in
260 the file, and the entire range is converted to unwritten
261 extents. This operation is a fast method of overwriting any
262 from the range specified with zeros without removing any blocks
263 or having to write zeros to disk. Any subsequent read in the
264 given range will return zeros until new data is written. This
265 functionality requires filesystems to support unwritten extents.
266 If xfs_info(8) reports unwritten=1, then the filesystem was made
267 to flag unwritten extents.
268 XFS_IOC_PATH_TO_HANDLE
272 XFS_IOC_PATH_TO_FSHANDLE
273 XFS_IOC_FD_TO_HANDLE
274 XFS_IOC_OPEN_BY_HANDLE
275 XFS_IOC_READLINK_BY_HANDLE
276 XFS_IOC_ATTR_LIST_BY_HANDLE
277 XFS_IOC_ATTR_MULTI_BY_HANDLE
278 XFS_IOC_FSSETDM_BY_HANDLE
279 These are all interfaces that are used to implement various lib‐
280 handle functions (see open_by_handle(3)). They are all subject
281 to change and should not be called directly by applications.
282 Filesystem Operations
284 In order to effect one of the following operations, the pathname and
285 descriptor arguments passed to xfsctl() can be any open file in the XFS
286 filesystem in question.
287 XFS_IOC_FSINUMBERS
289 This interface is used to extract a list of valid inode numbers
290 from an XFS filesystem. It is intended to be called itera‐
291 tively, to obtain the entire set of inodes. The information is
292 passed in and out via a structure of type xfs_fsop_bulkreq_t
293 pointed to by the final argument. lastip is a pointer to a
294 variable containing the last inode number returned, initially it
295 should be zero. icount is the size of the array of structures
296 specified by ubuffer. ubuffer is the address of an array of
297 structures, of type xfs_inogrp_t. This structure has the fol‐
298 lowing elements: xi_startino (starting inode number), xi_alloc‐
299 count (count of bits set in xi_allocmask), and xi_allocmask
300 (mask of allocated inodes in this group). The bitmask is 64
301 bits long, and the least significant bit corresponds to inode
302 xi_startino. Each bit is set if the corresponding inode is in
303 use. ocount is a pointer to a count of returned values, filled
304 in by the call. An output ocount value of zero means that the
305 inode table has been exhausted.
306 XFS_IOC_FSBULKSTAT
308 This interface is used to extract inode information (stat infor‐
309 mation) "in bulk" from a filesystem. It is intended to be
310 called iteratively, to obtain information about the entire set
311 of inodes in a filesystem. The information is passed in and out
312 via a structure of type xfs_fsop_bulkreq_t pointed to by the
313 final argument. lastip is a pointer to a variable containing
314 the last inode number returned, initially it should be zero.
315 icount indicates the size of the array of structures specified
316 by ubuffer. ubuffer is the address of an array of structures of
317 type xfs_bstat_t. Many of the elements in the structure are the
318 same as for the stat structure. The structure has the following
319 elements: bs_ino (inode number), bs_mode (type and mode),
320 bs_nlink (number of links), bs_uid (user id), bs_gid (group id),
321 bs_rdev (device value), bs_blksize (block size of the filesys‐
322 tem), bs_size (file size in bytes), bs_atime (access time),
323 bs_mtime (modify time), bs_ctime (inode change time), bs_blocks
324 (number of blocks used by the file), bs_xflags (extended flags),
325 bs_extsize (extent size), bs_extents (number of extents), bs_gen
326 (generation count), bs_projid_lo (project id - low word),
327 bs_projid_hi (project id - high word, used when projid32bit fea‐
328 ture is enabled), bs_dmevmask (DMIG event mask), bs_dmstate
329 (DMIG state information), and bs_aextents (attribute extent
330 count). ocount is a pointer to a count of returned values,
331 filled in by the call. An output ocount value of zero means
332 that the inode table has been exhausted.
333 XFS_IOC_FSBULKSTAT_SINGLE
335 This interface is a variant of the XFS_IOC_FSBULKSTAT interface,
336 used to obtain information about a single inode. for an open
337 file in the filesystem of interest. The same structure is used
338 to pass information in and out of the kernel, except no output
339 count parameter is used (should be initialized to zero). An
340 error is returned if the inode number is invalid.
341 XFS_IOC_THAW
343 XFS_IOC_FREEZE
344 XFS_IOC_GET_RESBLKS
345 XFS_IOC_SET_RESBLKS
346 XFS_IOC_FSGROWFSDATA
347 XFS_IOC_FSGROWFSLOG
348 XFS_IOC_FSGROWFSRT
349 XFS_IOC_FSCOUNTS
350 These interfaces are used to implement various filesystem inter‐
351 nal operations on XFS filesystems. For XFS_IOC_FSGEOMETRY (get
352 filesystem mkfs time information), the output structure is of
353 type xfs_fsop_geom_t. For XFS_FS_COUNTS (get filesystem dynamic
354 global information), the output structure is of type
355 xfs_fsop_counts_t. The remainder of these operations will not
356 be described further as they are not of general use to applica‐
357 tions.
358
360 fstatfs(2), statfs(2), xfs(5), xfs_info(8).
361 XFSCTL(3)