3 xfs_io \- debug the I/O path of an XFS filesystem
20 is a debugging tool like
22 but is aimed at examining the regular file I/O paths rather than the
23 raw XFS volume itself.
24 These code paths include not only the obvious read/write/mmap interfaces
25 for manipulating files, but also cover all of the XFS extensions (such
26 as space preallocation, additional inode flags, etc).
31 commands may be run interactively (the default) or as arguments on
32 the command line. Multiple
34 arguments may be given. The commands are run in the sequence given,
35 then the program exits.
38 Set the program name for prompts and some error messages,
45 if it does not already exist.
50 read-only, initially. This is required if
52 is immutable or append-only.
55 Expert mode. Dangerous commands are only available in this mode.
56 These commands also tend to require additional privileges.
59 Prints the version number and exits.
63 options described below are also available from the command line.
66 maintains a number of open files and memory mappings.
67 Files can be initially opened on the command line (optionally),
68 and additional files can also be opened later.
71 commands can be broken up into three groups.
72 Some commands are aimed at doing regular file I/O - read, write,
73 sync, space preallocation, etc.
75 The second set of commands exist for manipulating memory mapped regions
76 of a file - mapping, accessing, storing, unmapping, flushing, etc.
78 The remaining commands are for the navigation and display of data
79 structures relating to the open files, mappings, and the filesystems
82 Many commands have extensive online help. Use the
84 command for more details on any command.
88 Display a list of all open files and (optionally) switch to an alternate
91 .BI "open [[ \-acdfrstRT ] " path " ]"
92 Closes the current file, and opens the file specified by
94 instead. Without any arguments, displays statistics about the current
102 opens append-only (O_APPEND).
105 opens for direct I/O (O_DIRECT).
108 creates the file if it doesn't already exist (O_CREAT).
111 opens read-only (O_RDONLY).
114 opens for synchronous I/O (O_SYNC).
117 truncates on open (O_TRUNC).
120 opens in non-blocking mode if possible (O_NONBLOCK).
123 create a temporary file not linked into the filesystem namespace
124 (O_TMPFILE). The pathname passed must refer to a directory which
125 is treated as virtual parent for the newly created invisible file.
126 Can not be used together with the
131 marks the file as a realtime XFS file after
132 opening it, if it is not already marked as such.
142 Closes the current open file, marking the next open file as current
150 .BI "pread [ \-b " bsize " ] [ \-v ] [ \-FBR [ \-Z " seed " ] ] [ \-V " vectors " ] " "offset length"
151 Reads a range of bytes in a specified blocksize from the given
157 can be used to set the blocksize into which the
159 requests will be split. The default blocksize is 4096 bytes.
162 dump the contents of the buffer after reading,
163 by default only the count of bytes actually read is dumped.
166 read the buffers in a forwards sequential direction.
169 read the buffers in a reserve sequential direction.
172 read the buffers in the give range in a random order.
175 specify the random number seed used for random reads.
178 Use the vectored IO read syscall
180 with a number of blocksize length iovecs. The number of iovecs is set by the
191 .BI "pwrite [ \-i " file " ] [ \-d ] [ \-s " skip " ] [ \-b " size " ] [ \-S " seed " ] [ \-FBR [ \-Z " zeed " ] ] [ \-wW ] [ \-V " vectors " ] " "offset length"
192 Writes a range of bytes in a specified blocksize from the given
194 The bytes written can be either a set pattern or read in from another
202 to be specified as the source of the data to be written.
205 causes direct I/O, rather than the usual buffered
206 I/O, to be used when reading the input file.
209 specifies the number of bytes to
211 from the start of the input file before starting to read.
214 used to set the blocksize into which the
216 requests will be split. The default blocksize is 4096 bytes.
219 used to set the (repeated) fill pattern which
220 is used when the data to write is not coming from a file.
221 The default buffer fill pattern value is 0xcdcdcdcd.
224 write the buffers in a forwards sequential direction.
227 write the buffers in a reserve sequential direction.
230 write the buffers in the give range in a random order.
233 specify the random number seed used for random write
238 once all writes are complete (included in timing results)
243 once all writes are complete (included in timing results)
246 Use the vectored IO write syscall
248 with a number of blocksize length iovecs. The number of iovecs is set by the
259 .BI "bmap [ \-adlpv ] [ \-n " nx " ]"
260 Prints the block mapping for the current open file. Refer to the
262 manual page for complete documentation.
264 .BI "fiemap [ \-alv ] [ \-n " nx " ]"
265 Prints the block mapping for the current open file using the fiemap
266 ioctl. Options behave as described in the
270 .BI "extsize [ \-R | \-D ] [ " value " ]"
271 Display and/or modify the preferred extent size used when allocating
272 space for the currently open file. If the
274 option is specified, a recursive descent is performed
275 for all directory entries below the currently open file
277 can be used to restrict the output to directories only).
278 If the target file is a directory, then the inherited extent size
279 is set for that directory (new files created in that directory
280 inherit that extent size).
283 should be specified in bytes, or using one of the usual units suffixes
284 (k, m, g, b, etc). The extent size is always reported in units of bytes.
286 .BI "allocsp " size " 0"
287 Sets the size of the file to
289 and zeroes any additional space allocated using the
290 XFS_IOC_ALLOCSP/XFS_IOC_FREESP system call described in the
296 do exactly the same thing.
298 .BI "freesp " size " 0"
303 .BI "fadvise [ \-r | \-s | [[ \-d | \-n | \-w ] " "offset length " ]]
304 On platforms which support it, allows hints be given to the system
305 regarding the expected I/O patterns on the file.
306 The range arguments are required by some advise commands ([*] below), and
307 the others must have no range arguments.
308 With no arguments, the POSIX_FADV_NORMAL advice is implied (default readahead).
313 the data will not be accessed again in the near future (POSIX_FADV_DONTNEED[*]).
316 data will be accessed once and not be reused (POSIX_FADV_NOREUSE[*]).
319 expect access to data in random order (POSIX_FADV_RANDOM), which sets readahead to zero.
322 expect access to data in sequential order (POSIX_FADV_SEQUENTIAL),
323 which doubles the default readahead on the file.
326 advises the specified data will be needed again (POSIX_FADV_WILLNEED[*])
327 which forces the maximum readahead.
334 to flush the file's in-core data to disk.
339 to flush all in-core file state to disk.
346 .BI "sync_range [ \-a | \-b | \-w ] offset length "
347 On platforms which support it, allows control of syncing a range of the file to
348 disk. With no options, SYNC_FILE_RANGE_WRITE is implied on the range supplied.
353 wait for IO in the given range to finish after writing
354 (SYNC_FILE_RANGE_WAIT_AFTER).
357 wait for IO in the given range to finish before writing
358 (SYNC_FILE_RANGE_WAIT_BEFORE).
361 start writeback of dirty data in the given range (SYNC_FILE_RANGE_WRITE).
368 to flush all filesystems' in-core data to disk.
373 to flush this filesystem's in-core data to disk.
375 .BI resvsp " offset length"
376 Allocates reserved, unwritten space for part of a file using the
377 XFS_IOC_RESVSP system call described in the
381 .BI unresvsp " offset length"
382 Frees reserved space for part of a file using the XFS_IOC_UNRESVSP
383 system call described in the
387 .BI "falloc [ \-k ]" " offset length"
388 Allocates reserved, unwritten space for part of a file using the
389 fallocate routine as described in the
396 will set the FALLOC_FL_KEEP_SIZE flag as described in
401 .BI fcollapse " offset length"
402 Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described in the
404 manual page to de-allocates blocks and eliminates the hole created in this process
405 by shifting data blocks into the hole.
407 .BI finsert " offset length"
408 Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in the
410 manual page to create the hole by shifting data blocks.
412 .BI fpunch " offset length"
413 Punches (de-allocates) blocks in the file by calling fallocate with
414 the FALLOC_FL_PUNCH_HOLE flag as described in the
418 .BI fzero " offset length"
419 Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in the
421 manual page to allocate and zero blocks within the range.
423 .BI zero " offset length"
425 .B XFS_IOC_ZERO_RANGE
428 manual page to allocate and zero blocks within the range.
430 .BI truncate " offset"
431 Truncates the current file at the given offset using
434 .BI "sendfile \-i " srcfile " | \-f " N " [ " "offset length " ]
435 On platforms which support it, allows a direct in-kernel copy between
436 two file descriptors. The current open file is the target, the source
437 must be specified as another open file
442 .BI "readdir [ -v ] [ -o " offset " ] [ -l " length " ] "
443 Read a range of directory entries from a given offset of a directory.
448 verbose mode - dump dirent content as defined in
463 .BI "seek \-a | \-d | \-h [ \-r ] [ \-s ] offset"
464 On platforms that support the
469 options, display the offsets of the specified segments.
478 segments starting at the specified
484 segment starting at the specified
490 segment starting at the specified
494 Recursively display all the specified segments starting at the specified
498 Display the starting lseek(2) offset. This offset will be a calculated value when
499 both data and holes are displayed together or performing a recusively display.
504 .BI "reflink [ \-C ] [ \-q ] src_file [src_offset dst_offset length]"
505 On filesystems that support the
506 .B XFS_IOC_CLONE_RANGE
508 .B BTRFS_IOC_CLONE_RANGE
513 in the open file to the same physical blocks that are mapped at offset
517 , replacing any contents that may already have been there. If a program
518 writes into a reflinked block range of either file, the dirty blocks will be
519 cloned, written to, and remapped ("copy on write") in the affected file,
520 leaving the other file(s) unchanged. If src_offset, dst_offset, and length
521 are omitted, all contents of src_file will be reflinked into the open file.
526 Print timing statistics in a condensed format.
529 Do not print timing statistics at all.
534 .BI "dedupe [ \-C ] [ \-q ] src_file src_offset dst_offset length"
535 On filesystems that support the
536 .B XFS_IOC_FILE_EXTENT_SAME
538 .B BTRFS_IOC_FILE_EXTENT_SAME
543 in the open file to the same physical blocks that are mapped at offset
547 , but only if the contents of both ranges are identical. This is known as
548 block-based deduplication. If a program writes into a reflinked block range of
549 either file, the dirty blocks will be cloned, written to, and remapped ("copy
550 on write") in the affected file, leaving the other file(s) unchanged.
555 Print timing statistics in a condensed format.
558 Do not print timing statistics at all.
560 .SH MEMORY MAPPED I/O COMMANDS
562 .BI "mmap [ " N " | [[ \-rwx ] [\-s " size " ] " "offset length " ]]
565 shows the current mappings. Specifying a single numeric argument
567 sets the current mapping. If two arguments are specified (a range specified by
571 a new mapping is created spanning the range, and the protection mode can
572 be given as a combination of PROT_READ
579 is used to do a mmap(size) && munmap(size) operation at first, try to reserve some
580 extendible free memory space, if
584 parameter. But there's not guarantee that the memory after
590 "mmap -rw -s 8192 1024" will mmap 0 ~ 1024 bytes memory, but try to reserve 1024 ~ 8192
591 free space(no guarantee). This free space will helpful for "mremap 8192" without
599 .BI "mremap [ \-f <new_address> ] [ \-m ] " new_length
600 Changes the current mapping size to
602 Whether the mapping may be moved is controlled by the flags passed;
608 specifies a page-aligned address to which the mapping must be moved. It
609 can be setted to 139946004389888, 4096k or 1g etc.
617 Unmaps the current memory mapping.
624 .BI "mread [ \-f | \-v ] [ \-r ] [" " offset length " ]
625 Accesses a segment of the current memory mapping, optionally dumping it to
626 the standard output stream (with
630 option) for inspection. The accesses are performed sequentially from the start
632 by default, but can also be done from the end backwards through the
636 The two verbose modes differ only in the relative offsets they display, the
638 option is relative to file start, whereas
640 shows offsets relative to the start of the mapping.
647 .BI "mwrite [ \-r ] [ \-S " seed " ] [ " "offset length " ]
648 Stores a byte into memory for a range within a mapping.
649 The default stored value is 'X', repeated to fill the range specified,
650 but this can be changed using the
653 The memory stores are performed sequentially from the start offset by default,
654 but can also be done from the end backwards through the mapping if the
663 .BI "msync [ \-i ] [ \-a | \-s ] [ " "offset length " ]
664 Writes all modified copies of pages over the specified range (or entire
665 mapping if no range specified) to their backing storage locations.
666 Also, optionally invalidates
668 so that subsequent references to the pages will be obtained from their
669 backing storage locations (instead of cached copies).
670 The flush can be done synchronously
680 .BI "madvise [ \-d | \-r | \-s | \-w ] [ " "offset length " ]
681 Modifies page cache behavior when operating on the current mapping.
682 The range arguments are required by some advise commands ([*] below).
683 With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead).
688 the pages will not be needed (POSIX_MADV_DONTNEED[*]).
691 expect random page references (POSIX_MADV_RANDOM), which sets readahead to zero.
694 expect sequential page references (POSIX_MADV_SEQUENTIAL),
695 which doubles the default readahead on the file.
698 advises the specified pages will be needed again (POSIX_MADV_WILLNEED[*])
699 which forces the maximum readahead.
704 Dumps a list of pages or ranges of pages that are currently in core,
705 for the current memory mapping.
709 .BR "help [ " command " ]"
710 Display a brief description of one or all commands.
713 Display a list of all open files and memory mapped regions.
714 The current file and current mapping are distinguishable from
731 .BR lsattr " [ " \-R " | " \-D " | " \-a " | " \-v " ]"
732 List extended inode flags on the currently open file. If the
734 option is specified, a recursive descent is performed
735 for all directory entries below the currently open file
737 can be used to restrict the output to directories only).
738 This is a depth first descent, it does not follow symlinks and
739 it also does not cross mount points.
741 .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfS " ]"
742 Change extended inode flags on the currently open file. The
746 options have the same meaning as above. The mapping between each
747 letter and the inode flags (refer to
749 for the full list) is available via the
754 Suspend all write I/O requests to the filesystem of the current file.
755 Only available in expert mode and requires privileges.
758 Undo the effects of a filesystem freeze operation.
759 Only available in expert mode and requires privileges.
762 Link the currently open file descriptor into the filesystem namespace.
764 .BI "inject [ " tag " ]"
765 Inject errors into a filesystem to observe filesystem behavior at
766 specific points under adverse conditions. Without the
768 argument, displays the list of error tags available.
769 Only available in expert mode and requires privileges.
771 .BI "resblks [ " blocks " ]"
772 Get and/or set count of reserved filesystem blocks using the
773 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls.
774 Note \-\- this can be useful for exercising out of space behavior.
775 Only available in expert mode and requires privileges.
777 .BR shutdown " [ " \-f " ]"
778 Force the filesystem to shutdown (with or without flushing the log).
779 Only available in expert mode and requires privileges.
781 .BR stat " [ " \-v " ]"
782 Selected statistics from
784 and the XFS_IOC_GETXATTR system call on the current file. If the
786 option is specified, the atime (last access), mtime
787 (last modify), and ctime (last change) timestamps are also displayed.
790 Selected statistics from
792 and the XFS_IOC_FSGEOMETRY
793 system call on the filesystem where the current file resides.
795 .BR chproj " [ " \-R | \-D " ]"
796 Modifies the project identifier associated with the current path. The
798 option will recursively descend if the current path is a directory. The
800 option will also recursively descend, only setting modifying projects
801 on subdirectories. See the
803 manual page for more information about project identifiers.
805 .BR lsproj " [ " \-R | \-D " ]"
806 Displays the project identifier associated with the current path. The
810 options behave as described above, in
813 .BR parent " [ " \-cpv " ]"
814 By default this command prints out the parent inode numbers,
815 inode generation numbers and basenames of all the hardlinks which
816 point to the inode of the current file.
821 the output is similar to the default output except pathnames up to
822 the mount-point are printed out instead of the component name.
825 the file's filesystem will check all the parent attributes for consistency.
828 verbose output will be printed.
831 .B [NOTE: Not currently operational on Linux.]
projects / thirdparty / xfsprogs-dev.git / blob