1xfs_io(8) System Manager's Manual xfs_io(8)
2
6 xfs_io - debug the I/O path of an XFS filesystem
7
9 xfs_io [ -adfmrRstx ] [ -c cmd ] ... [ -p prog ] file
10
12 xfs_io is a debugging tool like xfs_db(8), but is aimed at examining
13 the regular file I/O paths rather than the raw XFS volume itself.
14 These code paths include not only the obvious read/write/mmap inter‐
15 faces for manipulating files, but also cover all of the XFS extensions
16 (such as space preallocation, additional inode flags, etc).
17
19 -c cmd xfs_io commands may be run interactively (the default) or as
20 arguments on the command line. Multiple -c arguments may be
21 given. The commands are run in the sequence given, then the
22 program exits.
23 -p prog Set the program name for prompts and some error messages, the
25 default value is xfs_io.
26 -f Create file if it does not already exist.
28 -r Open file read-only, initially. This is required if file is
30 immutable or append-only.
31 -x Expert mode. Dangerous commands are only available in this
33 mode. These commands also tend to require additional privi‐
34 leges.
35 The other open(2) options described below are also available from the
37 command line.
38
40 xfs_io maintains a number of open files and memory mappings. Files can
41 be initially opened on the command line (optionally), and additional
42 files can also be opened later.
43 xfs_io commands can be broken up into three groups. Some commands are
45 aimed at doing regular file I/O - read, write, sync, space prealloca‐
46 tion, etc.
47 The second set of commands exist for manipulating memory mapped regions
49 of a file - mapping, accessing, storing, unmapping, flushing, etc.
50 The remaining commands are for the navigation and display of data
52 structures relating to the open files, mappings, and the filesystems
53 where they reside.
54 Many commands have extensive online help. Use the help command for more
56 details on any command.
57
59 file [ N ]
60 Display a list of all open files and (optionally) switch to an
61 alternate current open file.
62 open [[ -acdfrstR ] path ]
64 Closes the current file, and opens the file specified by path
65 instead. Without any arguments, displays statistics about the
66 current file - see the stat command.
67 -a opens append-only (O_APPEND).
68 -d opens for direct I/O (O_DIRECT).
69 -f creates the file if it doesn't already exist (O_CREAT).
70 -r opens read-only (O_RDONLY).
71 -s opens for synchronous I/O (O_SYNC).
72 -t truncates on open (O_TRUNC).
73 -R marks the file as a realtime XFS file after opening it,
74 if it is not already marked as such.
75 o See the open command.
77 close Closes the current open file, marking the next open file as cur‐
79 rent (if one exists).
80 c See the close command.
82 pread [ -b bsize ] [ -v ] offset length
84 Reads a range of bytes in a specified blocksize from the given
85 offset.
86 -b can be used to set the blocksize into which the read(2)
87 requests will be split. The default blocksize is 4096
88 bytes.
89 -v dump the contents of the buffer after reading, by default
90 only the count of bytes actually read is dumped.
91 r See the pread command.
93 pwrite [ -i file ] [ -d ] [ -s skip ] [ -b size ] [ -S seed ] offset
95 length
96 Writes a range of bytes in a specified blocksize from the given
97 offset. The bytes written can be either a set pattern or read
98 in from another file before writing.
99 -i allows an input file to be specified as the source of the
100 data to be written.
101 -d causes direct I/O, rather than the usual buffered I/O, to
102 be used when reading the input file.
103 -s specifies the number of bytes to skip from the start of
104 the input file before starting to read.
105 -b used to set the blocksize into which the write(2)
106 requests will be split. The default blocksize is 4096
107 bytes.
108 -S used to set the (repeated) fill pattern which is used
109 when the data to write is not coming from a file. The
110 default buffer fill pattern value is 0xcdcdcdcd.
111 w See the pwrite command.
113 bmap [ -adlpv ] [ -n nx ]
115 Prints the block mapping for the current open file. Refer to the
116 xfs_bmap(8) manual page for complete documentation.
117 extsize [ -R | -D ] [ value ]
119 Display and/or modify the preferred extent size used when allo‐
120 cating space for the currently open file. If the -R option is
121 specified, a recursive descent is performed for all directory
122 entries below the currently open file (-D can be used to
123 restrict the output to directories only). If the target file is
124 a directory, then the inherited extent size is set for that
125 directory (new files created in that directory inherit that
126 extent size). The value should be specified in bytes, or using
127 one of the usual units suffixes (k, m, g, b, etc). The extent
128 size is always reported in units of bytes.
129 allocsp size 0
131 Sets the size of the file to size and zeroes any additional
132 space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system
133 call described in the xfsctl(3) manual page. allocsp and freesp
134 do exactly the same thing.
135 freesp size 0
137 See the allocsp command.
138 fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
140 On platforms which support it, allows hints be given to the sys‐
141 tem regarding the expected I/O patterns on the file. The range
142 arguments are required by some advise commands ([*] below), and
143 the others must have no range arguments. With no arguments, the
144 POSIX_FADV_NORMAL advice is implied (default readahead).
145 -d the data will not be accessed again in the near future
146 (POSIX_FADV_DONTNEED[*]).
147 -n data will be accessed once and not be reused
148 (POSIX_FADV_NOREUSE[*]).
149 -r expect access to data in random order (POSIX_FADV_RAN‐
150 DOM), which sets readahead to zero.
151 -s expect access to data in sequential order
152 (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
153 head on the file.
154 -w advises the specified data will be needed again
155 (POSIX_FADV_WILLNEED[*]) which forces the maximum reada‐
156 head.
157 fdatasync
159 Calls fdatasync(2) to flush the file's in-core data to disk.
160 fsync Calls fsync(2) to flush all in-core file state to disk.
162 s See the fsync command.
164 resvsp offset length
166 Allocates reserved, unwritten space for part of a file using the
167 XFS_IOC_RESVSP system call described in the xfsctl(3) manual
168 page.
169 unresvsp offset length
171 Frees reserved space for part of a file using the
172 XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual
173 page.
174 falloc [ -k ] offset length
176 Allocates reserved, unwritten space for part of a file using the
177 fallocate routine as described in the fallocate(2) manual page.
178 -k will set the FALLOC_FL_KEEP_SIZE flag as described in
179 fallocate(2).
180 truncate offset
182 Truncates the current file at the given offset using ftrun‐
183 cate(2).
184 sendfile -i srcfile | -f N [ offset length ]
186 On platforms which support it, allows a direct in-kernel copy
187 between two file descriptors. The current open file is the tar‐
188 get, the source must be specified as another open file (-f) or
189 by path (-i).
190
193 mmap [ N | [[ -rwx ] offset length ]]
194 With no arguments, mmap shows the current mappings. Specifying a
195 single numeric argument N sets the current mapping. If two argu‐
196 ments are specified (a range specified by offset and length), a
197 new mapping is created spanning the range, and the protection
198 mode can be given as a combination of PROT_READ (-r), PROT_WRITE
199 (-w), and PROT_EXEC (-x).
200 mm See the mmap command.
202 munmap Unmaps the current memory mapping.
204 mu See the munmap command.
206 mread [ -f | -v ] [ -r ] [ offset length ]
208 Accesses a segment of the current memory mapping, optionally
209 dumping it to the standard output stream (with -v or -f option)
210 for inspection. The accesses are performed sequentially from the
211 start offset by default, but can also be done from the end back‐
212 wards through the mapping if the -r option in specified. The
213 two verbose modes differ only in the relative offsets they dis‐
214 play, the -f option is relative to file start, whereas -v shows
215 offsets relative to the start of the mapping.
216 mr See the mread command.
218 mwrite [ -r ] [ -S seed ] [ offset length ]
220 Stores a byte into memory for a range within a mapping. The
221 default stored value is 'X', repeated to fill the range speci‐
222 fied, but this can be changed using the -S option. The memory
223 stores are performed sequentially from the start offset by
224 default, but can also be done from the end backwards through the
225 mapping if the -r option in specified.
226 mw See the mwrite command.
228 msync [ -i ] [ -a | -s ] [ offset length ]
230 Writes all modified copies of pages over the specified range (or
231 entire mapping if no range specified) to their backing storage
232 locations. Also, optionally invalidates (-i) so that subsequent
233 references to the pages will be obtained from their backing
234 storage locations (instead of cached copies). The flush can be
235 done synchronously (-s) or asynchronously (-a).
236 ms See the msync command.
238 madvise [ -d | -r | -s | -w ] [ offset length ]
240 Modifies page cache behavior when operating on the current map‐
241 ping. The range arguments are required by some advise commands
242 ([*] below). With no arguments, the POSIX_MADV_NORMAL advice is
243 implied (default readahead).
244 -d the pages will not be needed (POSIX_MADV_DONTNEED[*]).
245 -r expect random page references (POSIX_MADV_RANDOM), which
246 sets readahead to zero.
247 -s expect sequential page references (POSIX_MADV_SEQUEN‐
248 TIAL), which doubles the default readahead on the file.
249 -w advises the specified pages will be needed again
250 (POSIX_MADV_WILLNEED[*]) which forces the maximum reada‐
251 head.
252 mincore
254 Dumps a list of pages or ranges of pages that are currently in
255 core, for the current memory mapping.
256
259 print Display a list of all open files and memory mapped regions. The
260 current file and current mapping are distinguishable from any
261 others.
262 p See the print command.
264 quit Exit xfs_io.
266 q See the quit command.
268 lsattr [ -R | -D | -a | -v ]
270 List extended inode flags on the currently open file. If the -R
271 option is specified, a recursive descent is performed for all
272 directory entries below the currently open file (-D can be used
273 to restrict the output to directories only). This is a depth
274 first descent, it does not follow symlinks and it also does not
275 cross mount points.
276 chattr [ -R | -D ] [ +/-riasAdtPneEfS ]
278 Change extended inode flags on the currently open file. The -R
279 and -D options have the same meaning as above. The mapping
280 between each letter and the inode flags (refer to xfsctl(3) for
281 the full list) is available via the help command.
282 freeze Suspend all write I/O requests to the filesystem of the current
284 file. Only available in expert mode and requires privileges.
285 thaw Undo the effects of a filesystem freeze operation. Only avail‐
287 able in expert mode and requires privileges.
288 inject [ tag ]
290 Inject errors into a filesystem to observe filesystem behavior
291 at specific points under adverse conditions. Without the tag
292 argument, displays the list of error tags available. Only
293 available in expert mode and requires privileges.
294 resblks [ blocks ]
296 Get and/or set count of reserved filesystem blocks using the
297 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. Note
298 -- this can be useful for exercising out of space behavior.
299 Only available in expert mode and requires privileges.
300 shutdown [ -f ]
302 Force the filesystem to shutdown (with or without flushing the
303 log). Only available in expert mode and requires privileges.
304 stat [ -v ]
306 Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
307 call on the current file. If the -v option is specified, the
308 atime (last access), mtime (last modify), and ctime (last
309 change) timestamps are also displayed.
310 statfs Selected statistics from statfs(2) and the XFS_IOC_FSGEOMETRY
312 system call on the filesystem where the current file resides.
313 chproj [ -R|-D ]
315 Modifies the project identifier associated with the current
316 path. The -R option will recursively descend if the current path
317 is a directory. The -D option will also recursively descend,
318 only setting modifying projects on subdirectories. See the
319 xfs_quota(8) manual page for more information about project
320 identifiers.
321 lsproj [ -R|-D ]
323 Displays the project identifier associated with the current
324 path. The -R and -D options behave as described above, in
325 chproj.
326 parent [ -cpv ]
328 By default this command prints out the parent inode numbers,
329 inode generation numbers and basenames of all the hardlinks
330 which point to the inode of the current file.
331 -p the output is similar to the default output except path‐
332 names up to the mount-point are printed out instead of
333 the component name.
334 -c the file's filesystem will check all the parent
335 attributes for consistency.
336 -v verbose output will be printed.
337 [NOTE: Not currently operational on Linux.]
338
341 mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2),
342 fstat(2), fstatfs(2), fsync(2), ftruncate(2), mmap(2), msync(2),
343 open(2), pread(2), pwrite(2).
344 xfs_io(8)