Provided by: xfsprogs_2.7.7-1_i386 bug

NAME

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

SYNOPSIS

       xfs_io [ -c cmd ] ... [ -p prog ] [ -adFfmrRstx ] file

DESCRIPTION

       xfs_io  is  a debugging tool like xfs_db, but is aimed at examining the
       regular file I/O path rather than the raw XFS volume itself.

       The options to xfs_io are:

       -c cmd    xfs_io commands may be run interactively (the default) or  as
                 arguments  on the command line.  Multiple -c arguments may be
                 given.  The commands are run in the sequence given, then  the
                 program exits.

       -p prog   Set the program name for prompts and some error messages, the
                 default value is xfs_io.

       -F        Allow file to reside in non-XFS (foreign) filesystems.   This
                 mode has a restricted set of commands.

       -f        Create file if it does not already exist.

       -r        Open file read-only, initially.

       -x        Expert  mode.   Dangerous commands are only available in this
                 mode.   These  commands  also  tend  to  require   additional
                 privileges.

       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 [ -FacdfrstR ] [ 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.
                 The -F option allows non-XFS (foreign) files to be opened and
                 operated on with a restricted command set.
                 The -a option opens append-only (O_APPEND).
                 The -d option opens for direct I/O (O_DIRECT).
                 The -f option creates the file if it  doesn’t  already  exist
                 (O_CREAT).
                 The -r option opens read-only (O_RDONLY).
                 The -s option opens for synchronous I/O (O_SYNC).
                 The -t option truncates on open (O_TRUNC).
                 The  -R  option  marks  the file as a realtime XFS file after
                 opening it, if it is not already marked as such.

       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.

       pread [ -b bsize ] [ -v ]
                 Reads  a  range  of  bytes  in a specified blocksize from the
                 given offset.
                 The -b option can be used to set the blocksize into which the
                 read(2)  requests  will  be  split.  The default blocksize is
                 4096 bytes.
                 The -v option will dump the  contents  of  the  buffer  after
                 reading,  by default only the count of bytes actually read is
                 dumped.

       r         See the pread command.

       pwrite [ -i file ] [ -d ] [ -s skip ] [ -b size ] [ -S seed ]
                 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.
                 The -i option allows an input file to  be  specified  as  the
                 source of the data to be written.
                 The  -d  option  will cause direct I/O, rather than the usual
                 buffered I/O, to be used when reading the input file.
                 The -s options specifies the number of bytes to skip from the
                 start of the input file before starting to read.
                 The -b option can be used to set the blocksize into which the
                 write(2) requests will be split.  The  default  blocksize  is
                 4096 bytes.  The -S option is 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.

       w         See the pwrite command.

       bmap [ -adlpv ] [ -n nx ]
                 Prints the block mapping for the current open file.  Refer to
                 the xfs_bmap manual page for complete documentation.

       allocsp offset length
                 Allocates   zeroed  space  for  part  of  a  file  using  the
                 XFS_IOC_ALLOCSP system call described in the xfs manual page.

       freesp offset length
                 Frees  space  for  part  of  a  file using the XFS_IOC_FREESP
                 system call described in the xfs manual page.

       fadvise [ -dnrsw ]
                 On platforms which support it, allows hints be given  to  the
                 system  regarding the expected I/O patterns on the file.  The
                 hints are similar to those of the madvise command,  discussed
                 later.

       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.

       resvsp offset length
                 Allocates reserved, unwritten space for part of a file  using
                 the  XFS_IOC_RESVSP  system  call described in the xfs manual
                 page.

       unresvsp offset length
                 Frees  reserved  space  for  part  of  a   file   using   the
                 XFS_IOC_UNRESVSP  system  call  described  in  the xfs manual
                 page.

       truncate offset
                 Truncates  the  current  file  at  the  given  offset   using
                 ftruncate(2).

       sendfile -i infile | -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).

MEMORY MAPPED I/O COMMANDS

       mmap [ -rwx ] [[ N ] | [ offset length ]]
              With no arguments, mmap shows the current mappings.   Specifying
              a  single  numeric  argument  sets  the current mapping.  If two
              arguments are specified (a range),  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).

       mm     See the mmap command.

       munmap Unmaps the current memory mapping.

       mu     See the munmap command.

       mread [ -frv ]
              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 ]
              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  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 [ -drwsw ] [ 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).  The -d option says the
              pages will  not  be  needed  (POSIX_MADV_DONTNEED[*]).   The  -r
              option     says     to    expect    random    page    references
              (POSIX_MADV_RANDOM), which  sets  readahead  to  zero.   The  -s
              option    says    to    expect    sequential   page   references
              (POSIX_MADV_SEQUENTIAL), which doubles the default readahead  on
              the  file.   The  -w  option 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.

OTHER 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.

       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.

       chattr [ -R | -D ] [ +/-riasAdtPn ]
              Change  extended inode flags on the currently open file.  The -R
              and -D options have the same  meaning  as  above.   The  mapping
              between  each letter and the inode flags (refer to xfsctl(3) for
              the full list) is available via the help command.

       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  an
              argument, displays the  list  of  error  tags  available.   Only
              available in expert mode and requires privileges.

       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 shutdown (with or without  flushing  the
              log).  Only available in expert mode and requires privileges.

       stat [ -v ]
              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.

       statfs Selected statistics from statfs(2)  and  the  XFS_IOC_FSGEOMETRY
              system call on the filesystem where the current file resides.

       parent [ -cpv ]
              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 -p option
              is specified, then the output is similar to the  default  output
              except  pathnames  up to the mount-point are printed out instead
              of the component name.  If the -c option is specified, then  the
              file’s  filesystem  will  check  all  the  parent attributes for
              consistency.  If the -v option is specified, then verbose output
              will be printed.  Not currently operational on Linux.

IRIX SEE ALSO

       mkfs_xfs(1M), syssgi(2), xfs_bmap(1M), xfs_db(1M), xfs(4).

LINUX SEE ALSO

       mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5).

SEE ALSO

       fdatasync(2),  fstat(2),  fstatfs(2),  fsync(2), ftruncate(2), mmap(2),
       open(2), pread(2), pwrite(2).

                                                                     xfs_io(8)