Debian Codegraph @

upstream/debian-unstable/man8/xfs_io.8

raw
1 .TH xfs_io 8
2 .SH NAME
3 xfs_io \- debug the I/O path of an XFS filesystem
4 .SH SYNOPSIS
5 .B xfs_io
6 [
7 .B \-adfimrRstxT
8 ] [
9 .B \-c
10 .I cmd
11 ] ... [
12 .B \-C
13 .I cmd
14 ] ... [
15 .B \-p
16 .I prog
17 ]
18 .I [ file ]
19 .br
20 .B xfs_io \-V
21 .SH DESCRIPTION
22 .B xfs_io
23 is a debugging tool like
24 .BR xfs_db (8),
25 but is aimed at examining the regular file I/O paths rather than the
26 raw XFS volume itself.
27 These code paths include not only the obvious read/write/mmap interfaces
28 for manipulating files, but also cover all of the XFS extensions (such
29 as space preallocation, additional inode flags, etc).
30 .SH OPTIONS
31 .B xfs_io
32 commands may be run interactively (the default) or as arguments on the
33 command line.
34 Interactive mode always runs commands on the current open file, whilst commands
35 run from the command line may be repeated on all open files rather than just the current
36 open file.
37 In general, open file iteration will occur for commands that operate on file
38 content or state. In contrast, commands that operate on filesystem or
39 system-wide state will only be run on the current file regardless of how many
40 files are currently open.
41 Multiple arguments may be given on the command line and they are run in the
42 sequence given. The program exits one all commands have
43 been run.
44 .TP 1.0i
45 .BI \-c " cmd"
46 Run the specified command on all currently open files.
47 To maintain compatibility with historical usage, commands that can not be run on
48 all open files will still be run but only execute once on the current open file.
49 Multiple
50 .B \-c
51 arguments may be given and may be interleaved on the command line in any order
52 with
53 .B \-C
54 commands.
55 .TP
56 .BI \-C " cmd"
57 Run the specified command only on the current open file.
58 Multiple
59 .B \-C
60 arguments may be given and may be interleaved on the command line in any order
61 with
62 .B \-c
63 commands.
64 .TP
65 .BI \-p " prog"
66 Set the program name for prompts and some error messages,
67 the default value is
68 .BR xfs_io .
69 .TP
70 .B \-f
71 Create
72 .I file
73 if it does not already exist.
74 .TP
75 .B \-r
76 Open
77 .I file
78 read-only, initially. This is required if
79 .I file
80 is immutable or append-only.
81 .TP
82 .B \-i
83 Start an idle thread. The purpose of this idle thread is to test io
84 from a multi threaded process. With single threaded process,
85 the file table is not shared and file structs are not reference counted.
86 Spawning an idle thread can help detecting file struct reference leaks.
87 .TP
88 .B \-x
89 Expert mode. Dangerous commands are only available in this mode.
90 These commands also tend to require additional privileges.
91 .TP
92 .B \-V
93 Prints the version number and exits.
94 .PP
95 The other
96 .BR open (2)
97 options described below are also available from the command line.
98 .SH CONCEPTS
99 .B xfs_io
100 maintains a number of open files and memory mappings.
101 Files can be initially opened on the command line (optionally),
102 and additional files can also be opened later.
103 .PP
104 .B xfs_io
105 commands can be broken up into three groups.
106 Some commands are aimed at doing regular file I/O - read, write,
107 sync, space preallocation, etc.
108 .PP
109 The second set of commands exist for manipulating memory mapped regions
110 of a file - mapping, accessing, storing, unmapping, flushing, etc.
111 .PP
112 The remaining commands are for the navigation and display of data
113 structures relating to the open files, mappings, and the filesystems
114 where they reside.
115 .PP
116 Many commands have extensive online help. Use the
117 .B help
118 command for more details on any command.
119 .SH FILE I/O COMMANDS
120 .TP
121 .BI "file [ " N " ]"
122 Display a list of all open files and (optionally) switch to an alternate
123 current open file.
124 .TP
125 .BI "open [[ \-acdfrstRTPL ] " path " ]"
126 Closes the current file, and opens the file specified by
127 .I path
128 instead. Without any arguments, displays statistics about the current
129 file \- see the
130 .B stat
131 command.
132 .RS 1.0i
133 .PD 0
134 .TP 0.4i
135 .B \-a
136 opens append-only (O_APPEND).
137 .TP
138 .B \-d
139 opens for direct I/O (O_DIRECT).
140 .TP
141 .B \-f
142 creates the file if it doesn't already exist (O_CREAT).
143 .TP
144 .B \-r
145 opens read-only (O_RDONLY).
146 .TP
147 .B \-s
148 opens for synchronous I/O (O_SYNC).
149 .TP
150 .B \-t
151 truncates on open (O_TRUNC).
152 .TP
153 .B \-n
154 opens in non-blocking mode if possible (O_NONBLOCK).
155 .TP
156 .B \-T
157 create a temporary file not linked into the filesystem namespace
158 (O_TMPFILE). The pathname passed must refer to a directory which
159 is treated as virtual parent for the newly created invisible file.
160 Can not be used together with the
161 .B \-r
162 option.
163 .TP
164 .B \-R
165 marks the file as a realtime XFS file after
166 opening it, if it is not already marked as such.
167 .TP
168 .B \-P
169 opens the path as a referent only (O_PATH). This is incompatible with other
170 flags specifying other O_xxx flags apart from
171 .BR \-L .
172 .TP
173 .B \-L
174 doesn't follow symlinks (O_NOFOLLOW). This is incompatible with other
175 flags specifying other O_xxx flags apart from
176 .BR \-P .
177 .PD
178 .RE
179 .TP
180 .B o
181 See the
182 .B open
183 command.
184 .TP
185 .B close
186 Closes the current open file, marking the next open file as current
187 (if one exists).
188 .TP
189 .B c
190 See the
191 .B close
192 command.
193 .TP
194 .B chmod \-r | \-w
195 Change the mode of the currently open file. The
196 .B \-r
197 option will set the file permissions to read-only (0444), whilst the
198 .B \-w
199 option will set the file permissions to read-write (0644). This allows xfs_io to
200 set up mismatches between the file permissions and the open file descriptor
201 read/write mode to exercise permission checks inside various syscalls.
202 .TP
203 .BI "pread [ \-b " bsize " ] [ \-qUv ] [ \-FBR [ \-Z " seed " ] ] [ \-V " vectors " ] " "offset length"
204 Reads a range of bytes in a specified blocksize from the given
205 .IR offset .
206 .RS 1.0i
207 .PD 0
208 .TP 0.4i
209 .B \-b
210 can be used to set the blocksize into which the
211 .BR read (2)
212 requests will be split. The default blocksize is 4096 bytes.
213 .TP
214 .B \-q
215 quiet mode, do not write anything to standard output.
216 .TP
217 .B \-U
218 Perform the
219 .BR preadv2 (2)
220 call with
221 .IR RWF_DONTCACHE .
222 .TP
223 .B \-v
224 dump the contents of the buffer after reading,
225 by default only the count of bytes actually read is dumped.
226 .TP
227 .B \-F
228 read the buffers in a forward sequential direction.
229 .TP
230 .B \-B
231 read the buffers in a reverse sequential direction.
232 .TP
233 .B \-R
234 read the buffers in the give range in a random order.
235 .TP
236 .B \-Z seed
237 specify the random number seed used for random reads.
238 .TP
239 .B \-V vectors
240 Use the vectored IO read syscall
241 .BR preadv (2)
242 with a number of blocksize length iovecs. The number of iovecs is set by the
243 .I vectors
244 parameter.
245 .PD
246 .RE
247 .TP
248 .B r
249 See the
250 .B pread
251 command.
252 .TP
253 .BI "pwrite [ \-i " file " ] [ \-qAdDwNOUW ] [ \-s " skip " ] [ \-b " size " ] [ \-S " seed " ] [ \-FBR [ \-Z " zeed " ] ] [ \-V " vectors " ] " "offset length"
254 Writes a range of bytes in a specified blocksize from the given
255 .IR offset .
256 The bytes written can be either a set pattern or read in from another
257 file before writing.
258 .RS 1.0i
259 .PD 0
260 .TP 0.4i
261 .B \-i
262 allows an input
263 .I file
264 to be specified as the source of the data to be written.
265 .TP
266 .B \-q
267 quiet mode, do not write anything to standard output.
268 .TP
269 .B \-d
270 causes direct I/O, rather than the usual buffered
271 I/O, to be used when reading the input file.
272 .TP
273 .B \-w
274 call
275 .BR fdatasync (2)
276 once all writes are complete (included in timing results)
277 .TP
278 .B \-N
279 Perform the
280 .BR pwritev2 (2)
281 call with
282 .IR RWF_NOWAIT .
283 .TP
284 .B \-D
285 Perform the
286 .BR pwritev2 (2)
287 call with
288 .IR RWF_DSYNC .
289 .TP
290 .B \-A
291 Perform the
292 .BR pwritev2 (2)
293 call with
294 .IR RWF_ATOMIC .
295 .TP
296 .B \-U
297 Perform the
298 .BR pwritev2 (2)
299 call with
300 .IR RWF_DONTCACHE .
301 .TP
302 .B \-O
303 perform pwrite once and return the (maybe partial) bytes written.
304 .TP
305 .B \-W
306 call
307 .BR fsync (2)
308 once all writes are complete (included in timing results)
309 .TP
310 .B \-s
311 specifies the number of bytes to
312 .I skip
313 from the start of the input file before starting to read.
314 .TP
315 .B \-b
316 used to set the blocksize into which the
317 .BR write (2)
318 requests will be split. The default blocksize is 4096 bytes.
319 .TP
320 .B \-S
321 used to set the (repeated) fill pattern which
322 is used when the data to write is not coming from a file.
323 The default buffer fill pattern value is 0xcdcdcdcd.
324 .TP
325 .B \-F
326 write the buffers in a forward sequential direction.
327 .TP
328 .B \-B
329 write the buffers in a reverse sequential direction.
330 .TP
331 .B \-R
332 write the buffers in the give range in a random order.
333 .TP
334 .B \-Z seed
335 specify the random number seed used for random write
336 .TP
337 .B \-V vectors
338 Use the vectored IO write syscall
339 .BR pwritev (2)
340 with a number of blocksize length iovecs. The number of iovecs is set by the
341 .I vectors
342 parameter.
343 .RE
344 .PD
345 .TP
346 .B w
347 See the
348 .B pwrite
349 command.
350 .TP
351 .BI "bmap [ \-adelpv ] [ \-n " nx " ]"
352 Prints the block mapping for the current open file. Refer to the
353 .BR xfs_bmap (8)
354 manual page for complete documentation.
355 .TP
356 .BI "fiemap [ \-alv ] [ \-n " nx " ] [ " offset " [ " len " ]]"
357 Prints the block mapping for the current open file using the fiemap
358 ioctl. Options behave as described in the
359 .BR xfs_bmap (8)
360 manual page.
361 .PP
362 .RS
363 Optionally, this command also supports passing the start offset
364 from where to begin the mapping and the length of that region.
365 The kernel will return any full extents which intersect with the requested
366 range, and the
367 .B fiemap
368 command will print them in their entirety. If the requested range starts
369 or ends in a hole,
370 .B fiemap
371 will print the hole, truncated to the requested range.
372 .RE
373 .TP
374 .BI "extsize [ \-R | \-D ] [ " value " ]"
375 Display and/or modify the preferred extent size used when allocating
376 space for the currently open file. If the
377 .B \-R
378 option is specified, a recursive descent is performed
379 for all directory entries below the currently open file
380 .RB ( \-D
381 can be used to restrict the output to directories only).
382 If the target file is a directory, then the inherited extent size
383 is set for that directory (new files created in that directory
384 inherit that extent size).
385 The
386 .I value
387 should be specified in bytes, or using one of the usual units suffixes
388 (k, m, g, b, etc). The extent size is always reported in units of bytes.
389 .TP
390 .BI "cowextsize [ \-R | \-D ] [ " value " ]"
391 Display and/or modify the preferred copy-on-write extent size used
392 when allocating space for the currently open file. If the
393 .B \-R
394 option is specified, a recursive descent is performed
395 for all directory entries below the currently open file
396 .RB ( \-D
397 can be used to restrict the output to directories only).
398 If the target file is a directory, then the inherited CoW extent size
399 is set for that directory (new files created in that directory
400 inherit that CoW extent size).
401 The
402 .I value
403 should be specified in bytes, or using one of the usual units suffixes
404 (k, m, g, b, etc). The extent size is always reported in units of bytes.
405 .TP
406 .BI "allocsp " size " 0"
407 Sets the size of the file to
408 .I size
409 and zeroes any additional space allocated using the
410 XFS_IOC_ALLOCSP/XFS_IOC_FREESP system call described in the
411 .BR xfsctl (3)
412 manual page.
413 .B allocsp
414 and
415 .B freesp
416 do exactly the same thing.
417
418 These commands are no longer supported as of Linux 5.17.
419 .TP
420 .BI "freesp " size " 0"
421 See the
422 .B allocsp
423 command.
424 .TP
425 .BI "fadvise [ \-r | \-s | [[ \-d | \-n | \-w ] " "offset length " ]]
426 On platforms which support it, allows hints be given to the system
427 regarding the expected I/O patterns on the file.
428 The range arguments are required by some advise commands ([*] below), and
429 the others must have no range arguments.
430 With no arguments, the POSIX_FADV_NORMAL advice is implied (default readahead).
431 .RS 1.0i
432 .PD 0
433 .TP 0.4i
434 .B \-d
435 the data will not be accessed again in the near future (POSIX_FADV_DONTNEED[*]).
436 .TP
437 .B \-n
438 data will be accessed once and not be reused (POSIX_FADV_NOREUSE[*]).
439 .TP
440 .B \-r
441 expect access to data in random order (POSIX_FADV_RANDOM), which sets readahead to zero.
442 .TP
443 .B \-s
444 expect access to data in sequential order (POSIX_FADV_SEQUENTIAL),
445 which doubles the default readahead on the file.
446 .TP
447 .B \-w
448 advises the specified data will be needed again (POSIX_FADV_WILLNEED[*])
449 which forces the maximum readahead.
450 .RE
451 .PD
452 .TP
453 .B fdatasync
454 Calls
455 .BR fdatasync (2)
456 to flush the file's in-core data to disk.
457 .TP
458 .B fsync
459 Calls
460 .BR fsync (2)
461 to flush all in-core file state to disk.
462 .TP
463 .B s
464 See the
465 .B fsync
466 command.
467 .TP
468 .BI "sync_range [ \-a | \-b | \-w ] offset length "
469 On platforms which support it, allows control of syncing a range of the file to
470 disk. With no options, SYNC_FILE_RANGE_WRITE is implied on the range supplied.
471 .RS 1.0i
472 .PD 0
473 .TP 0.4i
474 .B \-a
475 wait for IO in the given range to finish after writing
476 (SYNC_FILE_RANGE_WAIT_AFTER).
477 .TP
478 .B \-b
479 wait for IO in the given range to finish before writing
480 (SYNC_FILE_RANGE_WAIT_BEFORE).
481 .TP
482 .B \-w
483 start writeback of dirty data in the given range (SYNC_FILE_RANGE_WRITE).
484 .RE
485 .PD
486 .TP
487 .B sync
488 Calls
489 .BR sync (2)
490 to flush all filesystems' in-core data to disk.
491 .TP
492 .B syncfs
493 Calls
494 .BR syncfs (2)
495 to flush this filesystem's in-core data to disk.
496 .TP
497 .BI resvsp " offset length"
498 Allocates reserved, unwritten space for part of a file using the
499 XFS_IOC_RESVSP system call described in the
500 .BR xfsctl (3)
501 manual page.
502 .TP
503 .BI unresvsp " offset length"
504 Frees reserved space for part of a file using the XFS_IOC_UNRESVSP
505 system call described in the
506 .BR xfsctl (3)
507 manual page.
508 .TP
509 .BI "falloc [ \-k ]" " offset length"
510 Allocates reserved, unwritten space for part of a file using the
511 fallocate routine as described in the
512 .BR fallocate (2)
513 manual page.
514 .RS 1.0i
515 .PD 0
516 .TP 0.4i
517 .B \-k
518 will set the FALLOC_FL_KEEP_SIZE flag as described in
519 .BR fallocate (2).
520 .PD
521 .RE
522 .TP
523 .BI fcollapse " offset length"
524 Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described in the
525 .BR fallocate (2)
526 manual page to de-allocates blocks and eliminates the hole created in this process
527 by shifting data blocks into the hole.
528 .TP
529 .BI finsert " offset length"
530 Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in the
531 .BR fallocate (2)
532 manual page to create the hole by shifting data blocks.
533 .TP
534 .BI fpunch " offset length"
535 Punches (de-allocates) blocks in the file by calling fallocate with
536 the FALLOC_FL_PUNCH_HOLE flag as described in the
537 .BR fallocate (2)
538 manual page.
539 .TP
540 .BI funshare " offset length"
541 Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as described in the
542 .BR fallocate (2)
543 manual page to unshare all shared blocks within the range.
544 .TP
545 .BI "fzero [ \-k ]" " offset length"
546 Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in the
547 .BR fallocate (2)
548 manual page to allocate and zero blocks within the range.
549 With the
550 .B -k
551 option, use the FALLOC_FL_KEEP_SIZE flag as well.
552 .TP
553 .BI fwzero " offset length"
554 Call fallocate with FALLOC_FL_WRITE_ZEROES flag as described in the
555 .BR fallocate (2)
556 manual page to allocate and zero blocks within the range by submitting write
557 zeroes.
558 .TP
559 .BI zero " offset length"
560 Call xfsctl with
561 .B XFS_IOC_ZERO_RANGE
562 as described in the
563 .BR xfsctl (3)
564 manual page to allocate and zero blocks within the range.
565 .TP
566 .BI truncate " offset"
567 Truncates the current file at the given offset using
568 .BR ftruncate (2).
569 .TP
570 .BI "sendfile [ \-q ] \-i " srcfile " | \-f " N " [ " "offset length " ]
571 On platforms which support it, allows a direct in-kernel copy between
572 two file descriptors. The current open file is the target, the source
573 must be specified as another open file
574 .RB ( \-f )
575 or by path
576 .RB ( \-i ).
577 .RS 1.0i
578 .B \-q
579 quiet mode, do not write anything to standard output.
580 .RE
581 .TP
582 .BI "readdir [ -v ] [ -o " offset " ] [ -l " length " ] "
583 Read a range of directory entries from a given offset of a directory.
584 .RS 1.0i
585 .PD 0
586 .TP 0.4i
587 .B \-v
588 verbose mode - dump dirent content as defined in
589 .BR readdir (3)
590 .TP
591 .B \-o
592 specify starting
593 .I offset
594 .TP
595 .B \-l
596 specify total
597 .I length
598 to read (in bytes)
599 .RE
600 .PD
601 .TP
602 .BI "seek \-a | \-d | \-h [ \-r ] [ \-s ] offset"
603 On platforms that support the
604 .BR lseek (2)
605 .B SEEK_DATA
606 and
607 .B SEEK_HOLE
608 options, display the offsets of the specified segments.
609 .RS 1.0i
610 .PD 0
611 .TP 0.4i
612 .B \-a
613 Display both
614 .B data
615 and
616 .B hole
617 segments starting at the specified
618 .B offset.
619 .TP
620 .B \-d
621 Display the
622 .B data
623 segment starting at the specified
624 .B offset.
625 .TP
626 .B \-h
627 Display the
628 .B hole
629 segment starting at the specified
630 .B offset.
631 .TP
632 .B \-r
633 Recursively display all the specified segments starting at the specified
634 .B offset.
635 .TP
636 .B \-s
637 Display the starting lseek(2) offset. This offset will be a calculated value when
638 both data and holes are displayed together or performing a recusively display.
639 .RE
640 .PD
641 .TP
642 .BI "reflink [ \-C ] [ \-q ] src_file [src_offset dst_offset length]"
643 On filesystems that support the
644 .B FICLONERANGE
645 or
646 .B BTRFS_IOC_CLONE_RANGE
647 ioctls, map
648 .I length
649 bytes at offset
650 .I dst_offset
651 in the open file to the same physical blocks that are mapped at offset
652 .I src_offset
653 in the file
654 .I src_file
655 , replacing any contents that may already have been there. If a program
656 writes into a reflinked block range of either file, the dirty blocks will be
657 cloned, written to, and remapped ("copy on write") in the affected file,
658 leaving the other file(s) unchanged. If src_offset, dst_offset, and length
659 are omitted, all contents of src_file will be reflinked into the open file.
660 .RS 1.0i
661 .PD 0
662 .TP 0.4i
663 .B \-C
664 Print timing statistics in a condensed format.
665 .TP
666 .B \-q
667 Do not print timing statistics at all.
668 .RE
669 .PD
670 .TP
671 .BI "dedupe [ \-C ] [ \-q ] src_file src_offset dst_offset length"
672 On filesystems that support the
673 .B FIDEDUPERANGE
674 or
675 .B BTRFS_IOC_FILE_EXTENT_SAME
676 ioctls, map
677 .I length
678 bytes at offset
679 .I dst_offset
680 in the open file to the same physical blocks that are mapped at offset
681 .I src_offset
682 in the file
683 .I src_file
684 , but only if the contents of both ranges are identical. This is known as
685 block-based deduplication. If a program writes into a reflinked block range of
686 either file, the dirty blocks will be cloned, written to, and remapped ("copy
687 on write") in the affected file, leaving the other file(s) unchanged.
688 .RS 1.0i
689 .PD 0
690 .TP 0.4i
691 .B \-C
692 Print timing statistics in a condensed format.
693 .TP
694 .B \-q
695 Do not print timing statistics at all.
696 .RE
697 .PD
698 .TP
699 .BI "copy_range [ -s " src_offset " ] [ -d " dst_offset " ] [ -l " length " ] src_file | \-f " N
700 On filesystems that support the
701 .BR copy_file_range (2)
702 system call, copies data from the source file into the current open file.
703 The source must be specified either by path
704 .RB ( src_file )
705 or as another open file
706 .RB ( \-f ).
707 If
708 .I length
709 is not specified, this command copies data from
710 .I src_offset
711 to the end of
712 .BI src_file
713 into the dst_file at
714 .IR dst_offset .
715 .RS 1.0i
716 .PD 0
717 .TP 0.4i
718 .B \-s
719 Copy data from
720 .I src_file
721 beginning from
722 .IR src_offset .
723 .TP
724 .B \-d
725 Copy data into the open file beginning at
726 .IR dst_offset .
727 .TP
728 .B \-l
729 Copy up to
730 .I length
731 bytes of data.
732 .RE
733 .PD
734 .TP
735 .BI swapext " donor_file "
736 Swaps extent forks between files. The current open file is the target. The donor
737 file is specified by path. Note that file data is not copied (file content moves
738 with the fork(s)).
739 .TP
740 .BI "exchangerange [OPTIONS]" donor_file "
741 Exchanges contents between files.
742 The current open file is the target.
743 The donor file is specified by path.
744 Note that file data is not copied (file content moves with the fork(s)).
745 Options include:
746 .RS 1.0i
747 .PD 0
748 .TP 0.4i
749 .TP
750 .B \-C
751 Print timing information in a condensed format.
752 .TP
753 .B \-c
754 Exchange contents only if file2 has not changed.
755 .TP
756 .BI \-d " dest_offset"
757 Swap extents with open file beginning at
758 .IR dest_offset .
759 .TP
760 .B \-f
761 Flush changed file data and file metadata to disk.
762 .TP
763 .BI \-l " length"
764 Swap up to
765 .I length
766 bytes of data.
767 .TP
768 .B \-n
769 Perform all the parameter validation checks but don't change anything.
770 .TP
771 .BI \-s " src_offset"
772 Swap extents with donor file beginning at
773 .IR src_offset .
774 .TP
775 .B \-t
776 Print timing information.
777 .TP
778 .B \-w
779 Only exchange written ranges in the supplied file.
780 .RE
781 .PD
782 .TP
783 .BI "set_encpolicy [ \-c " mode " ] [ \-n " mode " ] [ \-f " flags " ] [ \-s " log2_dusize " ] [ \-v " version " ] [ " keyspec " ]"
784 On filesystems that support encryption, assign an encryption policy to the
785 current file.
786 .I keyspec
787 is a hex string which specifies the encryption key to use. For v1 encryption
788 policies,
789 .I keyspec
790 must be a 16-character hex string (8 bytes). For v2 policies,
791 .I keyspec
792 must be a 32-character hex string (16 bytes). If unspecified, an all-zeroes
793 value is used.
794 .RS 1.0i
795 .PD 0
796 .TP 0.4i
797 .BI \-c " mode"
798 contents encryption mode (e.g. AES-256-XTS)
799 .TP
800 .BI \-n " mode"
801 filenames encryption mode (e.g. AES-256-CTS)
802 .TP
803 .BI \-f " flags"
804 policy flags (numeric)
805 .TP
806 .BI \-s " log2_dusize"
807 log2 of data unit size. Not supported by v1 policies.
808 .TP
809 .BI \-v " version"
810 policy version. Defaults to 1 or 2 depending on the length of
811 .IR keyspec ;
812 or to 1 if
813 .I keyspec
814 is unspecified.
815 .RE
816 .PD
817 .TP
818 .BI "get_encpolicy [ \-1 ] [ \-t ]"
819 On filesystems that support encryption, display the encryption policy of the
820 current file.
821 .RS 1.0i
822 .PD 0
823 .TP 0.4i
824 .BI \-1
825 Use only the old ioctl to get the encryption policy. This only works if the
826 file has a v1 encryption policy.
827 .TP
828 .BI \-t
829 Test whether v2 encryption policies are supported. Prints "supported",
830 "unsupported", or an error message.
831 .RE
832 .PD
833 .TP
834 .BI "add_enckey [ \-d " descriptor " ] [ \-k " key_id " ]"
835 On filesystems that support encryption, add an encryption key to the filesystem
836 containing the currently open file. By default, the raw key in binary
837 (typically 64 bytes long) is read from standard input.
838 .RS 1.0i
839 .PD 0
840 .TP 0.4i
841 .BI \-d " descriptor"
842 key descriptor, as a 16-character hex string (8 bytes). If given, the key will
843 be available for use by v1 encryption policies that use this descriptor.
844 Otherwise, the key is added as a v2 policy key, and on success the resulting
845 "key identifier" will be printed.
846 .TP
847 .BI \-k " key_id"
848 ID of kernel keyring key of type "fscrypt-provisioning". If given, the raw key
849 will be taken from here rather than from standard input.
850 .RE
851 .PD
852 .TP
853 .BI "rm_enckey [ -a ] " keyspec
854 On filesystems that support encryption, remove an encryption key from the
855 filesystem containing the currently open file.
856 .I keyspec
857 is a hex string specifying the key to remove, as a 16-character "key descriptor"
858 or a 32-character "key identifier".
859 .RS 1.0i
860 .PD 0
861 .TP 0.4i
862 .BI \-a
863 Remove the key for all users who have added it, not just the current user. This
864 is a privileged operation.
865 .RE
866 .PD
867 .TP
868 .BI "enckey_status " keyspec
869 On filesystems that support encryption, display the status of an encryption key.
870 .I keyspec
871 is a hex string specifying the key for which to display the status, as a
872 16-character "key descriptor" or a 32-character "key identifier".
873 .TP
874 .BR lsattr " [ " \-R " | " \-D " | " \-a " | " \-v " ]"
875 List extended inode flags on the currently open file. If the
876 .B \-R
877 option is specified, a recursive descent is performed
878 for all directory entries below the currently open file
879 .RB ( \-D
880 can be used to restrict the output to directories only).
881 This is a depth first descent, it does not follow symlinks and
882 it also does not cross mount points.
883
884 The current inode flag letters are documented below.
885 Please refer to the
886 .BR ioctl_xfs_fsgetxattr "(2)"
887 documentation for more details about what they mean.
888
889 .PD 0
890 .RS
891 .TP 0.5i
892 .B r
893 realtime file (XFS_XFLAG_REALTIME)
894
895 .TP
896 .B p
897 prealloc (XFS_XFLAG_PREALLOC)
898
899 .TP
900 .B i
901 immutable (XFS_XFLAG_IMMUTABLE)
902
903 .TP
904 .B a
905 append only (XFS_XFLAG_APPEND)
906
907 .TP
908 .B s
909 synchronous file writes (XFS_XFLAG_SYNC)
910
911 .TP
912 .B A
913 noatime (XFS_XFLAG_NOATIME)
914
915 .TP
916 .B d
917 nodump (XFS_XFLAG_NODUMP)
918
919 .TP
920 .B t
921 inherit realtime flag (XFS_XFLAG_RTINHERIT)"
922
923 .TP
924 .B P
925 inherit project id (XFS_XFLAG_PROJINHERIT)
926
927 .TP
928 .B n
929 no symlink creation (XFS_XFLAG_NOSYMLINKS)
930
931 .TP
932 .B e
933 extent size hint (XFS_XFLAG_EXTSIZE)
934
935 .TP
936 .B E
937 inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)
938
939 .TP
940 .B f
941 nodefrag (XFS_XFLAG_NODEFRAG)
942
943 .TP
944 .B S
945 filestream allocator (XFS_XFLAG_FILESTREAM)
946
947 .TP
948 .B x
949 direct access persistent memory (XFS_XFLAG_DAX)
950
951 .TP
952 .B C
953 copy on write extent hint (XFS_XFLAG_COWEXTSIZE)
954
955 .TP
956 .B X
957 has extended attributes (XFS_XFLAG_HASATTR)
958 .RE
959
960 .TP
961 .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfSxC " ]"
962 Change extended inode flags on the currently open file. The
963 .B \-R
964 and
965 .B \-D
966 options have the same meaning as above.
967
968 See the
969 .B lsattr
970 command above for the list of inode flag letters.
971
972 .TP
973 .BI "flink " path
974 Link the currently open file descriptor into the filesystem namespace.
975 .TP
976 .BR stat " [ " \-v "|" \-r " ]"
977 Selected statistics from
978 .BR stat (2)
979 and the XFS_IOC_GETXATTR system call on the current file. If the
980 .B \-v
981 option is specified, the atime (last access), mtime
982 (last modify), and ctime (last change) timestamps are also displayed. The
983 .B \-r
984 option dumps raw fields from the stat structure.
985 .TP
986 .BI "statx [ \-v|\-r ][ \-m " basic " | \-m " all " | -m " <mask> " ][ \-FD ]"
987 Selected statistics from
988 .BR stat (2)
989 and the XFS_IOC_GETXATTR system call on the current file.
990 .RS 1.0i
991 .PD 0
992 .TP 0.4i
993 .B \-v
994 Show timestamps.
995 .TP
996 .B \-r
997 Dump raw statx structure values.
998 .TP
999 .B \-m basic
1000 Set the field mask for the statx call to STATX_BASIC_STATS.
1001 .TP
1002 .B \-m all
1003 Set all bits in the field mask for the statx call except for STATX__RESERVED.
1004 If no
1005 .B -m
1006 arguments are specified, the default is STATX_BASIC_STATS and STATX_BTIME.
1007 .TP
1008 .B \-m <mask>
1009 Specify a numeric field mask for the statx call.
1010 .TP
1011 .BI "\-m +" value
1012 Add this value to the statx field value.
1013 Values can be numeric, or they can be words describing the desired fields.
1014 See the help command output for a list of recognized words.
1015 .TP
1016 .BI "\-m -" value
1017 Remove this value from the statx field value.
1018 .TP
1019 .BI "\-m +" value ",-" value
1020 Add and remove multiple values from the statx field value.
1021 .TP
1022 .B \-F
1023 Force the attributes to be synced with the server.
1024 .TP
1025 .B \-D
1026 Don't sync attributes with the server.
1027 .PD
1028 .RE
1029 .TP
1030 .BR chproj " [ " \-R | \-D " ]"
1031 Modifies the project identifier associated with the current path. The
1032 .B \-R
1033 option will recursively descend if the current path is a directory. The
1034 .B \-D
1035 option will also recursively descend, only setting modifying projects
1036 on subdirectories. See the
1037 .BR xfs_quota (8)
1038 manual page for more information about project identifiers.
1039 .TP
1040 .BR lsproj " [ " \-R | \-D " ]"
1041 Displays the project identifier associated with the current path. The
1042 .B \-R
1043 and
1044 .B \-D
1045 options behave as described above, in
1046 .B chproj.
1047 .TP
1048 .BR parent " [ " \-fpz " ] [ " \-b " bufsize ] [ " \-i " ino ] [ " \-n " name ] [" " ino gen " "]"
1049 By default this command prints out the parent inode numbers,
1050 inode generation numbers and basenames of all the hardlinks which
1051 point to the inode of the current file.
1052
1053 If the optional
1054 .B ino
1055 and
1056 .B gen
1057 parameters are provided, they will be used to create a file handle on the same
1058 filesystem as the open file.
1059 The parents of the file represented by the handle will be reported instead of
1060 the open file.
1061
1062 .RS 1.0i
1063 .PD 0
1064 .TP 0.4i
1065 .B \-b
1066 Use a buffer of this size to receive parent pointer records from the kernel.
1067 .TP 0.4i
1068 .B \-i
1069 Only show parent pointer records containing this inode number.
1070 .TP 0.4i
1071 .B \-n
1072 Only show parent pointer records containing this directory entry name.
1073 .TP 0.4i
1074 .B \-p
1075 the output is similar to the default output except pathnames up to
1076 the mount-point are printed out instead of the component name.
1077 .TP
1078 .B \-s
1079 Print records in short format: ino/gen/namelen/name
1080 .TP
1081 .B \-z
1082 Print only the first path from the root.
1083 .RE
1084 .PD
1085 .TP
1086 .BI utimes " atime_sec atime_nsec mtime_sec mtime_nsec"
1087 The utimes command changes the atime and mtime of the current file.
1088 sec uses UNIX timestamp notation and is the seconds elapsed since
1089 1970-01-01 00:00:00 UTC.
1090 nsec is the nanoseconds since the sec. This value needs to be in
1091 the range 0-999999999 with UTIME_NOW and UTIME_OMIT being exceptions.
1092 Each (sec, nsec) pair constitutes a single timestamp value.
1093 .TP
1094 .BI "startupdate [ " -e ]
1095 Create a temporary clone of a file in which to stage file updates.
1096 The
1097 .B \-e
1098 option creates an empty staging file.
1099 .TP
1100 .B cancelupdate
1101 Abandon changes from a update staging file.
1102 .TP
1103 .BI "commitupdate [" OPTIONS ]
1104 Commit changes from a update staging file to the real file.
1105 .RS 1.0i
1106 .PD 0
1107 .TP 0.4i
1108 .B \-C
1109 Print timing information in a condensed format.
1110 .TP 0.4i
1111 .B \-h
1112 Only swap ranges in the update staging file that were actually written.
1113 .TP 0.4i
1114 .B \-k
1115 Do not change file size.
1116 .TP 0.4i
1117 .B \-n
1118 Check parameters without changing anything.
1119 .TP 0.4i
1120 .B \-q
1121 Do not print timing information at all.
1122 .PD
1123 .RE
1124 .TP
1125 .BI "cachestat off len
1126 Print page cache statistics for the given file range.
1127
1128 .SH MEMORY MAPPED I/O COMMANDS
1129 .TP
1130 .BI "mmap [ " N " | [[ \-rwxS ] [\-s " size " ] " "offset length " ]]
1131 With no arguments,
1132 .B mmap
1133 shows the current mappings. Specifying a single numeric argument
1134 .I N
1135 sets the current mapping. If two arguments are specified (a range specified by
1136 .I offset
1137 and
1138 .IR length ),
1139 a new mapping is created spanning the range, and the protection mode can
1140 be given as a combination of PROT_READ
1141 .RB ( \-r ),
1142 PROT_WRITE
1143 .RB ( \-w ),
1144 and PROT_EXEC
1145 .RB ( \-x ).
1146 The mapping will be created with the MAP_SHARED flag by default, or with the
1147 Linux specific (MAP_SYNC | MAP_SHARED_VALIDATE) flags if
1148 .B -S
1149 is given.
1150 .BI \-s " size"
1151 is used to do a mmap(size) && munmap(size) operation at first, try to reserve some
1152 extendible free memory space, if
1153 .I size
1154 is bigger than
1155 .I length
1156 parameter. But there's not guarantee that the memory after
1157 .I length
1158 ( up to
1159 .I size
1160 ) will stay free.
1161 .B e.g.
1162 "mmap -rw -s 8192 1024" will mmap 0 ~ 1024 bytes memory, but try to reserve 1024 ~ 8192
1163 free space(no guarantee). This free space will helpful for "mremap 8192" without
1164 MREMAP_MAYMOVE flag.
1165 .TP
1166 .B mm
1167 See the
1168 .B mmap
1169 command.
1170 .TP
1171 .BI "mremap [ \-f <new_address> ] [ \-m ] " new_length
1172 Changes the current mapping size to
1173 .IR new_length .
1174 Whether the mapping may be moved is controlled by the flags passed;
1175 MREMAP_FIXED
1176 .RB ( \-f ),
1177 or MREMAP_MAYMOVE
1178 .RB ( \-m ).
1179 .IR new_length
1180 specifies a page-aligned address to which the mapping must be moved. It
1181 can be set to 139946004389888, 4096k or 1g etc.
1182 .TP
1183 .B mrm
1184 See the
1185 .B mremap
1186 command.
1187 .TP
1188 .B munmap
1189 Unmaps the current memory mapping.
1190 .TP
1191 .B mu
1192 See the
1193 .B munmap
1194 command.
1195 .TP
1196 .BI "mread [ \-f | \-v ] [ \-r ] [" " offset length " ]
1197 Accesses a segment of the current memory mapping, optionally dumping it to
1198 the standard output stream (with
1199 .B \-v
1200 or
1201 .B \-f
1202 option) for inspection. The accesses are performed sequentially from the start
1203 .I offset
1204 by default, but can also be done from the end backwards through the
1205 mapping if the
1206 .B \-r
1207 option in specified.
1208 The two verbose modes differ only in the relative offsets they display, the
1209 .B \-f
1210 option is relative to file start, whereas
1211 .B \-v
1212 shows offsets relative to the start of the mapping.
1213 .TP
1214 .B mr
1215 See the
1216 .B mread
1217 command.
1218 .TP
1219 .BI "mwrite [ \-r ] [ \-S " seed " ] [ " "offset length " ]
1220 Stores a byte into memory for a range within a mapping.
1221 The default stored value is 'X', repeated to fill the range specified,
1222 but this can be changed using the
1223 .B \-S
1224 option.
1225 The memory stores are performed sequentially from the start offset by default,
1226 but can also be done from the end backwards through the mapping if the
1227 .B \-r
1228 option in specified.
1229 .TP
1230 .B mw
1231 See the
1232 .B mwrite
1233 command.
1234 .TP
1235 .BI "msync [ \-i ] [ \-a | \-s ] [ " "offset length " ]
1236 Writes all modified copies of pages over the specified range (or entire
1237 mapping if no range specified) to their backing storage locations.
1238 Also, optionally invalidates
1239 .RB ( \-i )
1240 so that subsequent references to the pages will be obtained from their
1241 backing storage locations (instead of cached copies).
1242 The flush can be done synchronously
1243 .RB ( \-s)
1244 or asynchronously
1245 .RB ( \-a ).
1246 .TP
1247 .B ms
1248 See the
1249 .B msync
1250 command.
1251 .TP
1252 .BI "madvise [ \-d | \-r | \-s | \-w ] [ " "offset length " ]
1253 Modifies page cache behavior when operating on the current mapping.
1254 The range arguments are required by some advise commands ([*] below).
1255 With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead).
1256 .RS 1.0i
1257 .PD 0
1258 .TP 0.4i
1259 .B \-d
1260 the pages will not be needed (POSIX_MADV_DONTNEED[*]).
1261 .TP
1262 .B \-r
1263 expect random page references (POSIX_MADV_RANDOM), which sets readahead to zero.
1264 .TP
1265 .B \-s
1266 expect sequential page references (POSIX_MADV_SEQUENTIAL),
1267 which doubles the default readahead on the file.
1268 .TP
1269 .B \-w
1270 advises the specified pages will be needed again (POSIX_MADV_WILLNEED[*])
1271 which forces the maximum readahead.
1272 .RE
1273 .PD
1274 .TP
1275 .B mincore
1276 Dumps a list of pages or ranges of pages that are currently in core,
1277 for the current memory mapping.
1278
1279 .SH FILESYSTEM COMMANDS
1280 .TP
1281 .BI "aginfo [ \-a " agno " ]"
1282 Show information about or update the state of allocation groups.
1283 .RE
1284 .RS 1.0i
1285 .PD 0
1286 .TP
1287 .BI \-a
1288 Act only on a specific allocation group.
1289 .PD
1290 .RE
1291
1292 .TP
1293 .BI "bulkstat [ \-a " agno " ] [ \-d ] [ \-e " endino " ] [ \-m ] [ \-n " batchsize " ] [ \-q ] [ \-s " startino " ] [ \-v " version" ]
1294 Display raw stat information about a bunch of inodes in an XFS filesystem.
1295 Options are as follows:
1296 .RS 1.0i
1297 .PD 0
1298 .TP
1299 .BI \-a " agno"
1300 Display only results from the given allocation group.
1301 If not specified, all results returned will be displayed.
1302 .TP
1303 .BI \-d
1304 Print debugging information about call results.
1305 .TP
1306 .BI \-e " endino"
1307 Stop displaying records when this inode number is reached.
1308 Defaults to stopping when the system call stops returning results.
1309 .TP
1310 .BI \-m
1311 Include metadata directories in the output.
1312 .TP
1313 .BI \-n " batchsize"
1314 Retrieve at most this many records per call.
1315 Defaults to 4,096.
1316 .TP
1317 .BI \-q
1318 Run quietly.
1319 Does not parse or output retrieved bulkstat information.
1320 .TP
1321 .BI \-s " startino"
1322 Display inode allocation records starting with this inode.
1323 Defaults to the first inode in the filesystem.
1324 If the given inode is not allocated, results will begin with the next allocated
1325 inode in the filesystem.
1326 .TP
1327 .BI \-v " version"
1328 Use a particular version of the kernel interface.
1329 Currently supported versions are 1 and 5.
1330 .RE
1331 .PD
1332 .TP
1333 .BI "bulkstat_single [ \-d ] [ \-m ] [ \-v " version " ] [ " inum... " | " special... " ]
1334 Display raw stat information about individual inodes in an XFS filesystem.
1335 The
1336 .BR \-d ,
1337 .BR \-m ,
1338 and
1339 .B \-v
1340 options are the same as the
1341 .B bulkstat
1342 command.
1343 Arguments must be inode numbers or any of the special values:
1344 .RS 1.0i
1345 .PD 0
1346 .TP
1347 .B root
1348 Display information about the root directory inode.
1349 .RE
1350 .PD
1351 .TP
1352 .B freeze
1353 Suspend all write I/O requests to the filesystem of the current file.
1354 Only available in expert mode and requires privileges.
1355 .TP
1356 .B thaw
1357 Undo the effects of a filesystem freeze operation.
1358 Only available in expert mode and requires privileges.
1359 .TP
1360 .BI "inject [ " tag " ]"
1361 Inject errors into a filesystem to observe filesystem behavior at
1362 specific points under adverse conditions. Without the
1363 .I tag
1364 argument, displays the list of error tags available.
1365 Only available in expert mode and requires privileges.
1366
1367 .TP
1368 .BI "rginfo [ \-r " rgno " ]"
1369 Show information about or update the state of realtime allocation groups.
1370 .RE
1371 .RS 1.0i
1372 .PD 0
1373 .TP
1374 .BI \-r
1375 Act only on a specific realtime group.
1376 .PD
1377 .RE
1378
1379 .TP
1380 .BI "resblks [ " blocks " ]"
1381 Get and/or set count of reserved filesystem blocks using the
1382 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls.
1383 Note \-\- this can be useful for exercising out of space behavior.
1384 Only available in expert mode and requires privileges.
1385 .TP
1386 .BR shutdown " [ " \-f " ]"
1387 Force the filesystem to shut down, preventing any further IO.
1388 XFS and other filesystems implement this functionality, although implementation
1389 details may differ slightly.
1390 Only available in expert mode and requires privileges.
1391 .PP
1392 .RS
1393 By default, the filesystem will not attempt to flush completed transactions to
1394 disk before shutting down the filesystem. This simulates a disk failure or
1395 crash.
1396 .RE
1397 .RS 1.0i
1398 .PD 0
1399 .TP 0.4i
1400 .B \-f
1401 Force the filesystem to flush all completed transactions to disk before shutting
1402 down, matching XFS behavior when critical corruption is encountered.
1403 .PD
1404 .RE
1405 .TP
1406 .B statfs [ -c ] [ -g ] [ -s ]
1407 Report selected statistics on the filesystem where the current file resides.
1408 The default behavior is to enable all three reporting options:
1409 .RS 1.0i
1410 .PD 0
1411 .TP
1412 .BI \-c
1413 Display
1414 .B XFS_IOC_FSCOUNTERS
1415 summary counter data.
1416 .TP
1417 .BI \-g
1418 Display
1419 .B XFS_IOC_FSGEOMETRY
1420 filesystem geometry data.
1421 .TP
1422 .BI \-s
1423 Display
1424 .BR statfs (2)
1425 data.
1426 .TP
1427 .RE
1428 .PD
1429 .TP
1430 .BI "inode [ [ -n ] " number " ] [ -v ]"
1431 The inode command queries physical information about an inode. With
1432 no arguments, it will return 1 or 0, indicating whether or not any
1433 inode numbers greater than 32 bits are currently in use in the filesystem.
1434 If given an inode
1435 .I number
1436 as an argument, the command will return the same inode
1437 .I number
1438 if it is in use, or 0 if not. With
1439 .BI \-n " number"
1440 , the next used inode number after this
1441 .I number
1442 will be returned, or zero if the supplied inode number is the highest one
1443 in use. With
1444 .B \-v
1445 the command will also report the number of bits (32 or 64) used by the
1446 inode
1447 .I number
1448 printed in the result; if no inode
1449 .I number
1450 was specified on the command line, the maximum possible inode number in
1451 the system will be printed along with its size.
1452 .PD
1453 .TP
1454 .BI "inumbers [ \-a " agno " ] [ \-d ] [ \-e " endino " ] [ \-n " batchsize " ] [ \-s " startino " ] [ \-v " version " ]
1455 Prints allocation information about groups of inodes in an XFS filesystem.
1456 Callers can use this information to figure out which inodes are allocated.
1457 Options are as follows:
1458 .RS 1.0i
1459 .PD 0
1460 .TP
1461 .BI \-a " agno"
1462 Display only results from the given allocation group.
1463 If not specified, all results returned will be displayed.
1464 .TP
1465 .BI \-d
1466 Print debugging information about call results.
1467 .TP
1468 .BI \-e " endino"
1469 Stop displaying records when this inode number is reached.
1470 Defaults to stopping when the system call stops returning results.
1471 .TP
1472 .BI \-n " batchsize"
1473 Retrieve at most this many records per call.
1474 Defaults to 4,096.
1475 .TP
1476 .BI \-s " startino"
1477 Display inode allocation records starting with this inode.
1478 Defaults to the first inode in the filesystem.
1479 If the given inode is not allocated, results will begin with the next allocated
1480 inode in the filesystem.
1481 .TP
1482 .BI \-v " version"
1483 Use a particular version of the kernel interface.
1484 Currently supported versions are 1 and 5.
1485 .RE
1486 .PD
1487 .TP
1488 .BI "scrub " type " [ " agnumber " | " rgnumber " | " "ino" " " "gen" " | " metapath " [ " rgnumber " ] ]"
1489 Scrub internal XFS filesystem metadata. The
1490 .BI type
1491 parameter specifies which type of metadata to scrub.
1492 For AG metadata, one AG number must be specified.
1493 For realtime group metadata, one rtgroup number must be specified.
1494 For file metadata, the scrub is applied to the open file unless the
1495 inode number and generation number are specified.
1496 For metapath, the name of a file or a raw number must be specified.
1497 If the metapath file is a per-rtgroup file, the group number must be specified.
1498 .RE
1499 .PD
1500 .TP
1501 .BI "scrubv [ \-b NN ] [ \-d ] [ \-m oflags ] [ \-r ] [ \-v NN ] [ \-w ms ] " group " [ " agnumber " | " "ino" " " "gen" " ]"
1502 Scrub a bunch of internal XFS filesystem metadata.
1503 The
1504 .BI group
1505 parameter specifies which group of metadata to scrub.
1506 Valid groups are
1507 .IR ag ", " agheader ", " inode ", " iscan ", " fs ", " probe ", " rtgroup ", or " summary .
1508
1509 For
1510 .BR ag " and " agheader
1511 metadata, one AG number must be specified.
1512 For
1513 .B inode
1514 metadata, the scrub is applied to the open file unless the
1515 inode number and generation number are specified.
1516 For
1517 .B rtgroup
1518 metadata, one rt group number must be specified.
1519
1520 .RS 1.0i
1521 .PD 0
1522 .TP
1523 .BI "\-b " NN
1524 Inject scrub barriers into the vector stream at the given interval.
1525 Barriers abort vector processing if any previous scrub function found
1526 corruption.
1527 .TP
1528 .BI \-d
1529 Enables debug mode.
1530 .TP
1531 .BI \-m
1532 Fail scrub barriers if any of these scrub output flags are seen.
1533 .TP
1534 .BI \-r
1535 Repair metadata if corruptions are found.
1536 This option requires expert mode.
1537 .TP
1538 .BI "\-v " NN
1539 Force a particular API version.
1540 .B single
1541 selects XFS_SCRUB_METADATA (one-by-one).
1542 .B vector
1543 selects XFS_SCRUBV_METADATA (vectored).
1544 If no option is specified, vector mode will be used, with a fallback to single
1545 mode if the kernel doesn't recognize the vector mode ioctl.
1546 .TP
1547 .BI "\-w " us
1548 Wait the given number of microseconds between each scrub function.
1549 .RE
1550 .PD
1551 .TP
1552 .BI "repair " type " [ " agnumber " | " "ino" " " "gen" " ]"
1553 Repair internal XFS filesystem metadata. The
1554 .BI type
1555 parameter specifies which type of metadata to repair.
1556 For AG metadata, one AG number must be specified.
1557 For file metadata, the repair is applied to the open file unless the
1558 inode number and generation number are specified.
1559 The
1560 .B -R
1561 option can be specified to force rebuilding of a metadata structure.
1562 .TP
1563 .BI "label" " " "[ -c | -s " label " ] "
1564 On filesystems that support online label manipulation, get, set, or clear the
1565 filesystem label. With no options, print the current filesystem label. The
1566 .B \-c
1567 option clears the filesystem label by setting it to the null string. The
1568 .BI "\-s " label
1569 option sets the filesystem label to
1570 .IR label .
1571 If the label is longer than the filesystem will accept,
1572 .B xfs_io
1573 will print an error message. XFS filesystem labels can be at most 12
1574 characters long.
1575 .TP
1576 .BI "fsmap [ \-d | \-l | \-r ] [ \-m | \-v ] [ \-n " nx " ] [ " start " ] [ " end " ]
1577 Prints the mapping of disk blocks used by the filesystem hosting the current
1578 file. The map lists each extent used by files, allocation group metadata,
1579 journalling logs, and static filesystem metadata, as well as any
1580 regions that are unused.
1581 Each line of the listings takes the following form:
1582 .PP
1583 .RS
1584 .IR extent ": " major ":" minor " [" startblock .. endblock "]: " owner " " startoffset .. endoffset " " length
1585 .PP
1586 Static filesystem metadata, allocation group metadata, btrees,
1587 journalling logs, and free space are marked by replacing the
1588 .IR startoffset .. endoffset
1589 with the appropriate marker.
1590 All blocks, offsets, and lengths are specified in units of 512-byte
1591 blocks, no matter what the filesystem's block size is.
1592 The optional
1593 .I start
1594 and
1595 .I end
1596 arguments can be used to constrain the output to a particular range of
1597 disk blocks.
1598 If these two options are specified, exactly one of
1599 .BR "-d" ", " "-l" ", or " "-r"
1600 must also be set.
1601 .RE
1602 .RS 1.0i
1603 .PD 0
1604 .TP
1605 .BI \-d
1606 Display only extents from the data device.
1607 This option only applies for XFS filesystems.
1608 .TP
1609 .BI \-l
1610 Display only extents from the external log device.
1611 This option only applies to XFS filesystems.
1612 .TP
1613 .BI \-r
1614 Display only extents from the realtime device.
1615 This option only applies to XFS filesystems.
1616 .TP
1617 .BI \-m
1618 Display results in a machine readable format (CSV).
1619 This option is not compatible with the
1620 .B \-v
1621 flag.
1622 The columns of the output are: extent number, device major, device minor,
1623 physical start, physical end, owner, offset start, offset end, length.
1624 The start, end, and length numbers are provided in units of 512b.
1625 The owner field is a special string that takes the form:
1626
1627 .RS 1.0i
1628 .PD 0
1629 .TP 0.4i
1630 .I inode_%lld_data
1631 for inode data.
1632 .TP
1633 .I inode_%lld_data_bmbt
1634 for inode data extent maps.
1635 .TP
1636 .I inode_%lld_attr
1637 for inode extended attribute data.
1638 .TP
1639 .I inode_%lld_attr_bmbt
1640 for inode extended attribute extent maps.
1641 .TP
1642 .I special_%u:%u
1643 for other filesystem metadata.
1644 .PD
1645 .RE
1646
1647 .TP
1648 .BI \-n " num_extents"
1649 If this option is given,
1650 .B fsmap
1651 obtains the extent list of the file in groups of
1652 .I num_extents
1653 extents.
1654 In the absence of
1655 .BR "-n" ", " "fsmap"
1656 queries the system for extents in groups of 131,072 records.
1657 .TP
1658 .B \-v
1659 Shows verbose information.
1660 When this flag is specified, additional AG specific information is
1661 appended to each line in the following form:
1662 .IP
1663 .RS 1.2i
1664 .IR agno " (" startagblock .. endagblock ") " nblocks " " flags
1665 .RE
1666 .IP
1667 A second
1668 .B \-v
1669 option will print out the
1670 .I flags
1671 legend.
1672 This option is not compatible with the
1673 .B \-m
1674 flag.
1675 .RE
1676 .PD
1677 .TP
1678 .B fsuuid
1679 Print the mounted filesystem UUID.
1680 .TP
1681 .B sysfspath
1682 Print the sysfs or debugfs path for the mounted filesystem.
1683
1684 The
1685 .B -d
1686 option selects debugfs instead of sysfs.
1687 .TP
1688 .BI "getfsprops " name " [ " names "... ]"
1689 Retrieve the values of the given filesystem properties.
1690 .TP
1691 .BI "listfsprops [ " \-v " ]"
1692 List all filesystem properties that have been stored in the filesystem.
1693 If the
1694 .B \-v
1695 flag is specified, prints the values of the properties.
1696 .TP
1697 .BI "setfsprops " name = value " [ " name = value "... ]"
1698 Set the given filesystem properties to the specified values.
1699 .TP
1700 .BI "removefsprops " name " [ " names "... ]"
1701 Remove the given filesystem properties.
1702
1703 .SH OTHER COMMANDS
1704 .TP
1705 .BR "help [ " command " ]"
1706 Display a brief description of one or all commands.
1707 .TP
1708 .B print
1709 Display a list of all open files and memory mapped regions.
1710 The current file and current mapping are distinguishable from
1711 any others.
1712 .TP
1713 .B p
1714 See the
1715 .B print
1716 command.
1717 .TP
1718 .B quit
1719 Exit
1720 .BR xfs_io .
1721 .TP
1722 .B q
1723 See the
1724 .B quit
1725 command.
1726 .TP
1727 .BI "log_writes \-d " device " \-m " mark
1728 Create a mark named
1729 .I mark
1730 in the dm-log-writes log specified by
1731 .I device.
1732 This is intended to be equivalent to the shell command:
1733
1734 .B dmsetup message
1735 .I device
1736 .B 0 mark
1737 .I mark
1738 .PD
1739 .RE
1740 .TP
1741 .B lw
1742 See the
1743 .B log_writes
1744 command.
1745 .TP
1746 .B crc32cselftest
1747 Test the internal crc32c implementation to make sure that it computes results
1748 correctly.
1749 .SH SEE ALSO
1750 .BR mkfs.xfs (8),
1751 .BR xfsctl (3),
1752 .BR xfs_bmap (8),
1753 .BR xfs_db (8),
1754 .BR xfs (5),
1755 .BR fdatasync (2),
1756 .BR fstat (2),
1757 .BR fstatfs (2),
1758 .BR fsync (2),
1759 .BR ftruncate (2),
1760 .BR futimens (3),
1761 .BR mmap (2),
1762 .BR msync (2),
1763 .BR open (2),
1764 .BR pread (2),
1765 .BR pwrite (2),
1766 .BR readdir (3),
1767 .BR dmsetup (8).