1xfs_io(8)                   System Manager's Manual                  xfs_io(8)
2
3
4

NAME

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

SYNOPSIS

9       xfs_io  [  -adfimrRstxT  ]  [ -c cmd ] ... [ -C cmd ] ... [ -p prog ] [
10       file ]
11       xfs_io -V
12

DESCRIPTION

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

OPTIONS

21       xfs_io commands may be run interactively (the default) or as  arguments
22       on the command line.  Interactive mode always runs commands on the cur‐
23       rent open file, whilst commands  run  from  the  command  line  may  be
24       repeated  on all open files rather than just the current open file.  In
25       general, open file iteration will occur for commands  that  operate  on
26       file content or state. In contrast, commands that operate on filesystem
27       or system-wide state will only be run on the current file regardless of
28       how  many files are currently open.  Multiple arguments may be given on
29       the command line and they are run in the sequence  given.  The  program
30       exits one all commands have been run.
31
32       -c cmd    Run  the  specified  command on all currently open files.  To
33                 maintain compatibility with historical usage,  commands  that
34                 can  not  be run on all open files will still be run but only
35                 execute once on the current open file.  Multiple -c arguments
36                 may  be  given  and may be interleaved on the command line in
37                 any order with -C commands.
38
39       -C cmd    Run the specified command only  on  the  current  open  file.
40                 Multiple  -C arguments may be given and may be interleaved on
41                 the command line in any order with -c commands.
42
43       -p prog   Set the program name for prompts and some error messages, the
44                 default value is xfs_io.
45
46       -f        Create file if it does not already exist.
47
48       -r        Open  file  read-only, initially. This is required if file is
49                 immutable or append-only.
50
51       -i        Start an idle thread. The purpose of this idle thread  is  to
52                 test  io  from a multi threaded process. With single threaded
53                 process, the file table is not shared and  file  structs  are
54                 not  reference  counted.   Spawning  an  idle thread can help
55                 detecting file struct reference leaks.
56
57       -x        Expert mode. Dangerous commands are only  available  in  this
58                 mode.   These commands also tend to require additional privi‐
59                 leges.
60
61       -V        Prints the version number and exits.
62
63       The other open(2) options described below are also available  from  the
64       command line.
65

CONCEPTS

67       xfs_io maintains a number of open files and memory mappings.  Files can
68       be initially opened on the command line  (optionally),  and  additional
69       files can also be opened later.
70
71       xfs_io  commands can be broken up into three groups.  Some commands are
72       aimed at doing regular file I/O - read, write, sync,  space  prealloca‐
73       tion, etc.
74
75       The second set of commands exist for manipulating memory mapped regions
76       of a file - mapping, accessing, storing, unmapping, flushing, etc.
77
78       The remaining commands are for  the  navigation  and  display  of  data
79       structures  relating  to  the open files, mappings, and the filesystems
80       where they reside.
81
82       Many commands have extensive online help. Use the help command for more
83       details on any command.
84

FILE I/O COMMANDS

86       file [ N ]
87              Display  a  list of all open files and (optionally) switch to an
88              alternate current open file.
89
90       open [[ -acdfrstRTPL ] path ]
91              Closes the current file, and opens the file  specified  by  path
92              instead.  Without  any  arguments, displays statistics about the
93              current file - see the stat command.
94                 -a  opens append-only (O_APPEND).
95                 -d  opens for direct I/O (O_DIRECT).
96                 -f  creates the file if it doesn't already exist (O_CREAT).
97                 -r  opens read-only (O_RDONLY).
98                 -s  opens for synchronous I/O (O_SYNC).
99                 -t  truncates on open (O_TRUNC).
100                 -n  opens in non-blocking mode if possible (O_NONBLOCK).
101                 -T  create a temporary file not linked  into  the  filesystem
102                     namespace (O_TMPFILE).  The pathname passed must refer to
103                     a directory which is treated as virtual  parent  for  the
104                     newly  created  invisible file.  Can not be used together
105                     with the -r option.
106                 -R  marks the file as a realtime XFS file after  opening  it,
107                     if it is not already marked as such.
108                 -P  opens  the  path  as  a  referent only (O_PATH).  This is
109                     incompatible with  other  flags  specifying  other  O_xxx
110                     flags apart from -L.
111                 -L  doesn't follow symlinks (O_NOFOLLOW).  This is incompati‐
112                     ble with other flags specifying other O_xxx  flags  apart
113                     from -P.
114
115       o      See the open command.
116
117       close  Closes the current open file, marking the next open file as cur‐
118              rent (if one exists).
119
120       c      See the close command.
121
122       chmod -r | -w
123              Change the mode of the currently open file. The -r  option  will
124              set  the  file  permissions  to  read-only (0444), whilst the -w
125              option will set the file permissions to read-write (0644).  This
126              allows  xfs_io to set up mismatches between the file permissions
127              and the open file descriptor read/write mode to exercise permis‐
128              sion checks inside various syscalls.
129
130       pread  [  -b bsize ] [ -qv ] [ -FBR [ -Z seed ] ] [ -V vectors ] offset
131       length
132              Reads a range of bytes in a specified blocksize from  the  given
133              offset.
134                 -b  can  be  used to set the blocksize into which the read(2)
135                     requests will be split. The  default  blocksize  is  4096
136                     bytes.
137                 -q  quiet mode, do not write anything to standard output.
138                 -v  dump the contents of the buffer after reading, by default
139                     only the count of bytes actually read is dumped.
140                 -F  read the buffers in a forwards sequential direction.
141                 -B  read the buffers in a reserve sequential direction.
142                 -R  read the buffers in the give range in a random order.
143                 -Z seed
144                     specify the random number seed used for random reads.
145                 -V vectors
146                     Use the vectored IO read syscall preadv(2) with a  number
147                     of  blocksize  length iovecs. The number of iovecs is set
148                     by the vectors parameter.
149
150       r      See the pread command.
151
152       pwrite [ -i file ] [ -qdDwNOW ] [ -s skip ] [ -b size ] [ -S seed  ]  [
153       -FBR [ -Z zeed ] ] [ -V vectors ] offset length
154              Writes  a range of bytes in a specified blocksize from the given
155              offset.  The bytes written can be either a set pattern  or  read
156              in from another file before writing.
157                 -i  allows an input file to be specified as the source of the
158                     data to be written.
159                 -q  quiet mode, do not write anything to standard output.
160                 -d  causes direct I/O, rather than the usual buffered I/O, to
161                     be used when reading the input file.
162                 -w  call  fdatasync(2) once all writes are complete (included
163                     in timing results)
164                 -N  Perform the pwritev2(2) call with RWF_NOWAIT.
165                 -D  Perform the pwritev2(2) call with RWF_DSYNC.
166                 -O  perform pwrite once and return the (maybe partial)  bytes
167                     written.
168                 -W  call  fsync(2)  once all writes are complete (included in
169                     timing results)
170                 -s  specifies the number of bytes to skip from the  start  of
171                     the input file before starting to read.
172                 -b  used  to  set  the  blocksize  into  which  the  write(2)
173                     requests will be split. The  default  blocksize  is  4096
174                     bytes.
175                 -S  used  to  set  the  (repeated) fill pattern which is used
176                     when the data to write is not coming from  a  file.   The
177                     default buffer fill pattern value is 0xcdcdcdcd.
178                 -F  write the buffers in a forwards sequential direction.
179                 -B  write the buffers in a reserve sequential direction.
180                 -R  write the buffers in the give range in a random order.
181                 -Z seed
182                     specify the random number seed used for random write
183                 -V vectors
184                     Use  the vectored IO write syscall pwritev(2) with a num‐
185                     ber of blocksize length iovecs. The number of  iovecs  is
186                     set by the vectors parameter.
187
188       w      See the pwrite command.
189
190       bmap [ -adelpv ] [ -n nx ]
191              Prints the block mapping for the current open file. Refer to the
192              xfs_bmap(8) manual page for complete documentation.
193
194       fiemap [ -alv ] [ -n nx ] [ offset [ len ]]
195              Prints the block mapping for the current  open  file  using  the
196              fiemap  ioctl.   Options  behave as described in the xfs_bmap(8)
197              manual page.
198
199              Optionally, this command also supports passing the start  offset
200              from  where  to begin the mapping and the length of that region.
201              The kernel will return any full extents which intersect with the
202              requested range, and the fiemap command will print them in their
203              entirety.  If the requested range starts  or  ends  in  a  hole,
204              fiemap will print the hole, truncated to the requested range.
205
206       extsize [ -R | -D ] [ value ]
207              Display  and/or modify the preferred extent size used when allo‐
208              cating space for the currently open file. If the  -R  option  is
209              specified,  a  recursive  descent is performed for all directory
210              entries below the  currently  open  file  (-D  can  be  used  to
211              restrict the output to directories only).  If the target file is
212              a directory, then the inherited extent  size  is  set  for  that
213              directory  (new  files  created  in  that directory inherit that
214              extent size).  The value should be specified in bytes, or  using
215              one  of  the  usual units suffixes (k, m, g, b, etc). The extent
216              size is always reported in units of bytes.
217
218       cowextsize [ -R | -D ] [ value ]
219              Display and/or modify the preferred  copy-on-write  extent  size
220              used  when  allocating space for the currently open file. If the
221              -R option is specified, a recursive descent is performed for all
222              directory  entries below the currently open file (-D can be used
223              to restrict the output to directories only).  If the target file
224              is  a  directory,  then the inherited CoW extent size is set for
225              that directory (new files created in that directory inherit that
226              CoW  extent  size).   The value should be specified in bytes, or
227              using one of the usual units suffixes (k, m,  g,  b,  etc).  The
228              extent size is always reported in units of bytes.
229
230       allocsp size 0
231              Sets  the  size  of  the  file to size and zeroes any additional
232              space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP  system
233              call described in the xfsctl(3) manual page.  allocsp and freesp
234              do exactly the same thing.
235
236       freesp size 0
237              See the allocsp command.
238
239       fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
240              On platforms which support it, allows hints be given to the sys‐
241              tem  regarding the expected I/O patterns on the file.  The range
242              arguments are required by some advise commands ([*] below),  and
243              the others must have no range arguments.  With no arguments, the
244              POSIX_FADV_NORMAL advice is implied (default readahead).
245                 -d  the data will not be accessed again in  the  near  future
246                     (POSIX_FADV_DONTNEED[*]).
247                 -n  data   will   be   accessed   once   and  not  be  reused
248                     (POSIX_FADV_NOREUSE[*]).
249                 -r  expect access to data in  random  order  (POSIX_FADV_RAN‐
250                     DOM), which sets readahead to zero.
251                 -s  expect    access    to    data    in   sequential   order
252                     (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
253                     head on the file.
254                 -w  advises   the   specified   data  will  be  needed  again
255                     (POSIX_FADV_WILLNEED[*]) which forces the maximum  reada‐
256                     head.
257
258       fdatasync
259              Calls fdatasync(2) to flush the file's in-core data to disk.
260
261       fsync  Calls fsync(2) to flush all in-core file state to disk.
262
263       s      See the fsync command.
264
265       sync_range [ -a | -b | -w ] offset length
266              On platforms which support it, allows control of syncing a range
267              of the file to disk. With no options,  SYNC_FILE_RANGE_WRITE  is
268              implied on the range supplied.
269                 -a  wait  for  IO  in the given range to finish after writing
270                     (SYNC_FILE_RANGE_WAIT_AFTER).
271                 -b  wait for IO in the given range to finish  before  writing
272                     (SYNC_FILE_RANGE_WAIT_BEFORE).
273                 -w  start   writeback  of  dirty  data  in  the  given  range
274                     (SYNC_FILE_RANGE_WRITE).
275
276       sync   Calls sync(2) to flush all filesystems' in-core data to disk.
277
278       syncfs Calls syncfs(2) to flush this filesystem's in-core data to disk.
279
280       resvsp offset length
281              Allocates reserved, unwritten space for part of a file using the
282              XFS_IOC_RESVSP  system  call  described  in the xfsctl(3) manual
283              page.
284
285       unresvsp offset length
286              Frees  reserved  space  for   part   of   a   file   using   the
287              XFS_IOC_UNRESVSP  system  call described in the xfsctl(3) manual
288              page.
289
290       falloc [ -k ] offset length
291              Allocates reserved, unwritten space for part of a file using the
292              fallocate routine as described in the fallocate(2) manual page.
293                 -k  will  set  the  FALLOC_FL_KEEP_SIZE  flag as described in
294                     fallocate(2).
295
296       fcollapse offset length
297              Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag  as  described
298              in the fallocate(2) manual page to de-allocates blocks and elim‐
299              inates the hole created in this process by shifting data  blocks
300              into the hole.
301
302       finsert offset length
303              Call  fallocate with FALLOC_FL_INSERT_RANGE flag as described in
304              the fallocate(2) manual page to create the hole by shifting data
305              blocks.
306
307       fpunch offset length
308              Punches  (de-allocates)  blocks in the file by calling fallocate
309              with the FALLOC_FL_PUNCH_HOLE flag as described  in  the  fallo‐
310              cate(2) manual page.
311
312       funshare offset length
313              Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as described in
314              the fallocate(2) manual page to unshare all shared blocks within
315              the range.
316
317       fzero [ -k ] offset length
318              Call  fallocate  with  FALLOC_FL_ZERO_RANGE flag as described in
319              the fallocate(2) manual page to allocate and zero blocks  within
320              the range.  With the -k option, use the FALLOC_FL_KEEP_SIZE flag
321              as well.
322
323       zero offset length
324              Call  xfsctl  with  XFS_IOC_ZERO_RANGE  as  described   in   the
325              xfsctl(3)  manual  page  to  allocate and zero blocks within the
326              range.
327
328       truncate offset
329              Truncates the current file at  the  given  offset  using  ftrun‐
330              cate(2).
331
332       sendfile [ -q ] -i srcfile | -f N [ offset length ]
333              On  platforms  which  support it, allows a direct in-kernel copy
334              between two file descriptors. The current open file is the  tar‐
335              get,  the  source must be specified as another open file (-f) or
336              by path (-i).
337                 -q quiet mode, do not write anything to standard output.
338
339       readdir [ -v ] [ -o offset ] [ -l length ]
340              Read a range of directory entries  from  a  given  offset  of  a
341              directory.
342                 -v  verbose  mode  -  dump dirent content as defined in read‐
343                     dir(3)
344                 -o  specify starting offset
345                 -l  specify total length to read (in bytes)
346
347       seek  -a | -d | -h [ -r ] [ -s ] offset
348              On platforms that support the lseek(2) SEEK_DATA  and  SEEK_HOLE
349              options, display the offsets of the specified segments.
350                 -a  Display both data and hole segments starting at the spec‐
351                     ified offset.
352                 -d  Display the data segment starting at the  specified  off‐
353                     set.
354                 -h  Display  the  hole segment starting at the specified off‐
355                     set.
356                 -r  Recursively display all the specified  segments  starting
357                     at the specified offset.
358                 -s  Display the starting lseek(2) offset. This offset will be
359                     a calculated value when both data and holes are displayed
360                     together or performing a recusively display.
361
362       reflink  [ -C ] [ -q ] src_file [src_offset dst_offset length]
363              On    filesystems    that    support    the    FICLONERANGE   or
364              BTRFS_IOC_CLONE_RANGE  ioctls,  map  length  bytes   at   offset
365              dst_offset in the open file to the same physical blocks that are
366              mapped at offset src_offset in the file src_file , replacing any
367              contents  that may already have been there.  If a program writes
368              into a reflinked block range of either file,  the  dirty  blocks
369              will  be  cloned,  written to, and remapped ("copy on write") in
370              the affected file, leaving  the  other  file(s)  unchanged.   If
371              src_offset,  dst_offset, and length are omitted, all contents of
372              src_file will be reflinked into the open file.
373                 -C  Print timing statistics in a condensed format.
374                 -q  Do not print timing statistics at all.
375
376       dedupe  [ -C ] [ -q ] src_file src_offset dst_offset length
377              On   filesystems   that    support    the    FIDEDUPERANGE    or
378              BTRFS_IOC_FILE_EXTENT_SAME  ioctls,  map  length bytes at offset
379              dst_offset in the open file to the same physical blocks that are
380              mapped  at  offset src_offset in the file src_file , but only if
381              the contents of both ranges are identical.   This  is  known  as
382              block-based deduplication.  If a program writes into a reflinked
383              block range of either file, the dirty  blocks  will  be  cloned,
384              written to, and remapped ("copy on write") in the affected file,
385              leaving the other file(s) unchanged.
386                 -C  Print timing statistics in a condensed format.
387                 -q  Do not print timing statistics at all.
388
389       copy_range [ -s src_offset ] [ -d dst_offset ] [ -l length ] src_file |
390       -f N
391              On  filesystems that support the copy_file_range(2) system call,
392              copies data from the source file into  the  current  open  file.
393              The  source  must  be  specified either by path (src_file) or as
394              another open file (-f).  If length is not specified,  this  com‐
395              mand copies data from src_offset to the end of src_file into the
396              dst_file at dst_offset.
397                 -s  Copy data from src_file beginning from src_offset.
398                 -d  Copy data into the open file beginning at dst_offset.
399                 -l  Copy up to length bytes of data.
400
401       swapext donor_file
402              Swaps extent forks between files. The current open file  is  the
403              target. The donor file is specified by path. Note that file data
404              is not copied (file content moves with the fork(s)).
405
406       set_encpolicy [ -c mode ] [ -n mode ] [ -f flags ] [  -v  version  ]  [
407       keyspec ]
408              On  filesystems  that  support  encryption, assign an encryption
409              policy to the current file.  keyspec is a hex string which spec‐
410              ifies  the  encryption  key to use.  For v1 encryption policies,
411              keyspec must be a 16-character hex string  (8  bytes).   For  v2
412              policies,  keyspec must be a 32-character hex string (16 bytes).
413              If unspecified, an all-zeroes value is used.
414                 -c mode
415                     contents encryption mode (e.g. AES-256-XTS)
416                 -n mode
417                     filenames encryption mode (e.g. AES-256-CTS)
418                 -f flags
419                     policy flags (numeric)
420                 -v version
421                     policy version.  Defaults to 1  or  2  depending  on  the
422                     length of keyspec; or to 1 if keyspec is unspecified.
423
424       get_encpolicy [ -1 ] [ -t ]
425              On  filesystems  that support encryption, display the encryption
426              policy of the current file.
427                 -1  Use only the old ioctl  to  get  the  encryption  policy.
428                     This only works if the file has a v1 encryption policy.
429                 -t  Test   whether  v2  encryption  policies  are  supported.
430                     Prints "supported", "unsupported", or an error message.
431
432       add_enckey [ -d descriptor ] [ -k key_id ]
433              On filesystems that support encryption, add an encryption key to
434              the  filesystem containing the currently open file.  By default,
435              the raw key in binary (typically 64 bytes  long)  is  read  from
436              standard input.
437                 -d descriptor
438                     key  descriptor,  as a 16-character hex string (8 bytes).
439                     If given, the key will be available for use by v1 encryp‐
440                     tion  policies  that use this descriptor.  Otherwise, the
441                     key is added as a v2  policy  key,  and  on  success  the
442                     resulting "key identifier" will be printed.
443                 -k key_id
444                     ID  of kernel keyring key of type "fscrypt-provisioning".
445                     If given, the raw key will be taken from here rather than
446                     from standard input.
447
448       rm_enckey [ -a ] keyspec
449              On filesystems that support encryption, remove an encryption key
450              from the filesystem containing the currently open file.  keyspec
451              is  a hex string specifying the key to remove, as a 16-character
452              "key descriptor" or a 32-character "key identifier".
453                 -a  Remove the key for all users who have added it, not  just
454                     the current user.  This is a privileged operation.
455
456       enckey_status keyspec
457              On filesystems that support encryption, display the status of an
458              encryption key.  keyspec is a hex string specifying the key  for
459              which  to display the status, as a 16-character "key descriptor"
460              or a 32-character "key identifier".
461
462       lsattr [ -R | -D | -a | -v ]
463              List extended inode flags on the currently open file. If the  -R
464              option  is  specified,  a recursive descent is performed for all
465              directory entries below the currently open file (-D can be  used
466              to  restrict  the  output to directories only).  This is a depth
467              first descent, it does not follow symlinks and it also does  not
468              cross mount points.
469
470              The  current  inode  flag  letters are documented below.  Please
471              refer to  the  ioctl_xfs_fsgetxattr(2)  documentation  for  more
472              details about what they mean.
473
474              r    realtime file (XFS_XFLAG_REALTIME)
475
476              p    prealloc (XFS_XFLAG_PREALLOC)
477
478              i    immutable (XFS_XFLAG_IMMUTABLE)
479
480              a    append only (XFS_XFLAG_APPEND)
481
482              s    synchronous file writes (XFS_XFLAG_SYNC)
483
484              A    noatime (XFS_XFLAG_NOATIME)
485
486              d    nodump (XFS_XFLAG_NODUMP)
487
488              t    inherit realtime flag (XFS_XFLAG_RTINHERIT)"
489
490              P    inherit project id (XFS_XFLAG_PROJINHERIT)
491
492              n    no symlink creation (XFS_XFLAG_NOSYMLINKS)
493
494              e    extent size hint (XFS_XFLAG_EXTSIZE)
495
496              E    inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)
497
498              f    nodefrag (XFS_XFLAG_NODEFRAG)
499
500              S    filestream allocator (XFS_XFLAG_FILESTREAM)
501
502              x    direct access persistent memory (XFS_XFLAG_DAX)
503
504              C    copy on write extent hint (XFS_XFLAG_COWEXTSIZE)
505
506              X    has extended attributes (XFS_XFLAG_HASATTR)
507
508       chattr [ -R | -D ] [ +/-riasAdtPneEfSxC ]
509              Change  extended  inode flags on the currently open file. The -R
510              and -D options have the same meaning as above.
511
512              See the lsattr command above for the list of inode flag letters.
513
514       flink path
515              Link the currently open  file  descriptor  into  the  filesystem
516              namespace.
517       stat [ -v|-r ]
518              Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
519              call on the current file. If the -v  option  is  specified,  the
520              atime  (last  access),  mtime  (last  modify),  and  ctime (last
521              change) timestamps are also displayed.  The -r option dumps  raw
522              fields from the stat structure.
523       statx [ -v|-r ][ -m basic | -m all | -m <mask> ][ -FD ]
524              Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
525              call on the current file.
526                 -v  Show timestamps.
527                 -r  Dump raw statx structure values.
528                 -m basic
529                     Set   the   field   mask   for   the   statx   call    to
530                     STATX_BASIC_STATS.
531                 -m all
532                     Set  the  the  field mask for the statx call to STATX_ALL
533                     (default).
534                 -m <mask>
535                     Specify a numeric field mask for the statx call.
536                 -F  Force the attributes to be synced with the server.
537                 -D  Don't sync attributes with the server.
538
539       chproj [ -R|-D ]
540              Modifies the project  identifier  associated  with  the  current
541              path. The -R option will recursively descend if the current path
542              is a directory. The -D option  will  also  recursively  descend,
543              only  setting  modifying  projects  on  subdirectories.  See the
544              xfs_quota(8) manual page  for  more  information  about  project
545              identifiers.
546
547       lsproj [ -R|-D ]
548              Displays  the  project  identifier  associated  with the current
549              path. The -R and  -D  options  behave  as  described  above,  in
550              chproj.
551
552       parent [ -cpv ]
553              By  default  this  command  prints out the parent inode numbers,
554              inode generation numbers and  basenames  of  all  the  hardlinks
555              which point to the inode of the current file.
556                 -p  the  output is similar to the default output except path‐
557                     names up to the mount-point are printed  out  instead  of
558                     the component name.
559                 -c  the   file's   filesystem   will  check  all  the  parent
560                     attributes for consistency.
561                 -v  verbose output will be printed.
562              [NOTE: Not currently operational on Linux.]
563
564       utimes atime_sec atime_nsec mtime_sec mtime_nsec
565              The utimes command changes the atime and mtime  of  the  current
566              file.   sec  uses  UNIX  timestamp  notation  and is the seconds
567              elapsed since 1970-01-01 00:00:00 UTC.  nsec is the  nanoseconds
568              since  the  sec. This value needs to be in the range 0-999999999
569              with UTIME_NOW and  UTIME_OMIT  being  exceptions.   Each  (sec,
570              nsec) pair constitutes a single timestamp value.
571
572
573

MEMORY MAPPED I/O COMMANDS

575       mmap [ N | [[ -rwxS ] [-s size ] offset length ]]
576              With no arguments, mmap shows the current mappings. Specifying a
577              single numeric argument N sets the current mapping. If two argu‐
578              ments  are specified (a range specified by offset and length), a
579              new mapping is created spanning the range,  and  the  protection
580              mode can be given as a combination of PROT_READ (-r), PROT_WRITE
581              (-w), and PROT_EXEC (-x).  The mapping will be created with  the
582              MAP_SHARED flag by default, or with the Linux specific (MAP_SYNC
583              | MAP_SHARED_VALIDATE) flags if -S is given.  -s size is used to
584              do  a  mmap(size)  &&  munmap(size)  operation  at first, try to
585              reserve some extendible free memory space,  if  size  is  bigger
586              than length parameter. But there's not guarantee that the memory
587              after length ( up to size ) will stay free.  e.g.  "mmap -rw  -s
588              8192  1024"  will mmap 0 ~ 1024 bytes memory, but try to reserve
589              1024 ~ 8192 free space(no guarantee). This free space will help‐
590              ful for "mremap 8192" without MREMAP_MAYMOVE flag.
591
592       mm     See the mmap command.
593
594       mremap [ -f <new_address> ] [ -m ] new_length
595              Changes  the  current  mapping  size to new_length.  Whether the
596              mapping  may  be  moved  is  controlled  by  the  flags  passed;
597              MREMAP_FIXED (-f), or MREMAP_MAYMOVE (-m).  new_length specifies
598              a page-aligned address to which the mapping must  be  moved.  It
599              can be set to 139946004389888, 4096k or 1g etc.
600
601       mrm    See the mremap command.
602
603       munmap Unmaps the current memory mapping.
604
605       mu     See the munmap command.
606
607       mread [ -f | -v ] [ -r ] [ offset length ]
608              Accesses  a  segment  of  the current memory mapping, optionally
609              dumping it to the standard output stream (with -v or -f  option)
610              for inspection. The accesses are performed sequentially from the
611              start offset by default, but can also be done from the end back‐
612              wards  through  the  mapping if the -r option in specified.  The
613              two verbose modes differ only in the relative offsets they  dis‐
614              play,  the -f option is relative to file start, whereas -v shows
615              offsets relative to the start of the mapping.
616
617       mr     See the mread command.
618
619       mwrite [ -r ] [ -S seed ] [ offset length ]
620              Stores a byte into memory for a range  within  a  mapping.   The
621              default  stored  value is 'X', repeated to fill the range speci‐
622              fied, but this can be changed using the -S option.   The  memory
623              stores  are  performed  sequentially  from  the  start offset by
624              default, but can also be done from the end backwards through the
625              mapping if the -r option in specified.
626
627       mw     See the mwrite command.
628
629       msync [ -i ] [ -a | -s ] [ offset length ]
630              Writes all modified copies of pages over the specified range (or
631              entire mapping if no range specified) to their  backing  storage
632              locations.  Also, optionally invalidates (-i) so that subsequent
633              references to the pages will  be  obtained  from  their  backing
634              storage  locations (instead of cached copies).  The flush can be
635              done synchronously (-s) or asynchronously (-a).
636
637       ms     See the msync command.
638
639       madvise [ -d | -r | -s | -w ] [ offset length ]
640              Modifies page cache behavior when operating on the current  map‐
641              ping.   The range arguments are required by some advise commands
642              ([*] below).  With no arguments, the POSIX_MADV_NORMAL advice is
643              implied (default readahead).
644                 -d  the pages will not be needed (POSIX_MADV_DONTNEED[*]).
645                 -r  expect  random page references (POSIX_MADV_RANDOM), which
646                     sets readahead to zero.
647                 -s  expect  sequential  page  references  (POSIX_MADV_SEQUEN‐
648                     TIAL), which doubles the default readahead on the file.
649                 -w  advises   the   specified  pages  will  be  needed  again
650                     (POSIX_MADV_WILLNEED[*]) which forces the maximum  reada‐
651                     head.
652
653       mincore
654              Dumps  a  list of pages or ranges of pages that are currently in
655              core, for the current memory mapping.
656
657

FILESYSTEM COMMANDS

659       bulkstat [ -a agno ] [ -d ] [ -e  endino  ]  [  -n  batchsize  ]  [  -s
660       startino ] [ -v version"]
661              Display  raw  stat information about a bunch of inodes in an XFS
662              filesystem.  Options are as follows:
663                 -a agno
664                        Display only results from the given allocation  group.
665                        If  not  specified,  all results returned will be dis‐
666                        played.
667                 -d     Print debugging information about call results.
668                 -e endino
669                        Stop displaying records  when  this  inode  number  is
670                        reached.   Defaults  to  stopping when the system call
671                        stops returning results.
672                 -n batchsize
673                        Retrieve at most this many records per call.  Defaults
674                        to 4,096.
675                 -s startino
676                        Display  inode  allocation  records starting with this
677                        inode.  Defaults to the first inode in the filesystem.
678                        If  the  given  inode  is  not allocated, results will
679                        begin with the next allocated inode in the filesystem.
680                 -v version
681                        Use a particular  version  of  the  kernel  interface.
682                        Currently supported versions are 1 and 5.
683
684       bulkstat_single [ -d ] [ -v version ] [ inum... | special... ]
685              Display  raw  stat information about individual inodes in an XFS
686              filesystem.  The -d and -v options are the same as the  bulkstat
687              command.   Arguments must be inode numbers or any of the special
688              values:
689                 root   Display information about the root directory inode.
690
691       freeze Suspend all write I/O requests to the filesystem of the  current
692              file.  Only available in expert mode and requires privileges.
693
694       thaw   Undo  the effects of a filesystem freeze operation.  Only avail‐
695              able in expert mode and requires privileges.
696
697       inject [ tag ]
698              Inject errors into a filesystem to observe  filesystem  behavior
699              at  specific  points  under  adverse conditions. Without the tag
700              argument, displays the  list  of  error  tags  available.   Only
701              available in expert mode and requires privileges.
702
703       resblks [ blocks ]
704              Get  and/or  set  count  of reserved filesystem blocks using the
705              XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system  calls.   Note
706              --  this  can  be  useful  for exercising out of space behavior.
707              Only available in expert mode and requires privileges.
708
709       shutdown [ -f ]
710              Force the filesystem to shut down, preventing  any  further  IO.
711              XFS and other filesystems implement this functionality, although
712              implementation details may differ slightly.  Only  available  in
713              expert mode and requires privileges.
714
715              By  default,  the filesystem will not attempt to flush completed
716              transactions to disk before shutting down the filesystem.   This
717              simulates a disk failure or crash.
718                 -f  Force  the filesystem to flush all completed transactions
719                     to disk before shutting down, matching XFS behavior  when
720                     critical corruption is encountered.
721
722       statfs Selected  statistics  from  statfs(2) and the XFS_IOC_FSGEOMETRY
723              system call on the filesystem where the current file resides.
724
725       inode  [ [ -n ] number ] [ -v ]
726              The inode command queries physical information about  an  inode.
727              With  no arguments, it will return 1 or 0, indicating whether or
728              not any inode numbers greater than 32 bits are currently in  use
729              in the filesystem.  If given an inode number as an argument, the
730              command will return the same inode number if it is in use, or  0
731              if  not.  With -n number , the next used inode number after this
732              number will be returned, or zero if the supplied inode number is
733              the highest one in use. With -v the command will also report the
734              number of bits (32 or 64) used by the inode  number  printed  in
735              the  result;  if  no  inode  number was specified on the command
736              line, the maximum possible inode number in the  system  will  be
737              printed along with its size.
738
739       inumbers  [  -a  agno  ]  [  -d  ]  [ -e endino ] [ -n batchsize ] [ -s
740       startino ] [ -v version ]
741              Prints allocation information about groups of inodes in  an  XFS
742              filesystem.   Callers  can  use  this  information to figure out
743              which inodes are allocated.  Options are as follows:
744                 -a agno
745                        Display only results from the given allocation  group.
746                        If  not  specified,  all results returned will be dis‐
747                        played.
748                 -d     Print debugging information about call results.
749                 -e endino
750                        Stop displaying records  when  this  inode  number  is
751                        reached.   Defaults  to  stopping when the system call
752                        stops returning results.
753                 -n batchsize
754                        Retrieve at most this many records per call.  Defaults
755                        to 4,096.
756                 -s startino
757                        Display  inode  allocation  records starting with this
758                        inode.  Defaults to the first inode in the filesystem.
759                        If  the  given  inode  is  not allocated, results will
760                        begin with the next allocated inode in the filesystem.
761                 -v version
762                        Use a particular  version  of  the  kernel  interface.
763                        Currently supported versions are 1 and 5.
764
765       scrub type [ agnumber | ino gen ]
766              Scrub  internal  XFS  filesystem  metadata.   The type parameter
767              specifies which type of metadata to scrub.  For AG metadata, one
768              AG  number  must  be specified.  For file metadata, the scrub is
769              applied to the open file unless the inode number and  generation
770              number are specified.
771
772       repair type [ agnumber | ino gen ]
773              Repair  internal  XFS  filesystem  metadata.  The type parameter
774              specifies which type of metadata to repair.   For  AG  metadata,
775              one  AG number must be specified.  For file metadata, the repair
776              is applied to the open file unless the inode number and  genera‐
777              tion number are specified.
778
779       label [ -c | -s label ]
780              On filesystems that support online label manipulation, get, set,
781              or clear the filesystem label.  With no options, print the  cur‐
782              rent  filesystem  label.   The  -c  option clears the filesystem
783              label by setting it to the null string.   The  -s  label  option
784              sets the filesystem label to label.  If the label is longer than
785              the filesystem will accept, xfs_io will print an error  message.
786              XFS filesystem labels can be at most 12 characters long.
787
788       fsmap [ -d | -l | -r ] [ -m | -v ] [ -n nx ] [ start ] [ end ]
789              Prints the mapping of disk blocks used by the filesystem hosting
790              the current file.  The map lists  each  extent  used  by  files,
791              allocation group metadata, journalling logs, and static filesys‐
792              tem metadata, as well as any regions that are unused.  Each line
793              of the listings takes the following form:
794
795              extent:   major:minor  [startblock..endblock]:  owner  startoff‐
796              set..endoffset length
797
798              Static filesystem metadata, allocation group  metadata,  btrees,
799              journalling  logs,  and  free  space are marked by replacing the
800              startoffset..endoffset with the appropriate marker.  All blocks,
801              offsets,  and lengths are specified in units of 512-byte blocks,
802              no matter what the filesystem's block  size  is.   The  optional
803              start and end arguments can be used to constrain the output to a
804              particular range of disk blocks.  If these two options are spec‐
805              ified, exactly one of -d, -l, or -r must also be set.
806                 -d     Display  only  extents  from  the  data  device.  This
807                        option only applies for XFS filesystems.
808                 -l     Display only extents from  the  external  log  device.
809                        This option only applies to XFS filesystems.
810                 -r     Display  only  extents from the realtime device.  This
811                        option only applies to XFS filesystems.
812                 -m     Display results in a machine  readable  format  (CSV).
813                        This  option  is not compatible with the -v flag.  The
814                        columns of  the  output  are:  extent  number,  device
815                        major,  device  minor,  physical  start, physical end,
816                        owner, offset start, offset end, length.   The  start,
817                        end, and length numbers are provided in units of 512b.
818                        The owner field is a special  string  that  takes  the
819                        form:
820
821                           inode_%lld_data
822                               for inode data.
823                           inode_%lld_data_bmbt
824                               for inode data extent maps.
825                           inode_%lld_attr
826                               for inode extended attribute data.
827                           inode_%lld_attr_bmbt
828                               for inode extended attribute extent maps.
829                           special_%u:%u
830                               for other filesystem metadata.
831
832
833                 -n num_extents
834                        If this option is given, fsmap obtains the extent list
835                        of the file in groups of num_extents extents.  In  the
836                        absence of -n, fsmap queries the system for extents in
837                        groups of 131,072 records.
838
839                 -v     Shows verbose information.  When this flag  is  speci‐
840                        fied,  additional  AG specific information is appended
841                        to each line in the following form:
842
843                             agno (startagblock..endagblock) nblocks flags
844
845                        A second -v option will print out  the  flags  legend.
846                        This option is not compatible with the -m flag.
847
848
849

OTHER COMMANDS

851       help [ command ]
852              Display a brief description of one or all commands.
853
854       print  Display a list of all open files and memory mapped regions.  The
855              current file and current mapping are  distinguishable  from  any
856              others.
857
858       p      See the print command.
859
860       quit   Exit xfs_io.
861
862       q      See the quit command.
863
864       log_writes -d device -m mark
865              Create  a  mark named mark in the dm-log-writes log specified by
866              device.  This is intended to be equivalent to the shell command:
867
868              dmsetup message device 0 mark mark
869
870       lw     See the log_writes command.
871
872       crc32cselftest
873              Test the internal crc32c implementation to  make  sure  that  it
874              computes results correctly.
875

SEE ALSO

877       mkfs.xfs(8),  xfsctl(3),  xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2),
878       fstat(2), fstatfs(2),  fsync(2),  ftruncate(2),  futimens(3),  mmap(2),
879       msync(2), open(2), pread(2), pwrite(2), readdir(3), dmsetup(8).
880
881
882
883                                                                     xfs_io(8)
Impressum