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  re‐
24       peated  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 de‐
55                 tecting 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 in‐
109                     compatible with other flags specifying other O_xxx  flags
110                     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 op‐
125              tion 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 forward sequential direction.
141                 -B  read the buffers in a reverse 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) re‐
173                     quests 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 forward sequential direction.
179                 -B  write the buffers in a reverse 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  re‐
211              strict the output to directories only).  If the target file is a
212              directory, then the inherited extent size is set for that direc‐
213              tory  (new  files  created in that directory inherit that extent
214              size).  The value should be specified in bytes, or using one  of
215              the  usual  units suffixes (k, m, g, b, etc). The extent size is
216              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 ex‐
228              tent 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              These commands are no longer supported as of Linux 5.17.
237
238       freesp size 0
239              See the allocsp command.
240
241       fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
242              On platforms which support it, allows hints be given to the sys‐
243              tem  regarding the expected I/O patterns on the file.  The range
244              arguments are required by some advise commands ([*] below),  and
245              the others must have no range arguments.  With no arguments, the
246              POSIX_FADV_NORMAL advice is implied (default readahead).
247                 -d  the data will not be accessed again in  the  near  future
248                     (POSIX_FADV_DONTNEED[*]).
249                 -n  data   will   be   accessed   once   and  not  be  reused
250                     (POSIX_FADV_NOREUSE[*]).
251                 -r  expect access to data in  random  order  (POSIX_FADV_RAN‐
252                     DOM), which sets readahead to zero.
253                 -s  expect access to data in sequential order (POSIX_FADV_SE‐
254                     QUENTIAL), which doubles the  default  readahead  on  the
255                     file.
256                 -w  advises   the   specified   data  will  be  needed  again
257                     (POSIX_FADV_WILLNEED[*]) which forces the maximum  reada‐
258                     head.
259
260       fdatasync
261              Calls fdatasync(2) to flush the file's in-core data to disk.
262
263       fsync  Calls fsync(2) to flush all in-core file state to disk.
264
265       s      See the fsync command.
266
267       sync_range [ -a | -b | -w ] offset length
268              On platforms which support it, allows control of syncing a range
269              of the file to disk. With no options,  SYNC_FILE_RANGE_WRITE  is
270              implied on the range supplied.
271                 -a  wait  for  IO  in the given range to finish after writing
272                     (SYNC_FILE_RANGE_WAIT_AFTER).
273                 -b  wait for IO in the given range to finish  before  writing
274                     (SYNC_FILE_RANGE_WAIT_BEFORE).
275                 -w  start   writeback  of  dirty  data  in  the  given  range
276                     (SYNC_FILE_RANGE_WRITE).
277
278       sync   Calls sync(2) to flush all filesystems' in-core data to disk.
279
280       syncfs Calls syncfs(2) to flush this filesystem's in-core data to disk.
281
282       resvsp offset length
283              Allocates reserved, unwritten space for part of a file using the
284              XFS_IOC_RESVSP  system  call  described  in the xfsctl(3) manual
285              page.
286
287       unresvsp offset length
288              Frees reserved space for part of a file  using  the  XFS_IOC_UN‐
289              RESVSP system call described in the xfsctl(3) manual page.
290
291       falloc [ -k ] offset length
292              Allocates reserved, unwritten space for part of a file using the
293              fallocate routine as described in the fallocate(2) manual page.
294                 -k  will set the FALLOC_FL_KEEP_SIZE  flag  as  described  in
295                     fallocate(2).
296
297       fcollapse offset length
298              Call  fallocate  with FALLOC_FL_COLLAPSE_RANGE flag as described
299              in the fallocate(2) manual page to de-allocates blocks and elim‐
300              inates  the hole created in this process by shifting data blocks
301              into the hole.
302
303       finsert offset length
304              Call fallocate with FALLOC_FL_INSERT_RANGE flag as described  in
305              the fallocate(2) manual page to create the hole by shifting data
306              blocks.
307
308       fpunch offset length
309              Punches (de-allocates) blocks in the file by  calling  fallocate
310              with  the  FALLOC_FL_PUNCH_HOLE  flag as described in the fallo‐
311              cate(2) manual page.
312
313       funshare offset length
314              Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as described in
315              the fallocate(2) manual page to unshare all shared blocks within
316              the range.
317
318       fzero [ -k ] offset length
319              Call fallocate with FALLOC_FL_ZERO_RANGE flag  as  described  in
320              the  fallocate(2) manual page to allocate and zero blocks within
321              the range.  With the -k option, use the FALLOC_FL_KEEP_SIZE flag
322              as well.
323
324       zero offset length
325              Call  xfsctl  with  XFS_IOC_ZERO_RANGE  as  described in the xf‐
326              sctl(3) manual page to  allocate  and  zero  blocks  within  the
327              range.
328
329       truncate offset
330              Truncates  the  current  file  at  the given offset using ftrun‐
331              cate(2).
332
333       sendfile [ -q ] -i srcfile | -f N [ offset length ]
334              On platforms which support it, allows a  direct  in-kernel  copy
335              between  two file descriptors. The current open file is the tar‐
336              get, the source must be specified as another open file  (-f)  or
337              by path (-i).
338                 -q quiet mode, do not write anything to standard output.
339
340       readdir [ -v ] [ -o offset ] [ -l length ]
341              Read  a  range of directory entries from a given offset of a di‐
342              rectory.
343                 -v  verbose mode - dump dirent content as  defined  in  read‐
344                     dir(3)
345                 -o  specify starting offset
346                 -l  specify total length to read (in bytes)
347
348       seek  -a | -d | -h [ -r ] [ -s ] offset
349              On  platforms  that support the lseek(2) SEEK_DATA and SEEK_HOLE
350              options, display the offsets of the specified segments.
351                 -a  Display both data and hole segments starting at the spec‐
352                     ified offset.
353                 -d  Display  the  data segment starting at the specified off‐
354                     set.
355                 -h  Display the hole segment starting at the  specified  off‐
356                     set.
357                 -r  Recursively  display  all the specified segments starting
358                     at the specified offset.
359                 -s  Display the starting lseek(2) offset. This offset will be
360                     a calculated value when both data and holes are displayed
361                     together or performing a recusively display.
362
363       reflink  [ -C ] [ -q ] src_file [src_offset dst_offset length]
364              On   filesystems    that    support    the    FICLONERANGE    or
365              BTRFS_IOC_CLONE_RANGE   ioctls,   map  length  bytes  at  offset
366              dst_offset in the open file to the same physical blocks that are
367              mapped at offset src_offset in the file src_file , replacing any
368              contents that may already have been there.  If a program  writes
369              into  a  reflinked  block range of either file, the dirty blocks
370              will be cloned, written to, and remapped ("copy  on  write")  in
371              the  affected  file,  leaving  the  other file(s) unchanged.  If
372              src_offset, dst_offset, and length are omitted, all contents  of
373              src_file will be reflinked into the open file.
374                 -C  Print timing statistics in a condensed format.
375                 -q  Do not print timing statistics at all.
376
377       dedupe  [ -C ] [ -q ] src_file src_offset dst_offset length
378              On    filesystems    that    support    the   FIDEDUPERANGE   or
379              BTRFS_IOC_FILE_EXTENT_SAME ioctls, map length  bytes  at  offset
380              dst_offset in the open file to the same physical blocks that are
381              mapped at offset src_offset in the file src_file , but  only  if
382              the  contents  of  both  ranges are identical.  This is known as
383              block-based deduplication.  If a program writes into a reflinked
384              block  range  of  either  file, the dirty blocks will be cloned,
385              written to, and remapped ("copy on write") in the affected file,
386              leaving the other file(s) unchanged.
387                 -C  Print timing statistics in a condensed format.
388                 -q  Do not print timing statistics at all.
389
390       copy_range [ -s src_offset ] [ -d dst_offset ] [ -l length ] src_file |
391       -f N
392              On filesystems that support the copy_file_range(2) system  call,
393              copies  data  from  the  source file into the current open file.
394              The source must be specified either by path (src_file) or as an‐
395              other  open file (-f).  If length is not specified, this command
396              copies data from src_offset to the  end  of  src_file  into  the
397              dst_file at dst_offset.
398                 -s  Copy data from src_file beginning from src_offset.
399                 -d  Copy data into the open file beginning at dst_offset.
400                 -l  Copy up to length bytes of data.
401
402       swapext donor_file
403              Swaps  extent  forks between files. The current open file is the
404              target. The donor file is specified by path. Note that file data
405              is not copied (file content moves with the fork(s)).
406
407       set_encpolicy  [  -c  mode  ] [ -n mode ] [ -f flags ] [ -v version ] [
408       keyspec ]
409              On filesystems that support  encryption,  assign  an  encryption
410              policy to the current file.  keyspec is a hex string which spec‐
411              ifies the encryption key to use.  For  v1  encryption  policies,
412              keyspec  must  be  a  16-character hex string (8 bytes).  For v2
413              policies, keyspec must be a 32-character hex string (16  bytes).
414              If unspecified, an all-zeroes value is used.
415                 -c mode
416                     contents encryption mode (e.g. AES-256-XTS)
417                 -n mode
418                     filenames encryption mode (e.g. AES-256-CTS)
419                 -f flags
420                     policy flags (numeric)
421                 -v version
422                     policy  version.   Defaults  to  1  or 2 depending on the
423                     length of keyspec; or to 1 if keyspec is unspecified.
424
425       get_encpolicy [ -1 ] [ -t ]
426              On filesystems that support encryption, display  the  encryption
427              policy of the current file.
428                 -1  Use  only  the  old  ioctl  to get the encryption policy.
429                     This only works if the file has a v1 encryption policy.
430                 -t  Test  whether  v2  encryption  policies  are   supported.
431                     Prints "supported", "unsupported", or an error message.
432
433       add_enckey [ -d descriptor ] [ -k key_id ]
434              On filesystems that support encryption, add an encryption key to
435              the filesystem containing the currently open file.  By  default,
436              the  raw  key  in  binary (typically 64 bytes long) is read from
437              standard input.
438                 -d descriptor
439                     key descriptor, as a 16-character hex string  (8  bytes).
440                     If given, the key will be available for use by v1 encryp‐
441                     tion policies that use this descriptor.   Otherwise,  the
442                     key  is  added as a v2 policy key, and on success the re‐
443                     sulting "key identifier" will be printed.
444                 -k key_id
445                     ID of kernel keyring key of type  "fscrypt-provisioning".
446                     If given, the raw key will be taken from here rather than
447                     from standard input.
448
449       rm_enckey [ -a ] keyspec
450              On filesystems that support encryption, remove an encryption key
451              from the filesystem containing the currently open file.  keyspec
452              is a hex string specifying the key to remove, as a  16-character
453              "key descriptor" or a 32-character "key identifier".
454                 -a  Remove  the key for all users who have added it, not just
455                     the current user.  This is a privileged operation.
456
457       enckey_status keyspec
458              On filesystems that support encryption, display the status of an
459              encryption  key.  keyspec is a hex string specifying the key for
460              which to display the status, as a 16-character "key  descriptor"
461              or a 32-character "key identifier".
462
463       lsattr [ -R | -D | -a | -v ]
464              List  extended inode flags on the currently open file. If the -R
465              option is specified, a recursive descent is  performed  for  all
466              directory  entries below the currently open file (-D can be used
467              to restrict the output to directories only).  This  is  a  depth
468              first  descent, it does not follow symlinks and it also does not
469              cross mount points.
470
471              The current inode flag letters are documented below.  Please re‐
472              fer  to  the  ioctl_xfs_fsgetxattr(2) documentation for more de‐
473              tails about what they mean.
474
475              r    realtime file (XFS_XFLAG_REALTIME)
476
477              p    prealloc (XFS_XFLAG_PREALLOC)
478
479              i    immutable (XFS_XFLAG_IMMUTABLE)
480
481              a    append only (XFS_XFLAG_APPEND)
482
483              s    synchronous file writes (XFS_XFLAG_SYNC)
484
485              A    noatime (XFS_XFLAG_NOATIME)
486
487              d    nodump (XFS_XFLAG_NODUMP)
488
489              t    inherit realtime flag (XFS_XFLAG_RTINHERIT)"
490
491              P    inherit project id (XFS_XFLAG_PROJINHERIT)
492
493              n    no symlink creation (XFS_XFLAG_NOSYMLINKS)
494
495              e    extent size hint (XFS_XFLAG_EXTSIZE)
496
497              E    inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)
498
499              f    nodefrag (XFS_XFLAG_NODEFRAG)
500
501              S    filestream allocator (XFS_XFLAG_FILESTREAM)
502
503              x    direct access persistent memory (XFS_XFLAG_DAX)
504
505              C    copy on write extent hint (XFS_XFLAG_COWEXTSIZE)
506
507              X    has extended attributes (XFS_XFLAG_HASATTR)
508
509       chattr [ -R | -D ] [ +/-riasAdtPneEfSxC ]
510              Change extended inode flags on the currently open file.  The  -R
511              and -D options have the same meaning as above.
512
513              See the lsattr command above for the list of inode flag letters.
514
515       flink path
516              Link  the  currently  open  file  descriptor into the filesystem
517              namespace.
518       stat [ -v|-r ]
519              Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
520              call  on  the  current  file. If the -v option is specified, the
521              atime (last  access),  mtime  (last  modify),  and  ctime  (last
522              change)  timestamps are also displayed.  The -r option dumps raw
523              fields from the stat structure.
524       statx [ -v|-r ][ -m basic | -m all | -m <mask> ][ -FD ]
525              Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
526              call on the current file.
527                 -v  Show timestamps.
528                 -r  Dump raw statx structure values.
529                 -m basic
530                     Set  the  field  mask  for  the  statx  call to STATX_BA‐
531                     SIC_STATS.
532                 -m all
533                     Set the the field mask for the statx  call  to  STATX_ALL
534                     (default).
535                 -m <mask>
536                     Specify a numeric field mask for the statx call.
537                 -F  Force the attributes to be synced with the server.
538                 -D  Don't sync attributes with the server.
539
540       chproj [ -R|-D ]
541              Modifies  the  project  identifier  associated  with the current
542              path. The -R option will recursively descend if the current path
543              is  a  directory.  The  -D option will also recursively descend,
544              only setting modifying  projects  on  subdirectories.   See  the
545              xfs_quota(8)  manual  page  for  more  information about project
546              identifiers.
547
548       lsproj [ -R|-D ]
549              Displays the project  identifier  associated  with  the  current
550              path.  The  -R  and -D options behave as described above, in ch‐
551              proj.
552
553       parent [ -cpv ]
554              By default this command prints out the parent inode numbers, in‐
555              ode  generation numbers and basenames of all the hardlinks which
556              point to the inode of the current file.
557                 -p  the output is similar to the default output except  path‐
558                     names  up  to  the mount-point are printed out instead of
559                     the component name.
560                 -c  the file's filesystem  will  check  all  the  parent  at‐
561                     tributes for consistency.
562                 -v  verbose output will be printed.
563              [NOTE: Not currently operational on Linux.]
564
565       utimes atime_sec atime_nsec mtime_sec mtime_nsec
566              The  utimes  command  changes the atime and mtime of the current
567              file.  sec uses UNIX  timestamp  notation  and  is  the  seconds
568              elapsed  since 1970-01-01 00:00:00 UTC.  nsec is the nanoseconds
569              since the sec. This value needs to be in the  range  0-999999999
570              with  UTIME_NOW  and  UTIME_OMIT  being  exceptions.  Each (sec,
571              nsec) pair constitutes a single timestamp value.
572
573
574

MEMORY MAPPED I/O COMMANDS

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

FILESYSTEM COMMANDS

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

OTHER COMMANDS

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

SEE ALSO

885       mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8),  xfs(5),  fdatasync(2),
886       fstat(2),  fstatfs(2),  fsync(2),  ftruncate(2),  futimens(3), mmap(2),
887       msync(2), open(2), pread(2), pwrite(2), readdir(3), dmsetup(8).
888
889
890
891                                                                     xfs_io(8)
Impressum