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 [ -adFfmrRstx ] [ -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 Allow file to reside in non-XFS (foreign) filesystems. This
28 mode has a restricted set of commands.
29 -f Create file if it does not already exist.
31 -r Open file read-only, initially. This is required if file is
33 immutable or append-only.
34 -x Expert mode. Dangerous commands are only available in this
36 mode. These commands also tend to require additional privi‐
37 leges.
38 The other open(2) options described below are also available from the
40 command line.
41
43 xfs_io maintains a number of open files and memory mappings. Files can
44 be initially opened on the command line (optionally), and additional
45 files can also be opened later.
46 xfs_io commands can be broken up into three groups. Some commands are
48 aimed at doing regular file I/O - read, write, sync, space prealloca‐
49 tion, etc.
50 The second set of commands exist for manipulating memory mapped regions
52 of a file - mapping, accessing, storing, unmapping, flushing, etc.
53 The remaining commands are for the navigation and display of data
55 structures relating to the open files, mappings, and the filesystems
56 where they reside.
57 Many commands have extensive online help. Use the help command for more
59 details on any command.
60
62 file [ N ]
63 Display a list of all open files and (optionally) switch to an
64 alternate current open file.
65 open [[ -FacdfrstR ] path ]
67 Closes the current file, and opens the file specified by path
68 instead. Without any arguments, displays statistics about the
69 current file - see the stat command.
70 -F allows non-XFS (foreign) files to be opened and operated
71 on with a restricted command set.
72 -a opens append-only (O_APPEND).
73 -d opens for direct I/O (O_DIRECT).
74 -f creates the file if it doesn't already exist (O_CREAT).
75 -r opens read-only (O_RDONLY).
76 -s opens for synchronous I/O (O_SYNC).
77 -t truncates on open (O_TRUNC).
78 -R marks the file as a realtime XFS file after opening it,
79 if it is not already marked as such.
80 o See the open command.
82 close Closes the current open file, marking the next open file as cur‐
84 rent (if one exists).
85 c See the close command.
87 pread [ -b bsize ] [ -v ] offset length
89 Reads a range of bytes in a specified blocksize from the given
90 offset.
91 -b can be used to set the blocksize into which the read(2)
92 requests will be split. The default blocksize is 4096
93 bytes.
94 -v dump the contents of the buffer after reading, by default
95 only the count of bytes actually read is dumped.
96 r See the pread command.
98 pwrite [ -i file ] [ -d ] [ -s skip ] [ -b size ] [ -S seed ] offset
100 length
101 Writes a range of bytes in a specified blocksize from the given
102 offset. The bytes written can be either a set pattern or read
103 in from another file before writing.
104 -i allows an input file to be specified as the source of the
105 data to be written.
106 -d causes direct I/O, rather than the usual buffered I/O, to
107 be used when reading the input file.
108 -s specifies the number of bytes to skip from the start of
109 the input file before starting to read.
110 -b used to set the blocksize into which the write(2)
111 requests will be split. The default blocksize is 4096
112 bytes.
113 -S used to set the (repeated) fill pattern which is used
114 when the data to write is not coming from a file. The
115 default buffer fill pattern value is 0xcdcdcdcd.
116 w See the pwrite command.
118 bmap [ -adlpv ] [ -n nx ]
120 Prints the block mapping for the current open file. Refer to the
121 xfs_bmap(8) manual page for complete documentation.
122 extsize [ -R | -D ] [ value ]
124 Display and/or modify the preferred extent size used when allo‐
125 cating space for the currently open file. If the -R option is
126 specified, a recursive descent is performed for all directory
127 entries below the currently open file (-D can be used to
128 restrict the output to directories only). If the target file is
129 a directory, then the inherited extent size is set for that
130 directory (new files created in that directory inherit that
131 extent size). The value should be specified in bytes, or using
132 one of the usual units suffixes (k, m, g, b, etc). The extent
133 size is always reported in units of bytes.
134 allocsp size 0
136 Sets the size of the file to size and zeroes any additional
137 space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system
138 call described in the xfsctl(3) manual page. allocsp and freesp
139 do exactly the same thing.
140 freesp size 0
142 See the allocsp command.
143 fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
145 On platforms which support it, allows hints be given to the sys‐
146 tem regarding the expected I/O patterns on the file. The range
147 arguments are required by some advise commands ([*] below), and
148 the others must have no range arguments. With no arguments, the
149 POSIX_FADV_NORMAL advice is implied (default readahead).
150 -d the data will not be accessed again in the near future
151 (POSIX_FADV_DONTNEED[*]).
152 -n data will be accessed once and not be reused
153 (POSIX_FADV_NOREUSE[*]).
154 -r expect access to data in random order (POSIX_FADV_RAN‐
155 DOM), which sets readahead to zero.
156 -s expect access to data in sequential order
157 (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
158 head on the file.
159 -w advises the specified data will be needed again
160 (POSIX_FADV_WILLNEED[*]) which forces the maximum reada‐
161 head.
162 fdatasync
164 Calls fdatasync(2) to flush the file's in-core data to disk.
165 fsync Calls fsync(2) to flush all in-core file state to disk.
167 s See the fsync command.
169 resvsp offset length
171 Allocates reserved, unwritten space for part of a file using the
172 XFS_IOC_RESVSP system call described in the xfsctl(3) manual
173 page.
174 unresvsp offset length
176 Frees reserved space for part of a file using the
177 XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual
178 page.
179 truncate offset
181 Truncates the current file at the given offset using ftrun‐
182 cate(2).
183 sendfile -i srcfile | -f N [ offset length ]
185 On platforms which support it, allows a direct in-kernel copy
186 between two file descriptors. The current open file is the tar‐
187 get, the source must be specified as another open file (-f) or
188 by path (-i).
189
192 mmap [ N | [[ -rwx ] offset length ]]
193 With no arguments, mmap shows the current mappings. Specifying a
194 single numeric argument N sets the current mapping. If two argu‐
195 ments are specified (a range specified by offset and length), a
196 new mapping is created spanning the range, and the protection
197 mode can be given as a combination of PROT_READ (-r), PROT_WRITE
198 (-w), and PROT_EXEC (-x).
199 mm See the mmap command.
201 munmap Unmaps the current memory mapping.
203 mu See the munmap command.
205 mread [ -f | -v ] [ -r ] [ offset length ]
207 Accesses a segment of the current memory mapping, optionally
208 dumping it to the standard output stream (with -v or -f option)
209 for inspection. The accesses are performed sequentially from the
210 start offset by default, but can also be done from the end back‐
211 wards through the mapping if the -r option in specified. The
212 two verbose modes differ only in the relative offsets they dis‐
213 play, the -f option is relative to file start, whereas -v shows
214 offsets relative to the start of the mapping.
215 mr See the mread command.
217 mwrite [ -r ] [ -S seed ] [ offset length ]
219 Stores a byte into memory for a range within a mapping. The
220 default stored value is 'X', repeated to fill the range speci‐
221 fied, but this can be changed using the -S option. The memory
222 stores are performed sequentially from the start offset by
223 default, but can also be done from the end backwards through the
224 mapping if the -r option in specified.
225 mw See the mwrite command.
227 msync [ -i ] [ -a | -s ] [ offset length ]
229 Writes all modified copies of pages over the specified range (or
230 entire mapping if no range specified) to their backing storage
231 locations. Also, optionally invalidates (-i) so that subsequent
232 references to the pages will be obtained from their backing
233 storage locations (instead of cached copies). The flush can be
234 done synchronously (-s) or asynchronously (-a).
235 ms See the msync command.
237 madvise [ -d | -r | -s | -w ] [ offset length ]
239 Modifies page cache behavior when operating on the current map‐
240 ping. The range arguments are required by some advise commands
241 ([*] below). With no arguments, the POSIX_MADV_NORMAL advice is
242 implied (default readahead).
243 -d the pages will not be needed (POSIX_MADV_DONTNEED[*]).
244 -r expect random page references (POSIX_MADV_RANDOM), which
245 sets readahead to zero.
246 -s expect sequential page references (POSIX_MADV_SEQUEN‐
247 TIAL), which doubles the default readahead on the file.
248 -w advises the specified pages will be needed again
249 (POSIX_MADV_WILLNEED[*]) which forces the maximum reada‐
250 head.
251 mincore
253 Dumps a list of pages or ranges of pages that are currently in
254 core, for the current memory mapping.
255
258 print Display a list of all open files and memory mapped regions. The
259 current file and current mapping are distinguishable from any
260 others.
261 p See the print command.
263 quit Exit xfs_io.
265 q See the quit command.
267 lsattr [ -R | -D | -a | -v ]
269 List extended inode flags on the currently open file. If the -R
270 option is specified, a recursive descent is performed for all
271 directory entries below the currently open file (-D can be used
272 to restrict the output to directories only). This is a depth
273 first descent, it does not follow symlinks and it also does not
274 cross mount points.
275 chattr [ -R | -D ] [ +/-riasAdtPneEfS ]
277 Change extended inode flags on the currently open file. The -R
278 and -D options have the same meaning as above. The mapping
279 between each letter and the inode flags (refer to xfsctl(3) for
280 the full list) is available via the help command.
281 freeze Suspend all write I/O requests to the filesystem of the current
283 file. Only available in expert mode and requires privileges.
284 thaw Undo the effects of a filesystem freeze operation. Only avail‐
286 able in expert mode and requires privileges.
287 inject [ tag ]
289 Inject errors into a filesystem to observe filesystem behavior
290 at specific points under adverse conditions. Without the tag
291 argument, displays the list of error tags available. Only
292 available in expert mode and requires privileges.
293 resblks [ blocks ]
295 Get and/or set count of reserved filesystem blocks using the
296 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. Note
297 -- this can be useful for exercising out of space behavior.
298 Only available in expert mode and requires privileges.
299 shutdown [ -f ]
301 Force the filesystem to shutdown (with or without flushing the
302 log). Only available in expert mode and requires privileges.
303 stat [ -v ]
305 Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
306 call on the current file. If the -v option is specified, the
307 atime (last access), mtime (last modify), and ctime (last
308 change) timestamps are also displayed.
309 statfs Selected statistics from statfs(2) and the XFS_IOC_FSGEOMETRY
311 system call on the filesystem where the current file resides.
312 parent [ -cpv ]
314 By default this command prints out the parent inode numbers,
315 inode generation numbers and basenames of all the hardlinks
316 which point to the inode of the current file.
317 -p the output is similar to the default output except path‐
318 names up to the mount-point are printed out instead of
319 the component name.
320 -c the file's filesystem will check all the parent
321 attributes for consistency.
322 -v verbose output will be printed.
323 [NOTE: Not currently operational on Linux.]
324
327 mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2),
328 fstat(2), fstatfs(2), fsync(2), ftruncate(2), mmap(2), msync(2),
329 open(2), pread(2), pwrite(2).
330 xfs_io(8)