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

MEMORY MAPPED I/O COMMANDS

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

FILESYSTEM COMMANDS

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

OTHER COMMANDS

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

SEE ALSO

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