1xfs_io(8) System Manager's Manual xfs_io(8)
2
6 xfs_io - debug the I/O path of an XFS filesystem
7
9 xfs_io [ -adfimrRstxT ] [ -c cmd ] ... [ -C cmd ] ... [ -p prog ] [
10 file ]
11 xfs_io -V
12
14 xfs_io is a debugging tool like xfs_db(8), but is aimed at examining
15 the regular file I/O paths rather than the raw XFS volume itself.
16 These code paths include not only the obvious read/write/mmap inter‐
17 faces for manipulating files, but also cover all of the XFS extensions
18 (such as space preallocation, additional inode flags, etc).
19
21 xfs_io commands may be run interactively (the default) or as arguments
22 on the command line. Interactive mode always runs commands on the cur‐
23 rent open file, whilst commands run from the command line may be
24 repeated on all open files rather than just the current open file. In
25 general, open file iteration will occur for commands that operate on
26 file content or state. In contrast, commands that operate on filesystem
27 or system-wide state will only be run on the current file regardless of
28 how many files are currently open. Multiple arguments may be given on
29 the command line and they are run in the sequence given. The program
30 exits one all commands have been run.
31 -c cmd Run the specified command on all currently open files. To
33 maintain compatibility with historical usage, commands that
34 can not be run on all open files will still be run but only
35 execute once on the current open file. Multiple -c arguments
36 may be given and may be interleaved on the command line in
37 any order with -C commands.
38 -C cmd Run the specified command only on the current open file.
40 Multiple -C arguments may be given and may be interleaved on
41 the command line in any order with -c commands.
42 -p prog Set the program name for prompts and some error messages, the
44 default value is xfs_io.
45 -f Create file if it does not already exist.
47 -r Open file read-only, initially. This is required if file is
49 immutable or append-only.
50 -i Start an idle thread. The purpose of this idle thread is to
52 test io from a multi threaded process. With single threaded
53 process, the file table is not shared and file structs are
54 not reference counted. Spawning an idle thread can help
55 detecting file struct reference leaks.
56 -x Expert mode. Dangerous commands are only available in this
58 mode. These commands also tend to require additional privi‐
59 leges.
60 -V Prints the version number and exits.
62 The other open(2) options described below are also available from the
64 command line.
65
67 xfs_io maintains a number of open files and memory mappings. Files can
68 be initially opened on the command line (optionally), and additional
69 files can also be opened later.
70 xfs_io commands can be broken up into three groups. Some commands are
72 aimed at doing regular file I/O - read, write, sync, space prealloca‐
73 tion, etc.
74 The second set of commands exist for manipulating memory mapped regions
76 of a file - mapping, accessing, storing, unmapping, flushing, etc.
77 The remaining commands are for the navigation and display of data
79 structures relating to the open files, mappings, and the filesystems
80 where they reside.
81 Many commands have extensive online help. Use the help command for more
83 details on any command.
84
86 file [ N ]
87 Display a list of all open files and (optionally) switch to an
88 alternate current open file.
89 open [[ -acdfrstRTPL ] path ]
91 Closes the current file, and opens the file specified by path
92 instead. Without any arguments, displays statistics about the
93 current file - see the stat command.
94 -a opens append-only (O_APPEND).
95 -d opens for direct I/O (O_DIRECT).
96 -f creates the file if it doesn't already exist (O_CREAT).
97 -r opens read-only (O_RDONLY).
98 -s opens for synchronous I/O (O_SYNC).
99 -t truncates on open (O_TRUNC).
100 -n opens in non-blocking mode if possible (O_NONBLOCK).
101 -T create a temporary file not linked into the filesystem
102 namespace (O_TMPFILE). The pathname passed must refer to
103 a directory which is treated as virtual parent for the
104 newly created invisible file. Can not be used together
105 with the -r option.
106 -R marks the file as a realtime XFS file after opening it,
107 if it is not already marked as such.
108 -P opens the path as a referent only (O_PATH). This is
109 incompatible with other flags specifying other O_xxx
110 flags apart from -L.
111 -L doesn't follow symlinks (O_NOFOLLOW). This is incompati‐
112 ble with other flags specifying other O_xxx flags apart
113 from -P.
114 o See the open command.
116 close Closes the current open file, marking the next open file as cur‐
118 rent (if one exists).
119 c See the close command.
121 chmod -r | -w
123 Change the mode of the currently open file. The -r option will
124 set the file permissions to read-only (0444), whilst the -w
125 option will set the file permissions to read-write (0644). This
126 allows xfs_io to set up mismatches between the file permissions
127 and the open file descriptor read/write mode to exercise permis‐
128 sion checks inside various syscalls.
129 pread [ -b bsize ] [ -qv ] [ -FBR [ -Z seed ] ] [ -V vectors ] offset
131 length
132 Reads a range of bytes in a specified blocksize from the given
133 offset.
134 -b can be used to set the blocksize into which the read(2)
135 requests will be split. The default blocksize is 4096
136 bytes.
137 -q quiet mode, do not write anything to standard output.
138 -v dump the contents of the buffer after reading, by default
139 only the count of bytes actually read is dumped.
140 -F read the buffers in a forwards sequential direction.
141 -B read the buffers in a reserve sequential direction.
142 -R read the buffers in the give range in a random order.
143 -Z seed
144 specify the random number seed used for random reads.
145 -V vectors
146 Use the vectored IO read syscall preadv(2) with a number
147 of blocksize length iovecs. The number of iovecs is set
148 by the vectors parameter.
149 r See the pread command.
151 pwrite [ -i file ] [ -qdDwNOW ] [ -s skip ] [ -b size ] [ -S seed ] [
153 -FBR [ -Z zeed ] ] [ -V vectors ] offset length
154 Writes a range of bytes in a specified blocksize from the given
155 offset. The bytes written can be either a set pattern or read
156 in from another file before writing.
157 -i allows an input file to be specified as the source of the
158 data to be written.
159 -q quiet mode, do not write anything to standard output.
160 -d causes direct I/O, rather than the usual buffered I/O, to
161 be used when reading the input file.
162 -w call fdatasync(2) once all writes are complete (included
163 in timing results)
164 -N Perform the pwritev2(2) call with RWF_NOWAIT.
165 -D Perform the pwritev2(2) call with RWF_DSYNC.
166 -O perform pwrite once and return the (maybe partial) bytes
167 written.
168 -W call fsync(2) once all writes are complete (included in
169 timing results)
170 -s specifies the number of bytes to skip from the start of
171 the input file before starting to read.
172 -b used to set the blocksize into which the write(2)
173 requests will be split. The default blocksize is 4096
174 bytes.
175 -S used to set the (repeated) fill pattern which is used
176 when the data to write is not coming from a file. The
177 default buffer fill pattern value is 0xcdcdcdcd.
178 -F write the buffers in a forwards sequential direction.
179 -B write the buffers in a reserve sequential direction.
180 -R write the buffers in the give range in a random order.
181 -Z seed
182 specify the random number seed used for random write
183 -V vectors
184 Use the vectored IO write syscall pwritev(2) with a num‐
185 ber of blocksize length iovecs. The number of iovecs is
186 set by the vectors parameter.
187 w See the pwrite command.
189 bmap [ -adelpv ] [ -n nx ]
191 Prints the block mapping for the current open file. Refer to the
192 xfs_bmap(8) manual page for complete documentation.
193 fiemap [ -alv ] [ -n nx ] [ offset [ len ]]
195 Prints the block mapping for the current open file using the
196 fiemap ioctl. Options behave as described in the xfs_bmap(8)
197 manual page.
198 Optionally, this command also supports passing the start offset
200 from where to begin the mapping and the length of that region.
201 The kernel will return any full extents which intersect with the
202 requested range, and the fiemap command will print them in their
203 entirety. If the requested range starts or ends in a hole,
204 fiemap will print the hole, truncated to the requested range.
205 extsize [ -R | -D ] [ value ]
207 Display and/or modify the preferred extent size used when allo‐
208 cating space for the currently open file. If the -R option is
209 specified, a recursive descent is performed for all directory
210 entries below the currently open file (-D can be used to
211 restrict the output to directories only). If the target file is
212 a directory, then the inherited extent size is set for that
213 directory (new files created in that directory inherit that
214 extent size). The value should be specified in bytes, or using
215 one of the usual units suffixes (k, m, g, b, etc). The extent
216 size is always reported in units of bytes.
217 cowextsize [ -R | -D ] [ value ]
219 Display and/or modify the preferred copy-on-write extent size
220 used when allocating space for the currently open file. If the
221 -R option is specified, a recursive descent is performed for all
222 directory entries below the currently open file (-D can be used
223 to restrict the output to directories only). If the target file
224 is a directory, then the inherited CoW extent size is set for
225 that directory (new files created in that directory inherit that
226 CoW extent size). The value should be specified in bytes, or
227 using one of the usual units suffixes (k, m, g, b, etc). The
228 extent size is always reported in units of bytes.
229 allocsp size 0
231 Sets the size of the file to size and zeroes any additional
232 space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system
233 call described in the xfsctl(3) manual page. allocsp and freesp
234 do exactly the same thing.
235 freesp size 0
237 See the allocsp command.
238 fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
240 On platforms which support it, allows hints be given to the sys‐
241 tem regarding the expected I/O patterns on the file. The range
242 arguments are required by some advise commands ([*] below), and
243 the others must have no range arguments. With no arguments, the
244 POSIX_FADV_NORMAL advice is implied (default readahead).
245 -d the data will not be accessed again in the near future
246 (POSIX_FADV_DONTNEED[*]).
247 -n data will be accessed once and not be reused
248 (POSIX_FADV_NOREUSE[*]).
249 -r expect access to data in random order (POSIX_FADV_RAN‐
250 DOM), which sets readahead to zero.
251 -s expect access to data in sequential order
252 (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
253 head on the file.
254 -w advises the specified data will be needed again
255 (POSIX_FADV_WILLNEED[*]) which forces the maximum reada‐
256 head.
257 fdatasync
259 Calls fdatasync(2) to flush the file's in-core data to disk.
260 fsync Calls fsync(2) to flush all in-core file state to disk.
262 s See the fsync command.
264 sync_range [ -a | -b | -w ] offset length
266 On platforms which support it, allows control of syncing a range
267 of the file to disk. With no options, SYNC_FILE_RANGE_WRITE is
268 implied on the range supplied.
269 -a wait for IO in the given range to finish after writing
270 (SYNC_FILE_RANGE_WAIT_AFTER).
271 -b wait for IO in the given range to finish before writing
272 (SYNC_FILE_RANGE_WAIT_BEFORE).
273 -w start writeback of dirty data in the given range
274 (SYNC_FILE_RANGE_WRITE).
275 sync Calls sync(2) to flush all filesystems' in-core data to disk.
277 syncfs Calls syncfs(2) to flush this filesystem's in-core data to disk.
279 resvsp offset length
281 Allocates reserved, unwritten space for part of a file using the
282 XFS_IOC_RESVSP system call described in the xfsctl(3) manual
283 page.
284 unresvsp offset length
286 Frees reserved space for part of a file using the
287 XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual
288 page.
289 falloc [ -k ] offset length
291 Allocates reserved, unwritten space for part of a file using the
292 fallocate routine as described in the fallocate(2) manual page.
293 -k will set the FALLOC_FL_KEEP_SIZE flag as described in
294 fallocate(2).
295 fcollapse offset length
297 Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described
298 in the fallocate(2) manual page to de-allocates blocks and elim‐
299 inates the hole created in this process by shifting data blocks
300 into the hole.
301 finsert offset length
303 Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in
304 the fallocate(2) manual page to create the hole by shifting data
305 blocks.
306 fpunch offset length
308 Punches (de-allocates) blocks in the file by calling fallocate
309 with the FALLOC_FL_PUNCH_HOLE flag as described in the fallo‐
310 cate(2) manual page.
311 funshare offset length
313 Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as described in
314 the fallocate(2) manual page to unshare all shared blocks within
315 the range.
316 fzero [ -k ] offset length
318 Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in
319 the fallocate(2) manual page to allocate and zero blocks within
320 the range. With the -k option, use the FALLOC_FL_KEEP_SIZE flag
321 as well.
322 zero offset length
324 Call xfsctl with XFS_IOC_ZERO_RANGE as described in the
325 xfsctl(3) manual page to allocate and zero blocks within the
326 range.
327 truncate offset
329 Truncates the current file at the given offset using ftrun‐
330 cate(2).
331 sendfile [ -q ] -i srcfile | -f N [ offset length ]
333 On platforms which support it, allows a direct in-kernel copy
334 between two file descriptors. The current open file is the tar‐
335 get, the source must be specified as another open file (-f) or
336 by path (-i).
337 -q quiet mode, do not write anything to standard output.
338 readdir [ -v ] [ -o offset ] [ -l length ]
340 Read a range of directory entries from a given offset of a
341 directory.
342 -v verbose mode - dump dirent content as defined in read‐
343 dir(3)
344 -o specify starting offset
345 -l specify total length to read (in bytes)
346 seek -a | -d | -h [ -r ] [ -s ] offset
348 On platforms that support the lseek(2) SEEK_DATA and SEEK_HOLE
349 options, display the offsets of the specified segments.
350 -a Display both data and hole segments starting at the spec‐
351 ified offset.
352 -d Display the data segment starting at the specified off‐
353 set.
354 -h Display the hole segment starting at the specified off‐
355 set.
356 -r Recursively display all the specified segments starting
357 at the specified offset.
358 -s Display the starting lseek(2) offset. This offset will be
359 a calculated value when both data and holes are displayed
360 together or performing a recusively display.
361 reflink [ -C ] [ -q ] src_file [src_offset dst_offset length]
363 On filesystems that support the FICLONERANGE or
364 BTRFS_IOC_CLONE_RANGE ioctls, map length bytes at offset
365 dst_offset in the open file to the same physical blocks that are
366 mapped at offset src_offset in the file src_file , replacing any
367 contents that may already have been there. If a program writes
368 into a reflinked block range of either file, the dirty blocks
369 will be cloned, written to, and remapped ("copy on write") in
370 the affected file, leaving the other file(s) unchanged. If
371 src_offset, dst_offset, and length are omitted, all contents of
372 src_file will be reflinked into the open file.
373 -C Print timing statistics in a condensed format.
374 -q Do not print timing statistics at all.
375 dedupe [ -C ] [ -q ] src_file src_offset dst_offset length
377 On filesystems that support the FIDEDUPERANGE or
378 BTRFS_IOC_FILE_EXTENT_SAME ioctls, map length bytes at offset
379 dst_offset in the open file to the same physical blocks that are
380 mapped at offset src_offset in the file src_file , but only if
381 the contents of both ranges are identical. This is known as
382 block-based deduplication. If a program writes into a reflinked
383 block range of either file, the dirty blocks will be cloned,
384 written to, and remapped ("copy on write") in the affected file,
385 leaving the other file(s) unchanged.
386 -C Print timing statistics in a condensed format.
387 -q Do not print timing statistics at all.
388 copy_range [ -s src_offset ] [ -d dst_offset ] [ -l length ] src_file |
390 -f N
391 On filesystems that support the copy_file_range(2) system call,
392 copies data from the source file into the current open file.
393 The source must be specified either by path (src_file) or as
394 another open file (-f). If length is not specified, this com‐
395 mand copies data from src_offset to the end of src_file into the
396 dst_file at dst_offset.
397 -s Copy data from src_file beginning from src_offset.
398 -d Copy data into the open file beginning at dst_offset.
399 -l Copy up to length bytes of data.
400 swapext donor_file
402 Swaps extent forks between files. The current open file is the
403 target. The donor file is specified by path. Note that file data
404 is not copied (file content moves with the fork(s)).
405 set_encpolicy [ -c mode ] [ -n mode ] [ -f flags ] [ -v version ] [
407 keyspec ]
408 On filesystems that support encryption, assign an encryption
409 policy to the current file. keyspec is a hex string which spec‐
410 ifies the encryption key to use. For v1 encryption policies,
411 keyspec must be a 16-character hex string (8 bytes). For v2
412 policies, keyspec must be a 32-character hex string (16 bytes).
413 If unspecified, an all-zeroes value is used.
414 -c mode
415 contents encryption mode (e.g. AES-256-XTS)
416 -n mode
417 filenames encryption mode (e.g. AES-256-CTS)
418 -f flags
419 policy flags (numeric)
420 -v version
421 policy version. Defaults to 1 or 2 depending on the
422 length of keyspec; or to 1 if keyspec is unspecified.
423 get_encpolicy [ -1 ] [ -t ]
425 On filesystems that support encryption, display the encryption
426 policy of the current file.
427 -1 Use only the old ioctl to get the encryption policy.
428 This only works if the file has a v1 encryption policy.
429 -t Test whether v2 encryption policies are supported.
430 Prints "supported", "unsupported", or an error message.
431 add_enckey [ -d descriptor ] [ -k key_id ]
433 On filesystems that support encryption, add an encryption key to
434 the filesystem containing the currently open file. By default,
435 the raw key in binary (typically 64 bytes long) is read from
436 standard input.
437 -d descriptor
438 key descriptor, as a 16-character hex string (8 bytes).
439 If given, the key will be available for use by v1 encryp‐
440 tion policies that use this descriptor. Otherwise, the
441 key is added as a v2 policy key, and on success the
442 resulting "key identifier" will be printed.
443 -k key_id
444 ID of kernel keyring key of type "fscrypt-provisioning".
445 If given, the raw key will be taken from here rather than
446 from standard input.
447 rm_enckey [ -a ] keyspec
449 On filesystems that support encryption, remove an encryption key
450 from the filesystem containing the currently open file. keyspec
451 is a hex string specifying the key to remove, as a 16-character
452 "key descriptor" or a 32-character "key identifier".
453 -a Remove the key for all users who have added it, not just
454 the current user. This is a privileged operation.
455 enckey_status keyspec
457 On filesystems that support encryption, display the status of an
458 encryption key. keyspec is a hex string specifying the key for
459 which to display the status, as a 16-character "key descriptor"
460 or a 32-character "key identifier".
461 lsattr [ -R | -D | -a | -v ]
463 List extended inode flags on the currently open file. If the -R
464 option is specified, a recursive descent is performed for all
465 directory entries below the currently open file (-D can be used
466 to restrict the output to directories only). This is a depth
467 first descent, it does not follow symlinks and it also does not
468 cross mount points.
469 The current inode flag letters are documented below. Please
471 refer to the ioctl_xfs_fsgetxattr(2) documentation for more
472 details about what they mean.
473 r realtime file (XFS_XFLAG_REALTIME)
475 p prealloc (XFS_XFLAG_PREALLOC)
477 i immutable (XFS_XFLAG_IMMUTABLE)
479 a append only (XFS_XFLAG_APPEND)
481 s synchronous file writes (XFS_XFLAG_SYNC)
483 A noatime (XFS_XFLAG_NOATIME)
485 d nodump (XFS_XFLAG_NODUMP)
487 t inherit realtime flag (XFS_XFLAG_RTINHERIT)"
489 P inherit project id (XFS_XFLAG_PROJINHERIT)
491 n no symlink creation (XFS_XFLAG_NOSYMLINKS)
493 e extent size hint (XFS_XFLAG_EXTSIZE)
495 E inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)
497 f nodefrag (XFS_XFLAG_NODEFRAG)
499 S filestream allocator (XFS_XFLAG_FILESTREAM)
501 x direct access persistent memory (XFS_XFLAG_DAX)
503 C copy on write extent hint (XFS_XFLAG_COWEXTSIZE)
505 X has extended attributes (XFS_XFLAG_HASATTR)
507 chattr [ -R | -D ] [ +/-riasAdtPneEfSxC ]
509 Change extended inode flags on the currently open file. The -R
510 and -D options have the same meaning as above.
511 See the lsattr command above for the list of inode flag letters.
513 flink path
515 Link the currently open file descriptor into the filesystem
516 namespace.
517 stat [ -v|-r ]
518 Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
519 call on the current file. If the -v option is specified, the
520 atime (last access), mtime (last modify), and ctime (last
521 change) timestamps are also displayed. The -r option dumps raw
522 fields from the stat structure.
523 statx [ -v|-r ][ -m basic | -m all | -m <mask> ][ -FD ]
524 Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
525 call on the current file.
526 -v Show timestamps.
527 -r Dump raw statx structure values.
528 -m basic
529 Set the field mask for the statx call to
530 STATX_BASIC_STATS.
531 -m all
532 Set the the field mask for the statx call to STATX_ALL
533 (default).
534 -m <mask>
535 Specify a numeric field mask for the statx call.
536 -F Force the attributes to be synced with the server.
537 -D Don't sync attributes with the server.
538 chproj [ -R|-D ]
540 Modifies the project identifier associated with the current
541 path. The -R option will recursively descend if the current path
542 is a directory. The -D option will also recursively descend,
543 only setting modifying projects on subdirectories. See the
544 xfs_quota(8) manual page for more information about project
545 identifiers.
546 lsproj [ -R|-D ]
548 Displays the project identifier associated with the current
549 path. The -R and -D options behave as described above, in
550 chproj.
551 parent [ -cpv ]
553 By default this command prints out the parent inode numbers,
554 inode generation numbers and basenames of all the hardlinks
555 which point to the inode of the current file.
556 -p the output is similar to the default output except path‐
557 names up to the mount-point are printed out instead of
558 the component name.
559 -c the file's filesystem will check all the parent
560 attributes for consistency.
561 -v verbose output will be printed.
562 [NOTE: Not currently operational on Linux.]
563 utimes atime_sec atime_nsec mtime_sec mtime_nsec
565 The utimes command changes the atime and mtime of the current
566 file. sec uses UNIX timestamp notation and is the seconds
567 elapsed since 1970-01-01 00:00:00 UTC. nsec is the nanoseconds
568 since the sec. This value needs to be in the range 0-999999999
569 with UTIME_NOW and UTIME_OMIT being exceptions. Each (sec,
570 nsec) pair constitutes a single timestamp value.
571
575 mmap [ N | [[ -rwxS ] [-s size ] offset length ]]
576 With no arguments, mmap shows the current mappings. Specifying a
577 single numeric argument N sets the current mapping. If two argu‐
578 ments are specified (a range specified by offset and length), a
579 new mapping is created spanning the range, and the protection
580 mode can be given as a combination of PROT_READ (-r), PROT_WRITE
581 (-w), and PROT_EXEC (-x). The mapping will be created with the
582 MAP_SHARED flag by default, or with the Linux specific (MAP_SYNC
583 | MAP_SHARED_VALIDATE) flags if -S is given. -s size is used to
584 do a mmap(size) && munmap(size) operation at first, try to
585 reserve some extendible free memory space, if size is bigger
586 than length parameter. But there's not guarantee that the memory
587 after length ( up to size ) will stay free. e.g. "mmap -rw -s
588 8192 1024" will mmap 0 ~ 1024 bytes memory, but try to reserve
589 1024 ~ 8192 free space(no guarantee). This free space will help‐
590 ful for "mremap 8192" without MREMAP_MAYMOVE flag.
591 mm See the mmap command.
593 mremap [ -f <new_address> ] [ -m ] new_length
595 Changes the current mapping size to new_length. Whether the
596 mapping may be moved is controlled by the flags passed;
597 MREMAP_FIXED (-f), or MREMAP_MAYMOVE (-m). new_length specifies
598 a page-aligned address to which the mapping must be moved. It
599 can be set to 139946004389888, 4096k or 1g etc.
600 mrm See the mremap command.
602 munmap Unmaps the current memory mapping.
604 mu See the munmap command.
606 mread [ -f | -v ] [ -r ] [ offset length ]
608 Accesses a segment of the current memory mapping, optionally
609 dumping it to the standard output stream (with -v or -f option)
610 for inspection. The accesses are performed sequentially from the
611 start offset by default, but can also be done from the end back‐
612 wards through the mapping if the -r option in specified. The
613 two verbose modes differ only in the relative offsets they dis‐
614 play, the -f option is relative to file start, whereas -v shows
615 offsets relative to the start of the mapping.
616 mr See the mread command.
618 mwrite [ -r ] [ -S seed ] [ offset length ]
620 Stores a byte into memory for a range within a mapping. The
621 default stored value is 'X', repeated to fill the range speci‐
622 fied, but this can be changed using the -S option. The memory
623 stores are performed sequentially from the start offset by
624 default, but can also be done from the end backwards through the
625 mapping if the -r option in specified.
626 mw See the mwrite command.
628 msync [ -i ] [ -a | -s ] [ offset length ]
630 Writes all modified copies of pages over the specified range (or
631 entire mapping if no range specified) to their backing storage
632 locations. Also, optionally invalidates (-i) so that subsequent
633 references to the pages will be obtained from their backing
634 storage locations (instead of cached copies). The flush can be
635 done synchronously (-s) or asynchronously (-a).
636 ms See the msync command.
638 madvise [ -d | -r | -s | -w ] [ offset length ]
640 Modifies page cache behavior when operating on the current map‐
641 ping. The range arguments are required by some advise commands
642 ([*] below). With no arguments, the POSIX_MADV_NORMAL advice is
643 implied (default readahead).
644 -d the pages will not be needed (POSIX_MADV_DONTNEED[*]).
645 -r expect random page references (POSIX_MADV_RANDOM), which
646 sets readahead to zero.
647 -s expect sequential page references (POSIX_MADV_SEQUEN‐
648 TIAL), which doubles the default readahead on the file.
649 -w advises the specified pages will be needed again
650 (POSIX_MADV_WILLNEED[*]) which forces the maximum reada‐
651 head.
652 mincore
654 Dumps a list of pages or ranges of pages that are currently in
655 core, for the current memory mapping.
656
659 bulkstat [ -a agno ] [ -d ] [ -e endino ] [ -n batchsize ] [ -s
660 startino ] [ -v version"]
661 Display raw stat information about a bunch of inodes in an XFS
662 filesystem. Options are as follows:
663 -a agno
664 Display only results from the given allocation group.
665 If not specified, all results returned will be dis‐
666 played.
667 -d Print debugging information about call results.
668 -e endino
669 Stop displaying records when this inode number is
670 reached. Defaults to stopping when the system call
671 stops returning results.
672 -n batchsize
673 Retrieve at most this many records per call. Defaults
674 to 4,096.
675 -s startino
676 Display inode allocation records starting with this
677 inode. Defaults to the first inode in the filesystem.
678 If the given inode is not allocated, results will
679 begin with the next allocated inode in the filesystem.
680 -v version
681 Use a particular version of the kernel interface.
682 Currently supported versions are 1 and 5.
683 bulkstat_single [ -d ] [ -v version ] [ inum... | special... ]
685 Display raw stat information about individual inodes in an XFS
686 filesystem. The -d and -v options are the same as the bulkstat
687 command. Arguments must be inode numbers or any of the special
688 values:
689 root Display information about the root directory inode.
690 freeze Suspend all write I/O requests to the filesystem of the current
692 file. Only available in expert mode and requires privileges.
693 thaw Undo the effects of a filesystem freeze operation. Only avail‐
695 able in expert mode and requires privileges.
696 inject [ tag ]
698 Inject errors into a filesystem to observe filesystem behavior
699 at specific points under adverse conditions. Without the tag
700 argument, displays the list of error tags available. Only
701 available in expert mode and requires privileges.
702 resblks [ blocks ]
704 Get and/or set count of reserved filesystem blocks using the
705 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. Note
706 -- this can be useful for exercising out of space behavior.
707 Only available in expert mode and requires privileges.
708 shutdown [ -f ]
710 Force the filesystem to shut down, preventing any further IO.
711 XFS and other filesystems implement this functionality, although
712 implementation details may differ slightly. Only available in
713 expert mode and requires privileges.
714 By default, the filesystem will not attempt to flush completed
716 transactions to disk before shutting down the filesystem. This
717 simulates a disk failure or crash.
718 -f Force the filesystem to flush all completed transactions
719 to disk before shutting down, matching XFS behavior when
720 critical corruption is encountered.
721 statfs Selected statistics from statfs(2) and the XFS_IOC_FSGEOMETRY
723 system call on the filesystem where the current file resides.
724 inode [ [ -n ] number ] [ -v ]
726 The inode command queries physical information about an inode.
727 With no arguments, it will return 1 or 0, indicating whether or
728 not any inode numbers greater than 32 bits are currently in use
729 in the filesystem. If given an inode number as an argument, the
730 command will return the same inode number if it is in use, or 0
731 if not. With -n number , the next used inode number after this
732 number will be returned, or zero if the supplied inode number is
733 the highest one in use. With -v the command will also report the
734 number of bits (32 or 64) used by the inode number printed in
735 the result; if no inode number was specified on the command
736 line, the maximum possible inode number in the system will be
737 printed along with its size.
738 inumbers [ -a agno ] [ -d ] [ -e endino ] [ -n batchsize ] [ -s
740 startino ] [ -v version ]
741 Prints allocation information about groups of inodes in an XFS
742 filesystem. Callers can use this information to figure out
743 which inodes are allocated. Options are as follows:
744 -a agno
745 Display only results from the given allocation group.
746 If not specified, all results returned will be dis‐
747 played.
748 -d Print debugging information about call results.
749 -e endino
750 Stop displaying records when this inode number is
751 reached. Defaults to stopping when the system call
752 stops returning results.
753 -n batchsize
754 Retrieve at most this many records per call. Defaults
755 to 4,096.
756 -s startino
757 Display inode allocation records starting with this
758 inode. Defaults to the first inode in the filesystem.
759 If the given inode is not allocated, results will
760 begin with the next allocated inode in the filesystem.
761 -v version
762 Use a particular version of the kernel interface.
763 Currently supported versions are 1 and 5.
764 scrub type [ agnumber | ino gen ]
766 Scrub internal XFS filesystem metadata. The type parameter
767 specifies which type of metadata to scrub. For AG metadata, one
768 AG number must be specified. For file metadata, the scrub is
769 applied to the open file unless the inode number and generation
770 number are specified.
771 repair type [ agnumber | ino gen ]
773 Repair internal XFS filesystem metadata. The type parameter
774 specifies which type of metadata to repair. For AG metadata,
775 one AG number must be specified. For file metadata, the repair
776 is applied to the open file unless the inode number and genera‐
777 tion number are specified.
778 label [ -c | -s label ]
780 On filesystems that support online label manipulation, get, set,
781 or clear the filesystem label. With no options, print the cur‐
782 rent filesystem label. The -c option clears the filesystem
783 label by setting it to the null string. The -s label option
784 sets the filesystem label to label. If the label is longer than
785 the filesystem will accept, xfs_io will print an error message.
786 XFS filesystem labels can be at most 12 characters long.
787 fsmap [ -d | -l | -r ] [ -m | -v ] [ -n nx ] [ start ] [ end ]
789 Prints the mapping of disk blocks used by the filesystem hosting
790 the current file. The map lists each extent used by files,
791 allocation group metadata, journalling logs, and static filesys‐
792 tem metadata, as well as any regions that are unused. Each line
793 of the listings takes the following form:
794 extent: major:minor [startblock..endblock]: owner startoff‐
796 set..endoffset length
797 Static filesystem metadata, allocation group metadata, btrees,
799 journalling logs, and free space are marked by replacing the
800 startoffset..endoffset with the appropriate marker. All blocks,
801 offsets, and lengths are specified in units of 512-byte blocks,
802 no matter what the filesystem's block size is. The optional
803 start and end arguments can be used to constrain the output to a
804 particular range of disk blocks. If these two options are spec‐
805 ified, exactly one of -d, -l, or -r must also be set.
806 -d Display only extents from the data device. This
807 option only applies for XFS filesystems.
808 -l Display only extents from the external log device.
809 This option only applies to XFS filesystems.
810 -r Display only extents from the realtime device. This
811 option only applies to XFS filesystems.
812 -m Display results in a machine readable format (CSV).
813 This option is not compatible with the -v flag. The
814 columns of the output are: extent number, device
815 major, device minor, physical start, physical end,
816 owner, offset start, offset end, length. The start,
817 end, and length numbers are provided in units of 512b.
818 The owner field is a special string that takes the
819 form:
820 inode_%lld_data
822 for inode data.
823 inode_%lld_data_bmbt
824 for inode data extent maps.
825 inode_%lld_attr
826 for inode extended attribute data.
827 inode_%lld_attr_bmbt
828 for inode extended attribute extent maps.
829 special_%u:%u
830 for other filesystem metadata.
831 -n num_extents
834 If this option is given, fsmap obtains the extent list
835 of the file in groups of num_extents extents. In the
836 absence of -n, fsmap queries the system for extents in
837 groups of 131,072 records.
838 -v Shows verbose information. When this flag is speci‐
840 fied, additional AG specific information is appended
841 to each line in the following form:
842 agno (startagblock..endagblock) nblocks flags
844 A second -v option will print out the flags legend.
846 This option is not compatible with the -m flag.
847
851 help [ command ]
852 Display a brief description of one or all commands.
853 print Display a list of all open files and memory mapped regions. The
855 current file and current mapping are distinguishable from any
856 others.
857 p See the print command.
859 quit Exit xfs_io.
861 q See the quit command.
863 log_writes -d device -m mark
865 Create a mark named mark in the dm-log-writes log specified by
866 device. This is intended to be equivalent to the shell command:
867 dmsetup message device 0 mark mark
869 lw See the log_writes command.
871 crc32cselftest
873 Test the internal crc32c implementation to make sure that it
874 computes results correctly.
875
877 mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2),
878 fstat(2), fstatfs(2), fsync(2), ftruncate(2), futimens(3), mmap(2),
879 msync(2), open(2), pread(2), pwrite(2), readdir(3), dmsetup(8).
880 xfs_io(8)