# xfs_io

## NAME



           xfs_io - debug the I/O path of an XFS filesystem
    


## SYNOPSIS



           **xfs_io**[ **-adfimrRstxT**] [ **-c** _cmd_ ] ... [ **-C** _cmd_ ] ... [ **-p** _prog_ ]
           _[ file ]_
           **xfs_io -V**
    


## DESCRIPTION



           **xfs_io** is a debugging tool like xfs_db(8), but is aimed at
           examining the regular file I/O paths rather than the raw XFS
           volume itself.  These code paths include not only the obvious
           read/write/mmap interfaces for manipulating files, but also cover
           all of the XFS extensions (such as space preallocation, additional
           inode flags, etc).
    


## OPTIONS



           **xfs_io** commands may be run interactively (the default) or as
           arguments on the command line.  Interactive mode always runs
           commands on the current open file, whilst commands run from the
           command line may be repeated on all open files rather than just
           the current open file.  In general, open file iteration will occur
           for commands that operate on file content or state. In contrast,
           commands that operate on filesystem or system-wide state will only
           be run on the current file regardless of how many files are
           currently open.  Multiple arguments may be given on the command
           line and they are run in the sequence given. The program exits one
           all commands have been run.
    
           **-c** _cmd_ Run the specified command on all currently open files.  To
                  maintain compatibility with historical usage, commands that
                  can not be run on all open files will still be run but only
                  execute once on the current open file.  Multiple **-c**
                  arguments may be given and may be interleaved on the
                  command line in any order with **-C** commands.
    
           **-C** _cmd_ Run the specified command only on the current open file.
                  Multiple **-C** arguments may be given and may be interleaved
                  on the command line in any order with **-c** commands.
    
           **-p** _prog_
                  Set the program name for prompts and some error messages,
                  the default value is **xfs_io**.
    
           **-f** Create _file_ if it does not already exist.
    
           **-r** Open _file_ read-only, initially. This is required if _file_ is
                  immutable or append-only.
    
           **-i** Start an idle thread. The purpose of this idle thread is to
                  test io from a multi threaded process. With single threaded
                  process, the file table is not shared and file structs are
                  not reference counted.  Spawning an idle thread can help
                  detecting file struct reference leaks.
    
           **-x** Expert mode. Dangerous commands are only available in this
                  mode.  These commands also tend to require additional
                  privileges.
    
           **-V** Prints the version number and exits.
    
           The other open(2) options described below are also available from
           the command line.
    


## CONCEPTS



           **xfs_io** maintains a number of open files and memory mappings.
           Files can be initially opened on the command line (optionally),
           and additional files can also be opened later.
    
           **xfs_io** commands can be broken up into three groups.  Some commands
           are aimed at doing regular file I/O - read, write, sync, space
           preallocation, etc.
    
           The second set of commands exist for manipulating memory mapped
           regions of a file - mapping, accessing, storing, unmapping,
           flushing, etc.
    
           The remaining commands are for the navigation and display of data
           structures relating to the open files, mappings, and the
           filesystems where they reside.
    
           Many commands have extensive online help. Use the **help** command for
           more details on any command.
    


## FILE I/O COMMANDS



           **file [**_N_ **]**
                  Display a list of all open files and (optionally) switch to
                  an alternate current open file.
    
           **open [[ -acdfrstRTPL ]**_path_ **]**
                  Closes the current file, and opens the file specified by
                  _path_ instead. Without any arguments, displays statistics
                  about the current file - see the **stat** command.
                     **-a** opens append-only (O_APPEND).
                     **-d** opens for direct I/O (O_DIRECT).
                     **-f** creates the file if it doesn't already exist
                         (O_CREAT).
                     **-r** opens read-only (O_RDONLY).
                     **-s** opens for synchronous I/O (O_SYNC).
                     **-t** truncates on open (O_TRUNC).
                     **-n** opens in non-blocking mode if possible (O_NONBLOCK).
                     **-T** create a temporary file not linked into the
                         filesystem namespace (O_TMPFILE).  The pathname
                         passed must refer to a directory which is treated as
                         virtual parent for the newly created invisible file.
                         Can not be used together with the **-r** option.
                     **-R** marks the file as a realtime XFS file after opening
                         it, if it is not already marked as such.
                     **-P** opens the path as a referent only (O_PATH).  This is
                         incompatible with other flags specifying other O_xxx
                         flags apart from **-L**.
                     **-L** doesn't follow symlinks (O_NOFOLLOW).  This is
                         incompatible with other flags specifying other O_xxx
                         flags apart from **-P**.
    
           **o** See the **open** command.
    
           **close** Closes the current open file, marking the next open file as
                  current (if one exists).
    
           **c** See the **close** command.
    
           **chmod -r | -w**
                  Change the mode of the currently open file. The **-r** option
                  will set the file permissions to read-only (0444), whilst
                  the **-w** option will set the file permissions to read-write
                  (0644). This allows xfs_io to set up mismatches between the
                  file permissions and the open file descriptor read/write
                  mode to exercise permission checks inside various syscalls.
    
           **pread [ -b** _bsize_ **] [ -qUv ] [ -FBR [ -Z** _seed_ **] ] [ -V** _vectors_ **]**
           _offset length_
                  Reads a range of bytes in a specified blocksize from the
                  given _offset_.
                     **-b** can be used to set the blocksize into which the
                         read(2) requests will be split. The default
                         blocksize is 4096 bytes.
                     **-q** quiet mode, do not write anything to standard
                         output.
                     **-U** Perform the preadv2(2) call with _RWF_DONTCACHE_.
                     **-v** dump the contents of the buffer after reading, by
                         default only the count of bytes actually read is
                         dumped.
                     **-F** read the buffers in a forward sequential direction.
                     **-B** read the buffers in a reverse sequential direction.
                     **-R** read the buffers in the give range in a random
                         order.
                     **-Z seed**
                         specify the random number seed used for random
                         reads.
                     **-V vectors**
                         Use the vectored IO read syscall preadv(2) with a
                         number of blocksize length iovecs. The number of
                         iovecs is set by the _vectors_ parameter.
    
           **r** See the **pread** command.
    
           **pwrite [ -i** _file_ **] [ -qAdDwNOUW ] [ -s** _skip_ **] [ -b** _size_ **] [ -S**
           _seed_ **] [ -FBR [ -Z** _zeed_ **] ] [ -V** _vectors_ **]**_offset length_
                  Writes a range of bytes in a specified blocksize from the
                  given _offset_.  The bytes written can be either a set
                  pattern or read in from another file before writing.
                     **-i** allows an input _file_ to be specified as the source
                         of the data to be written.
                     **-q** quiet mode, do not write anything to standard
                         output.
                     **-d** causes direct I/O, rather than the usual buffered
                         I/O, to be used when reading the input file.
                     **-w** call fdatasync(2) once all writes are complete
                         (included in timing results)
                     **-N** Perform the pwritev2(2) call with _RWF_NOWAIT_.
                     **-D** Perform the pwritev2(2) call with _RWF_DSYNC_.
                     **-A** Perform the pwritev2(2) call with _RWF_ATOMIC_.
                     **-U** Perform the pwritev2(2) call with _RWF_DONTCACHE_.
                     **-O** perform pwrite once and return the (maybe partial)
                         bytes written.
                     **-W** call fsync(2) once all writes are complete (included
                         in timing results)
                     **-s** specifies the number of bytes to _skip_ from the start
                         of the input file before starting to read.
                     **-b** used to set the blocksize into which the write(2)
                         requests will be split. The default blocksize is
                         4096 bytes.
                     **-S** used to set the (repeated) fill pattern which is
                         used when the data to write is not coming from a
                         file.  The default buffer fill pattern value is
                         0xcdcdcdcd.
                     **-F** write the buffers in a forward sequential direction.
                     **-B** write the buffers in a reverse sequential direction.
                     **-R** write the buffers in the give range in a random
                         order.
                     **-Z seed**
                         specify the random number seed used for random write
                     **-V vectors**
                         Use the vectored IO write syscall pwritev(2) with a
                         number of blocksize length iovecs. The number of
                         iovecs is set by the _vectors_ parameter.
    
           **w** See the **pwrite** command.
    
           **bmap [ -adelpv ] [ -n** _nx_ **]**
                  Prints the block mapping for the current open file. Refer
                  to the xfs_bmap(8) manual page for complete documentation.
    
           **fiemap [ -alv ] [ -n** _nx_ **] [**_offset_ **[**_len_ **]]**
                  Prints the block mapping for the current open file using
                  the fiemap ioctl.  Options behave as described in the
                  xfs_bmap(8) manual page.
    
                  Optionally, this command also supports passing the start
                  offset from where to begin the mapping and the length of
                  that region.  The kernel will return any full extents which
                  intersect with the requested range, and the **fiemap** command
                  will print them in their entirety.  If the requested range
                  starts or ends in a hole, **fiemap** will print the hole,
                  truncated to the requested range.
    
           **extsize [ -R | -D ] [**_value_ **]**
                  Display and/or modify the preferred extent size used when
                  allocating space for the currently open file. If the **-R**
                  option is specified, a recursive descent is performed for
                  all directory entries below the currently open file (**-D** can
                  be used to restrict the output to directories only).  If
                  the target file is a directory, then the inherited extent
                  size is set for that directory (new files created in that
                  directory inherit that extent size).  The _value_ should be
                  specified in bytes, or using one of the usual units
                  suffixes (k, m, g, b, etc). The extent size is always
                  reported in units of bytes.
    
           **cowextsize [ -R | -D ] [**_value_ **]**
                  Display and/or modify the preferred copy-on-write extent
                  size used when allocating space for the currently open
                  file. If the **-R** option is specified, a recursive descent is
                  performed for all directory entries below the currently
                  open file (**-D** can be used to restrict the output to
                  directories only).  If the target file is a directory, then
                  the inherited CoW extent size is set for that directory
                  (new files created in that directory inherit that CoW
                  extent size).  The _value_ should be specified in bytes, or
                  using one of the usual units suffixes (k, m, g, b, etc).
                  The extent size is always reported in units of bytes.
    
           **allocsp** _size_ **0**
                  Sets the size of the file to _size_ and zeroes any additional
                  space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP
                  system call described in the xfsctl(3) manual page.
                  **allocsp** and **freesp** do exactly the same thing.
    
                  These commands are no longer supported as of Linux 5.17.
    
           **freesp** _size_ **0**
                  See the **allocsp** command.
    
           **fadvise [ -r | -s | [[ -d | -n | -w ]**_offset length_ **]]**
                  On platforms which support it, allows hints be given to the
                  system regarding the expected I/O patterns on the file.
                  The range arguments are required by some advise commands
                  ([*] below), and the others must have no range arguments.
                  With no arguments, the POSIX_FADV_NORMAL advice is implied
                  (default readahead).
                     **-d** the data will not be accessed again in the near
                         future (POSIX_FADV_DONTNEED[*]).
                     **-n** data will be accessed once and not be reused
                         (POSIX_FADV_NOREUSE[*]).
                     **-r** expect access to data in random order
                         (POSIX_FADV_RANDOM), which sets readahead to zero.
                     **-s** expect access to data in sequential order
                         (POSIX_FADV_SEQUENTIAL), which doubles the default
                         readahead on the file.
                     **-w** advises the specified data will be needed again
                         (POSIX_FADV_WILLNEED[*]) which forces the maximum
                         readahead.
    
           **fdatasync**
                  Calls fdatasync(2) to flush the file's in-core data to
                  disk.
    
           **fsync** Calls fsync(2) to flush all in-core file state to disk.
    
           **s** See the **fsync** command.
    
           **sync_range [ -a | -b | -w ] offset length**
                  On platforms which support it, allows control of syncing a
                  range of the file to disk. With no options,
                  SYNC_FILE_RANGE_WRITE is implied on the range supplied.
                     **-a** wait for IO in the given range to finish after
                         writing (SYNC_FILE_RANGE_WAIT_AFTER).
                     **-b** wait for IO in the given range to finish before
                         writing (SYNC_FILE_RANGE_WAIT_BEFORE).
                     **-w** start writeback of dirty data in the given range
                         (SYNC_FILE_RANGE_WRITE).
    
           **sync** Calls sync(2) to flush all filesystems' in-core data to
                  disk.
    
           **syncfs** Calls syncfs(2) to flush this filesystem's in-core data to
                  disk.
    
           **resvsp** _offset length_
                  Allocates reserved, unwritten space for part of a file
                  using the XFS_IOC_RESVSP system call described in the
                  xfsctl(3) manual page.
    
           **unresvsp** _offset length_
                  Frees reserved space for part of a file using the
                  XFS_IOC_UNRESVSP system call described in the xfsctl(3)
                  manual page.
    
           **falloc [ -k ]**_offset length_
                  Allocates reserved, unwritten space for part of a file
                  using the fallocate routine as described in the
                  fallocate(2) manual page.
                     **-k** will set the FALLOC_FL_KEEP_SIZE flag as described
                         in fallocate(2).
    
           **fcollapse** _offset length_
                  Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as
                  described in the fallocate(2) manual page to de-allocates
                  blocks and eliminates the hole created in this process by
                  shifting data blocks into the hole.
    
           **finsert** _offset length_
                  Call fallocate with FALLOC_FL_INSERT_RANGE flag as
                  described in the fallocate(2) manual page to create the
                  hole by shifting data blocks.
    
           **fpunch** _offset length_
                  Punches (de-allocates) blocks in the file by calling
                  fallocate with the FALLOC_FL_PUNCH_HOLE flag as described
                  in the fallocate(2) manual page.
    
           **funshare** _offset length_
                  Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as
                  described in the fallocate(2) manual page to unshare all
                  shared blocks within the range.
    
           **fzero [ -k ]**_offset length_
                  Call fallocate with FALLOC_FL_ZERO_RANGE flag as described
                  in the fallocate(2) manual page to allocate and zero blocks
                  within the range.  With the **-k** option, use the
                  FALLOC_FL_KEEP_SIZE flag as well.
    
           **zero** _offset length_
                  Call xfsctl with **XFS_IOC_ZERO_RANGE** as described in the
                  xfsctl(3) manual page to allocate and zero blocks within
                  the range.
    
           **truncate** _offset_
                  Truncates the current file at the given offset using
                  ftruncate(2).
    
           **sendfile [ -q ] -i** _srcfile_ **| -f** _N_ **[**_offset length_ **]**
                  On platforms which support it, allows a direct in-kernel
                  copy between two file descriptors. The current open file is
                  the target, the source must be specified as another open
                  file (**-f**) or by path (**-i**).
                     **-q** quiet mode, do not write anything to standard output.
    
           **readdir [ -v ] [ -o** _offset_ **] [ -l** _length_ **]**
                  Read a range of directory entries from a given offset of a
                  directory.
                     **-v** verbose mode - dump dirent content as defined in
                         readdir(3)
                     **-o** specify starting _offset_
                     **-l** specify total _length_ to read (in bytes)
    
           **seek  -a | -d | -h [ -r ] [ -s ] offset**
                  On platforms that support the lseek(2) **SEEK_DATA** and
                  **SEEK_HOLE** options, display the offsets of the specified
                  segments.
                     **-a** Display both **data** and **hole** segments starting at the
                         specified **offset.**
                     **-d** Display the **data** segment starting at the specified
                         **offset.**
                     **-h** Display the **hole** segment starting at the specified
                         **offset.**
                     **-r** Recursively display all the specified segments
                         starting at the specified **offset.**
                     **-s** Display the starting lseek(2) offset. This offset
                         will be a calculated value when both data and holes
                         are displayed together or performing a recusively
                         display.
    
           **reflink  [ -C ] [ -q ] src_file [src_offset dst_offset length]**
                  On filesystems that support the **FICLONERANGE** or
                  **BTRFS_IOC_CLONE_RANGE** ioctls, map _length_ bytes at offset
                  _dst_offset_ in the open file to the same physical blocks
                  that are mapped at offset _src_offset_ in the file _src_file_ ,
                  replacing any contents that may already have been there.
                  If a program writes into a reflinked block range of either
                  file, the dirty blocks will be cloned, written to, and
                  remapped ("copy on write") in the affected file, leaving
                  the other file(s) unchanged.  If src_offset, dst_offset,
                  and length are omitted, all contents of src_file will be
                  reflinked into the open file.
                     **-C** Print timing statistics in a condensed format.
                     **-q** Do not print timing statistics at all.
    
           **dedupe  [ -C ] [ -q ] src_file src_offset dst_offset length**
                  On filesystems that support the **FIDEDUPERANGE** or
                  **BTRFS_IOC_FILE_EXTENT_SAME** ioctls, map _length_ bytes at
                  offset _dst_offset_ in the open file to the same physical
                  blocks that are mapped at offset _src_offset_ in the file
                  _src_file_ , but only if the contents of both ranges are
                  identical.  This is known as block-based deduplication.  If
                  a program writes into a reflinked block range of either
                  file, the dirty blocks will be cloned, written to, and
                  remapped ("copy on write") in the affected file, leaving
                  the other file(s) unchanged.
                     **-C** Print timing statistics in a condensed format.
                     **-q** Do not print timing statistics at all.
    
           **copy_range [ -s** _src_offset_ **] [ -d** _dst_offset_ **] [ -l** _length_ **]**
           **src_file | -f** _N_
                  On filesystems that support the copy_file_range(2) system
                  call, copies data from the source file into the current
                  open file.  The source must be specified either by path
                  (**src_file**) or as another open file (**-f**).  If _length_ is not
                  specified, this command copies data from _src_offset_ to the
                  end of **src_file** into the dst_file at _dst_offset_.
                     **-s** Copy data from _src_file_ beginning from _src_offset_.
                     **-d** Copy data into the open file beginning at
                         _dst_offset_.
                     **-l** Copy up to _length_ bytes of data.
    
           **swapext** _donor_file_
                  Swaps extent forks between files. The current open file is
                  the target. The donor file is specified by path. Note that
                  file data is not copied (file content moves with the
                  fork(s)).
    
           **exchangerange [OPTIONS]**_donor_file_
                  Exchanges contents between files.  The current open file is
                  the target.  The donor file is specified by path.  Note
                  that file data is not copied (file content moves with the
                  fork(s)).  Options include:
                     **-C** Print timing information in a condensed format.
                     **-c** Exchange contents only if file2 has not changed.
                     **-d** _dest_offset_
                         Swap extents with open file beginning at
                         _dest_offset_.
                     **-f** Flush changed file data and file metadata to disk.
                     **-l** _length_
                         Swap up to _length_ bytes of data.
                     **-n** Perform all the parameter validation checks but
                         don't change anything.
                     **-s** _src_offset_
                         Swap extents with donor file beginning at
                         _src_offset_.
                     **-t** Print timing information.
                     **-w** Only exchange written ranges in the supplied file.
    
           **set_encpolicy [ -c** _mode_ **] [ -n** _mode_ **] [ -f** _flags_ **] [ -s**
           _log2_dusize_ **] [ -v** _version_ **] [**_keyspec_ **]**
                  On filesystems that support encryption, assign an
                  encryption policy to the current file.  _keyspec_ is a hex
                  string which specifies the encryption key to use.  For v1
                  encryption policies, _keyspec_ must be a 16-character hex
                  string (8 bytes).  For v2 policies, _keyspec_ must be a
                  32-character hex string (16 bytes).  If unspecified, an
                  all-zeroes value is used.
                     **-c** _mode_
                         contents encryption mode (e.g. AES-256-XTS)
                     **-n** _mode_
                         filenames encryption mode (e.g. AES-256-CTS)
                     **-f** _flags_
                         policy flags (numeric)
                     **-s** _log2_dusize_
                         log2 of data unit size.  Not supported by v1
                         policies.
                     **-v** _version_
                         policy version.  Defaults to 1 or 2 depending on the
                         length of _keyspec_ ; or to 1 if _keyspec_ is
                         unspecified.
    
           **get_encpolicy [ -1 ] [ -t ]**
                  On filesystems that support encryption, display the
                  encryption policy of the current file.
                     **-1** Use only the old ioctl to get the encryption policy.
                         This only works if the file has a v1 encryption
                         policy.
                     **-t** Test whether v2 encryption policies are supported.
                         Prints "supported", "unsupported", or an error
                         message.
    
           **add_enckey [ -d** _descriptor_ **] [ -k** _key_id_ **]**
                  On filesystems that support encryption, add an encryption
                  key to the filesystem containing the currently open file.
                  By default, the raw key in binary (typically 64 bytes long)
                  is read from standard input.
                     **-d** _descriptor_
                         key descriptor, as a 16-character hex string (8
                         bytes).  If given, the key will be available for use
                         by v1 encryption policies that use this descriptor.
                         Otherwise, the key is added as a v2 policy key, and
                         on success the resulting "key identifier" will be
                         printed.
                     **-k** _key_id_
                         ID of kernel keyring key of type "fscrypt-
                         provisioning".  If given, the raw key will be taken
                         from here rather than from standard input.
    
           **rm_enckey [ -a ]**_keyspec_
                  On filesystems that support encryption, remove an
                  encryption key from the filesystem containing the currently
                  open file.  _keyspec_ is a hex string specifying the key to
                  remove, as a 16-character "key descriptor" or a
                  32-character "key identifier".
                     **-a** Remove the key for all users who have added it, not
                         just the current user.  This is a privileged
                         operation.
    
           **enckey_status** _keyspec_
                  On filesystems that support encryption, display the status
                  of an encryption key.  _keyspec_ is a hex string specifying
                  the key for which to display the status, as a 16-character
                  "key descriptor" or a 32-character "key identifier".
    
           **lsattr**[ **-R** | **-D** | **-a** | **-v**]
                  List extended inode flags on the currently open file. If
                  the **-R** option is specified, a recursive descent is
                  performed for all directory entries below the currently
                  open file (**-D** can be used to restrict the output to
                  directories only).  This is a depth first descent, it does
                  not follow symlinks and it also does not cross mount
                  points.
    
                  The current inode flag letters are documented below.
                  Please refer to the ioctl_xfs_fsgetxattr(2) documentation
                  for more details about what they mean.
    
                  **r** realtime file (XFS_XFLAG_REALTIME)
    
                  **p** prealloc (XFS_XFLAG_PREALLOC)
    
                  **i** immutable (XFS_XFLAG_IMMUTABLE)
    
                  **a** append only (XFS_XFLAG_APPEND)
    
                  **s** synchronous file writes (XFS_XFLAG_SYNC)
    
                  **A** noatime (XFS_XFLAG_NOATIME)
    
                  **d** nodump (XFS_XFLAG_NODUMP)
    
                  **t** inherit realtime flag (XFS_XFLAG_RTINHERIT)"
    
                  **P** inherit project id (XFS_XFLAG_PROJINHERIT)
    
                  **n** no symlink creation (XFS_XFLAG_NOSYMLINKS)
    
                  **e** extent size hint (XFS_XFLAG_EXTSIZE)
    
                  **E** inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)
    
                  **f** nodefrag (XFS_XFLAG_NODEFRAG)
    
                  **S** filestream allocator (XFS_XFLAG_FILESTREAM)
    
                  **x** direct access persistent memory (XFS_XFLAG_DAX)
    
                  **C** copy on write extent hint (XFS_XFLAG_COWEXTSIZE)
    
                  **X** has extended attributes (XFS_XFLAG_HASATTR)
    
           **chattr**[ **-R** | **-D**] [ **+** /**-riasAdtPneEfSxC**]
                  Change extended inode flags on the currently open file. The
                  **-R** and **-D** options have the same meaning as above.
    
                  See the **lsattr** command above for the list of inode flag
                  letters.
    
           **flink** _path_
                  Link the currently open file descriptor into the filesystem
                  namespace.
           **stat**[ **-v** |**-r**]
                  Selected statistics from stat(2) and the XFS_IOC_GETXATTR
                  system call on the current file. If the **-v** option is
                  specified, the atime (last access), mtime (last modify),
                  and ctime (last change) timestamps are also displayed.  The
                  **-r** option dumps raw fields from the stat structure.
           **statx [ -v|-r ][ -m** _basic_ **| -m** _all_ **| -m** _< mask>_ **][ -FD ]**
                  Selected statistics from stat(2) and the XFS_IOC_GETXATTR
                  system call on the current file.
                     **-v** Show timestamps.
                     **-r** Dump raw statx structure values.
                     **-m basic**
                         Set the field mask for the statx call to
                         STATX_BASIC_STATS.
                     **-m all**
                         Set all bits in the field mask for the statx call
                         except for STATX__RESERVED.  If no **-m** arguments are
                         specified, the default is STATX_BASIC_STATS and
                         STATX_BTIME.
                     **-m <mask>**
                         Specify a numeric field mask for the statx call.
                     **-m +**_value_
                         Add this value to the statx field value.  Values can
                         be numeric, or they can be words describing the
                         desired fields.  See the help command output for a
                         list of recognized words.
                     **-m -**_value_
                         Remove this value from the statx field value.
                     **-m +**_value_**,-**_value_
                         Add and remove multiple values from the statx field
                         value.
                     **-F** Force the attributes to be synced with the server.
                     **-D** Don't sync attributes with the server.
    
           **chproj**[ **-R** |**-D**]
                  Modifies the project identifier associated with the current
                  path. The **-R** option will recursively descend if the current
                  path is a directory. The **-D** option will also recursively
                  descend, only setting modifying projects on subdirectories.
                  See the xfs_quota(8) manual page for more information about
                  project identifiers.
    
           **lsproj**[ **-R** |**-D**]
                  Displays the project identifier associated with the current
                  path. The **-R** and **-D** options behave as described above, in
                  **chproj.**
    
           **parent**[ **-fpz**] [ **-b** bufsize ] [ **-i** ino ] [ **-n** name ] [ **ino gen**]
                  By default this command prints out the parent inode
                  numbers, inode generation numbers and basenames of all the
                  hardlinks which point to the inode of the current file.
    
                  If the optional **ino** and **gen** parameters are provided, they
                  will be used to create a file handle on the same filesystem
                  as the open file.  The parents of the file represented by
                  the handle will be reported instead of the open file.
    
                     **-b** Use a buffer of this size to receive parent pointer
                         records from the kernel.
                     **-i** Only show parent pointer records containing this
                         inode number.
                     **-n** Only show parent pointer records containing this
                         directory entry name.
                     **-p** the output is similar to the default output except
                         pathnames up to the mount-point are printed out
                         instead of the component name.
                     **-s** Print records in short format: ino/gen/namelen/name
                     **-z** Print only the first path from the root.
    
           **utimes** _atime_sec atime_nsec mtime_sec mtime_nsec_
                  The utimes command changes the atime and mtime of the
                  current file.  sec uses UNIX timestamp notation and is the
                  seconds elapsed since 1970-01-01 00:00:00 UTC.  nsec is the
                  nanoseconds since the sec. This value needs to be in the
                  range 0-999999999 with UTIME_NOW and UTIME_OMIT being
                  exceptions.  Each (sec, nsec) pair constitutes a single
                  timestamp value.
    
           **startupdate [**_-e_**]**
                  Create a temporary clone of a file in which to stage file
                  updates.  The **-e** option creates an empty staging file.
    
           **cancelupdate**
                  Abandon changes from a update staging file.
    
           **commitupdate [**_OPTIONS_**]**
                  Commit changes from a update staging file to the real file.
                     **-C** Print timing information in a condensed format.
                     **-h** Only swap ranges in the update staging file that
                         were actually written.
                     **-k** Do not change file size.
                     **-n** Check parameters without changing anything.
                     **-q** Do not print timing information at all.
    
           **cachestat off len**
                  Print page cache statistics for the given file range.
    


## MEMORY MAPPED I/O COMMANDS



           **mmap [**_N_ **| [[ -rwxS ] [-s** _size_ **]**_offset length_ **]]**
                  With no arguments, **mmap** shows the current mappings.
                  Specifying a single numeric argument _N_ sets the current
                  mapping. If two arguments are specified (a range specified
                  by _offset_ and _length_), a new mapping is created spanning
                  the range, and the protection mode can be given as a
                  combination of PROT_READ (**-r**), PROT_WRITE (**-w**), and
                  PROT_EXEC (**-x**).  The mapping will be created with the
                  MAP_SHARED flag by default, or with the Linux specific
                  (MAP_SYNC | MAP_SHARED_VALIDATE) flags if **-S** is given.  **-s**
                  _size_ is used to do a mmap(size) && munmap(size) operation
                  at first, try to reserve some extendible free memory space,
                  if _size_ is bigger than _length_ parameter. But there's not
                  guarantee that the memory after _length_ ( up to _size_ ) will
                  stay free.  **e.g.** "mmap -rw -s 8192 1024" will mmap 0 ~
                  1024 bytes memory, but try to reserve 1024 ~ 8192 free
                  space(no guarantee). This free space will helpful for
                  "mremap 8192" without MREMAP_MAYMOVE flag.
    
           **mm** See the **mmap** command.
    
           **mremap [ -f <new_address> ] [ -m ] **_new_length_
                  Changes the current mapping size to _new_length_.  Whether
                  the mapping may be moved is controlled by the flags passed;
                  MREMAP_FIXED (**-f**), or MREMAP_MAYMOVE (**-m**).  _new_length_
                  specifies a page-aligned address to which the mapping must
                  be moved. It can be set to 139946004389888, 4096k or 1g
                  etc.
    
           **mrm** See the **mremap** command.
    
           **munmap** Unmaps the current memory mapping.
    
           **mu** See the **munmap** command.
    
           **mread [ -f | -v ] [ -r ] [**_offset length_ **]**
                  Accesses a segment of the current memory mapping,
                  optionally dumping it to the standard output stream (with
                  **-v** or **-f** option) for inspection. The accesses are performed
                  sequentially from the start _offset_ by default, but can also
                  be done from the end backwards through the mapping if the
                  **-r** option in specified.  The two verbose modes differ only
                  in the relative offsets they display, the **-f** option is
                  relative to file start, whereas **-v** shows offsets relative
                  to the start of the mapping.
    
           **mr** See the **mread** command.
    
           **mwrite [ -r ] [ -S** _seed_ **] [**_offset length_ **]**
                  Stores a byte into memory for a range within a mapping.
                  The default stored value is 'X', repeated to fill the range
                  specified, but this can be changed using the **-S** option.
                  The memory stores are performed sequentially from the start
                  offset by default, but can also be done from the end
                  backwards through the mapping if the **-r** option in
                  specified.
    
           **mw** See the **mwrite** command.
    
           **msync [ -i ] [ -a | -s ] [**_offset length_ **]**
                  Writes all modified copies of pages over the specified
                  range (or entire mapping if no range specified) to their
                  backing storage locations.  Also, optionally invalidates
                  (**-i**) so that subsequent references to the pages will be
                  obtained from their backing storage locations (instead of
                  cached copies).  The flush can be done synchronously (**-s)**
                  or asynchronously (**-a**).
    
           **ms** See the **msync** command.
    
           **madvise [ -d | -r | -s | -w ] [**_offset length_ **]**
                  Modifies page cache behavior when operating on the current
                  mapping.  The range arguments are required by some advise
                  commands ([*] below).  With no arguments, the
                  POSIX_MADV_NORMAL advice is implied (default readahead).
                     **-d** the pages will not be needed
                         (POSIX_MADV_DONTNEED[*]).
                     **-r** expect random page references (POSIX_MADV_RANDOM),
                         which sets readahead to zero.
                     **-s** expect sequential page references
                         (POSIX_MADV_SEQUENTIAL), which doubles the default
                         readahead on the file.
                     **-w** advises the specified pages will be needed again
                         (POSIX_MADV_WILLNEED[*]) which forces the maximum
                         readahead.
    
           **mincore**
                  Dumps a list of pages or ranges of pages that are currently
                  in core, for the current memory mapping.
    


## FILESYSTEM COMMANDS



           **aginfo [ -a** _agno_ **]**
                  Show information about or update the state of allocation
                  groups.
                     **-a** Act only on a specific allocation group.
    
           **bulkstat [ -a** _agno_ **] [ -d ] [ -e** _endino_ **] [ -m ] [ -n** _batchsize_ **]**
           **[ -q ] [ -s** _startino_ **] [ -v** _version"_**]**
                  Display raw stat information about a bunch of inodes in an
                  XFS filesystem.  Options are as follows:
                     **-a** _agno_
                            Display only results from the given allocation
                            group.  If not specified, all results returned
                            will be displayed.
                     **-d** Print debugging information about call results.
                     **-e** _endino_
                            Stop displaying records when this inode number is
                            reached.  Defaults to stopping when the system
                            call stops returning results.
                     **-m** Include metadata directories in the output.
                     **-n** _batchsize_
                            Retrieve at most this many records per call.
                            Defaults to 4,096.
                     **-q** Run quietly.  Does not parse or output retrieved
                            bulkstat information.
                     **-s** _startino_
                            Display inode allocation records starting with
                            this inode.  Defaults to the first inode in the
                            filesystem.  If the given inode is not allocated,
                            results will begin with the next allocated inode
                            in the filesystem.
                     **-v** _version_
                            Use a particular version of the kernel interface.
                            Currently supported versions are 1 and 5.
    
           **bulkstat_single [ -d ] [ -m ] [ -v** _version_ **] [**_inum..._ **|**
           _special..._ **]**
                  Display raw stat information about individual inodes in an
                  XFS filesystem.  The **-d** , **-m** , and **-v** options are the same as
                  the **bulkstat** command.  Arguments must be inode numbers or
                  any of the special values:
                     **root** Display information about the root directory
                            inode.
    
           **freeze** Suspend all write I/O requests to the filesystem of the
                  current file.  Only available in expert mode and requires
                  privileges.
    
           **thaw** Undo the effects of a filesystem freeze operation.  Only
                  available in expert mode and requires privileges.
    
           **inject [**_tag_ **]**
                  Inject errors into a filesystem to observe filesystem
                  behavior at specific points under adverse conditions.
                  Without the _tag_ argument, displays the list of error tags
                  available.  Only available in expert mode and requires
                  privileges.
    
           **rginfo [ -r** _rgno_ **]**
                  Show information about or update the state of realtime
                  allocation groups.
                     **-r** Act only on a specific realtime group.
    
           **resblks [**_blocks_ **]**
                  Get and/or set count of reserved filesystem blocks using
                  the XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system
                  calls.  Note -- this can be useful for exercising out of
                  space behavior.  Only available in expert mode and requires
                  privileges.
    
           **shutdown**[ **-f**]
                  Force the filesystem to shut down, preventing any further
                  IO.  XFS and other filesystems implement this
                  functionality, although implementation details may differ
                  slightly.  Only available in expert mode and requires
                  privileges.
    
                  By default, the filesystem will not attempt to flush
                  completed transactions to disk before shutting down the
                  filesystem.  This simulates a disk failure or crash.
                     **-f** Force the filesystem to flush all completed
                         transactions to disk before shutting down, matching
                         XFS behavior when critical corruption is
                         encountered.
    
           **statfs [ -c ] [ -g ] [ -s ]**
                  Report selected statistics on the filesystem where the
                  current file resides.  The default behavior is to enable
                  all three reporting options:
                     **-c** Display **XFS_IOC_FSCOUNTERS** summary counter data.
                     **-g** Display **XFS_IOC_FSGEOMETRY** filesystem geometry
                            data.
                     **-s** Display statfs(2) data.
           **inode  [ [ -n ]**_number_ **] [ -v ]**
                  The inode command queries physical information about an
                  inode. With no arguments, it will return 1 or 0, indicating
                  whether or not any inode numbers greater than 32 bits are
                  currently in use in the filesystem.  If given an inode
                  _number_ as an argument, the command will return the same
                  inode _number_ if it is in use, or 0 if not. With **-n** _number_ ,
                  the next used inode number after this _number_ will be
                  returned, or zero if the supplied inode number is the
                  highest one in use. With **-v** the command will also report
                  the number of bits (32 or 64) used by the inode _number_
                  printed in the result; if no inode _number_ was specified on
                  the command line, the maximum possible inode number in the
                  system will be printed along with its size.
    
           **inumbers [ -a** _agno_ **] [ -d ] [ -e** _endino_ **] [ -n** _batchsize_ **] [ -s**
           _startino_ **] [ -v** _version_ **]**
                  Prints allocation information about groups of inodes in an
                  XFS filesystem.  Callers can use this information to figure
                  out which inodes are allocated.  Options are as follows:
                     **-a** _agno_
                            Display only results from the given allocation
                            group.  If not specified, all results returned
                            will be displayed.
                     **-d** Print debugging information about call results.
                     **-e** _endino_
                            Stop displaying records when this inode number is
                            reached.  Defaults to stopping when the system
                            call stops returning results.
                     **-n** _batchsize_
                            Retrieve at most this many records per call.
                            Defaults to 4,096.
                     **-s** _startino_
                            Display inode allocation records starting with
                            this inode.  Defaults to the first inode in the
                            filesystem.  If the given inode is not allocated,
                            results will begin with the next allocated inode
                            in the filesystem.
                     **-v** _version_
                            Use a particular version of the kernel interface.
                            Currently supported versions are 1 and 5.
    
           **scrub** _type_ **[**_agnumber_ **|**_rgnumber_ **|**_ino gen_ **|**_metapath_ **[**_rgnumber_ **]**
           **]**
                  Scrub internal XFS filesystem metadata.  The **type** parameter
                  specifies which type of metadata to scrub.  For AG
                  metadata, one AG number must be specified.  For realtime
                  group metadata, one rtgroup number must be specified.  For
                  file metadata, the scrub is applied to the open file unless
                  the inode number and generation number are specified.  For
                  metapath, the name of a file or a raw number must be
                  specified.  If the metapath file is a per-rtgroup file, the
                  group number must be specified.
    
           **scrubv [ -b NN ] [ -d ] [ -m oflags ] [ -r ] [ -v NN ] [ -w ms ]**
           _group_ **[**_agnumber_ **|**_ino gen_ **]**
                  Scrub a bunch of internal XFS filesystem metadata.  The
                  **group** parameter specifies which group of metadata to scrub.
                  Valid groups are _ag_ , _agheader_ , _inode_ , _iscan_ , _fs_ , _probe_ ,
                  _rtgroup_ , or _summary_.
    
                  For **ag** and **agheader** metadata, one AG number must be
                  specified.  For **inode** metadata, the scrub is applied to the
                  open file unless the inode number and generation number are
                  specified.  For **rtgroup** metadata, one rt group number must
                  be specified.
    
                     **-b** _NN_  Inject scrub barriers into the vector stream at
                            the given interval.  Barriers abort vector
                            processing if any previous scrub function found
                            corruption.
                     **-d** Enables debug mode.
                     **-m** Fail scrub barriers if any of these scrub output
                            flags are seen.
                     **-r** Repair metadata if corruptions are found.  This
                            option requires expert mode.
                     **-v** _NN_  Force a particular API version.  **single** selects
                            XFS_SCRUB_METADATA (one-by-one).  **vector** selects
                            XFS_SCRUBV_METADATA (vectored).  If no option is
                            specified, vector mode will be used, with a
                            fallback to single mode if the kernel doesn't
                            recognize the vector mode ioctl.
                     **-w** _us_  Wait the given number of microseconds between
                            each scrub function.
    
           **repair** _type_ **[**_agnumber_ **|**_ino gen_ **]**
                  Repair internal XFS filesystem metadata.  The **type**
                  parameter specifies which type of metadata to repair.  For
                  AG metadata, one AG number must be specified.  For file
                  metadata, the repair is applied to the open file unless the
                  inode number and generation number are specified.  The **-R**
                  option can be specified to force rebuilding of a metadata
                  structure.
    
           **label [ -c | -s** _label_ **]**
                  On filesystems that support online label manipulation, get,
                  set, or clear the filesystem label.  With no options, print
                  the current filesystem label.  The **-c** option clears the
                  filesystem label by setting it to the null string.  The **-s**
                  _label_ option sets the filesystem label to _label_.  If the
                  label is longer than the filesystem will accept, **xfs_io**
                  will print an error message.  XFS filesystem labels can be
                  at most 12 characters long.
    
           **fsmap [ -d | -l | -r ] [ -m | -v ] [ -n** _nx_ **] [**_start_ **] [**_end_ **]**
                  Prints the mapping of disk blocks used by the filesystem
                  hosting the current file.  The map lists each extent used
                  by files, allocation group metadata, journalling logs, and
                  static filesystem metadata, as well as any regions that are
                  unused.  Each line of the listings takes the following
                  form:
    
                  _extent_ : _major_ :_minor_ [_startblock_.._endblock_]: _owner_
                  _startoffset_.._endoffset length_
    
                  Static filesystem metadata, allocation group metadata,
                  btrees, journalling logs, and free space are marked by
                  replacing the _startoffset_.._endoffset_ with the appropriate
                  marker.  All blocks, offsets, and lengths are specified in
                  units of 512-byte blocks, no matter what the filesystem's
                  block size is.  The optional _start_ and _end_ arguments can be
                  used to constrain the output to a particular range of disk
                  blocks.  If these two options are specified, exactly one of
                  **-d** , **-l** , or **-r** must also be set.
                     **-d** Display only extents from the data device.  This
                            option only applies for XFS filesystems.
                     **-l** Display only extents from the external log
                            device.  This option only applies to XFS
                            filesystems.
                     **-r** Display only extents from the realtime device.
                            This option only applies to XFS filesystems.
                     **-m** Display results in a machine readable format
                            (CSV).  This option is not compatible with the **-v**
                            flag.  The columns of the output are: extent
                            number, device major, device minor, physical
                            start, physical end, owner, offset start, offset
                            end, length.  The start, end, and length numbers
                            are provided in units of 512b.  The owner field
                            is a special string that takes the form:
    
                               _inode_%lld_data_
                                   for inode data.
                               _inode_%lld_data_bmbt_
                                   for inode data extent maps.
                               _inode_%lld_attr_
                                   for inode extended attribute data.
                               _inode_%lld_attr_bmbt_
                                   for inode extended attribute extent maps.
                               _special_%u:%u_
                                   for other filesystem metadata.
    
                     **-n** _num_extents_
                            If this option is given, **fsmap** obtains the extent
                            list of the file in groups of _num_extents_
                            extents.  In the absence of **-n** , **fsmap** queries the
                            system for extents in groups of 131,072 records.
    
                     **-v** Shows verbose information.  When this flag is
                            specified, additional AG specific information is
                            appended to each line in the following form:
    
                                 _agno_ (_startagblock_.._endagblock_) _nblocks_
                                 _flags_
    
                            A second **-v** option will print out the _flags_
                            legend.  This option is not compatible with the
                            **-m** flag.
    
           **fsuuid** Print the mounted filesystem UUID.
    
           **sysfspath**
                  Print the sysfs or debugfs path for the mounted filesystem.
    
                  The **-d** option selects debugfs instead of sysfs.
    
           **getfsprops** _name_ **[**_names_**... ]**
                  Retrieve the values of the given filesystem properties.
    
           **listfsprops [**_-v_ **]**
                  List all filesystem properties that have been stored in the
                  filesystem.  If the **-v** flag is specified, prints the values
                  of the properties.
    
           **setfsprops** _name_**=**_value_ **[**_name_**=**_value_**... ]**
                  Set the given filesystem properties to the specified
                  values.
    
           **removefsprops** _name_ **[**_names_**... ]**
                  Remove the given filesystem properties.
    


## OTHER COMMANDS



           **help [** command **]**
                  Display a brief description of one or all commands.
    
           **print** Display a list of all open files and memory mapped regions.
                  The current file and current mapping are distinguishable
                  from any others.
    
           **p** See the **print** command.
    
           **quit** Exit **xfs_io**.
    
           **q** See the **quit** command.
    
           **log_writes -d** _device_ **-m** _mark_
                  Create a mark named _mark_ in the dm-log-writes log specified
                  by _device._  This is intended to be equivalent to the shell
                  command:
    
                  **dmsetup message** _device_ **0 mark** _mark_
    
           **lw** See the **log_writes** command.
    
           **crc32cselftest**
                  Test the internal crc32c implementation to make sure that
                  it computes results correctly.
    


* * *