unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-3.1)
Page:
Section:
Apropos / Subsearch:
optional field

xfs_io(8)                   System Manager's Manual                  xfs_io(8)



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(8), 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  privi-
                 leges.

       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 prealloca-
       tion, 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 0xcd-
                 cdcdcd.

       w         See the pwrite command.

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

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

       freesp offset length
                 Frees space for part of a file using the XFS_IOC_FREESP  sys-
                 tem call described in xfs(5).

       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 xfs(5).

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

       truncate offset
                 Truncates the current file at the given offset  using  ftrun-
                 cate(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 speci-
              fied, 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  map-
              ping.   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 List extended inode flags on the currently open file.

       chattr [ +/-riasAd ]
              Change extended inode flags on the currently open file.

       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  avail-
              able 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  argu-
              ment, 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,  as
              described in xfs(5).  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 from xfs(5) on the current file.  If the -v option is spec-
              ified,  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 from xfs(5) on the filesystem where the current file
              resides.


SEE ALSO
       fdatasync(2),    fstat(2),    fstatfs(2),    fsync(2),    ftruncate(2),
       mkfs.xfs(8),   mmap(2),   open(2),  pread(2),  pwrite(2),  xfs_bmap(8),
       xfs_db(8), xfs(5).



                                                                     xfs_io(8)