]>
Commit | Line | Data |
---|---|---|
e246ba5f NS |
1 | .TH xfs_io 8 |
2 | .SH NAME | |
48c46ee3 | 3 | xfs_io \- debug the I/O path of an XFS filesystem |
e246ba5f NS |
4 | .SH SYNOPSIS |
5 | .nf | |
48c46ee3 | 6 | \f3xfs_io\f1 [ \f3\-c\f1 cmd ] ... [ \f3\-p\f1 prog ] [ \f3\-adFfmrRstx\f1 ] file |
e246ba5f NS |
7 | .fi |
8 | .SH DESCRIPTION | |
2a1888c5 | 9 | \f2xfs_io\f1 is a debugging tool like \f2xfs_db\f1, but is aimed |
7289a92c | 10 | at examining the regular file I/O paths rather than the raw XFS volume |
e246ba5f | 11 | itself. |
7289a92c NS |
12 | These code paths include not only the obvious read/write/mmap interfaces |
13 | for manipulating files, but also cover all of the XFS extensions (such | |
14 | as space preallocation, additional inode flags, etc). | |
e246ba5f NS |
15 | .PP |
16 | The options to \f2xfs_io\f1 are: | |
17 | .TP 10 | |
18 | \f3\-c\f1 \f2cmd\f1 | |
19 | \f2xfs_io\f1 commands may be run interactively (the default) | |
20 | or as arguments on the command line. | |
21 | Multiple \f3\-c\f1 arguments may be given. | |
22 | The commands are run in the sequence given, then the program exits. | |
e246ba5f NS |
23 | .TP |
24 | \f3\-p\f1 \f2prog\f1 | |
25 | Set the program name for prompts and some error messages, | |
26 | the default value is \f2xfs_io\f1. | |
27 | .TP | |
f72d20ad | 28 | \f3\-F\f1 |
c0211f67 | 29 | Allow \f2file\f1 to reside in non-XFS (foreign) filesystems. |
f72d20ad NS |
30 | This mode has a restricted set of commands. |
31 | .TP | |
32 | \f3\-f\f1 | |
33 | Create \f2file\f1 if it does not already exist. | |
34 | .TP | |
e246ba5f NS |
35 | \f3\-r\f1 |
36 | Open \f2file\f1 read-only, initially. | |
48c46ee3 NS |
37 | .TP |
38 | \f3\-x\f1 | |
39 | Expert mode. | |
40 | Dangerous commands are only available in this mode. | |
41 | These commands also tend to require additional privileges. | |
42 | .PP | |
43 | The other \f2open\f1(2) options described below are also available | |
44 | from the command line. | |
e246ba5f | 45 | .SH CONCEPTS |
48c46ee3 NS |
46 | \f2xfs_io\f1 maintains a number of open files and memory mappings. |
47 | Files can be initially opened on the command line (optionally), | |
48 | and additional files can also be opened later. | |
49 | .PP | |
50 | \f2xfs_io\f1 commands can be broken up into three groups. | |
51 | Some commands are aimed at doing regular file I/O - read, write, | |
52 | sync, space preallocation, etc. | |
53 | .PP | |
54 | The second set of commands exist for manipulating memory mapped regions | |
55 | of a file - mapping, accessing, storing, unmapping, flushing, etc. | |
e246ba5f | 56 | .PP |
48c46ee3 NS |
57 | The remaining commands are for the navigation and display of data |
58 | structures relating to the open files, mappings, and the filesystems | |
59 | where they reside. | |
e246ba5f NS |
60 | .PP |
61 | Many commands have extensive online help. | |
62 | Use the \f3help\f1 command for more details on any command. | |
48c46ee3 | 63 | .SH FILE I/O COMMANDS |
c0211f67 NS |
64 | .TP |
65 | \f3file\f1 [ \f2N\f1 ] | |
66 | Display a list of all open files and (optionally) switch to an alternate | |
67 | current open file. | |
e246ba5f | 68 | .TP 10 |
48c46ee3 | 69 | \f3open\f1 [ \f2\-FacdfrstR\f1 ] [ \f2path\f1 ] |
e246ba5f | 70 | Closes the current file, and opens the file specified by \f2path\f1 instead. |
48c46ee3 | 71 | Without any arguments, displays statistics about the current file \- |
e246ba5f NS |
72 | see the \f3stat\f1 command. |
73 | .br | |
f72d20ad NS |
74 | The \f3\-F\f1 option allows non-XFS (foreign) files to be opened and |
75 | operated on with a restricted command set. | |
76 | .br | |
e246ba5f NS |
77 | The \f3\-a\f1 option opens append-only (O_APPEND). |
78 | .br | |
48c46ee3 | 79 | The \f3\-d\f1 option opens for direct I/O (O_DIRECT). |
e246ba5f | 80 | .br |
48c46ee3 | 81 | The \f3\-f\f1 option creates the file if it doesn't already exist (O_CREAT). |
e246ba5f NS |
82 | .br |
83 | The \f3\-r\f1 option opens read-only (O_RDONLY). | |
84 | .br | |
48c46ee3 | 85 | The \f3\-s\f1 option opens for synchronous I/O (O_SYNC). |
e246ba5f NS |
86 | .br |
87 | The \f3\-t\f1 option truncates on open (O_TRUNC). | |
88 | .br | |
48c46ee3 | 89 | The \f3\-R\f1 option marks the file as a realtime XFS file after |
e246ba5f NS |
90 | opening it, if it is not already marked as such. |
91 | .TP | |
48c46ee3 NS |
92 | \f3o\f1 |
93 | See the \f3open\f1 command. | |
94 | .TP | |
95 | \f3close\f1 | |
96 | Closes the current open file, marking the next open file as current | |
97 | (if one exists). | |
98 | .TP | |
99 | \f3c\f1 | |
100 | See the \f3close\f1 command. | |
101 | .TP | |
102 | \f3pread\f1 [ \f2\-b bsize\f1 ] [ \f2\-v\f1 ] | |
e246ba5f NS |
103 | Reads a range of bytes in a specified blocksize from the given offset. |
104 | .br | |
105 | The \f3\-b\f1 option can be used to set the blocksize into which the | |
106 | \f2read\f1(2) requests will be split. | |
107 | The default blocksize is 4096 bytes. | |
108 | .br | |
109 | The \f3\-v\f1 option will dump the contents of the buffer after reading, | |
110 | by default only the count of bytes actually read is dumped. | |
111 | .TP | |
48c46ee3 NS |
112 | \f3r\f1 |
113 | See the \f3pread\f1 command. | |
114 | .TP | |
115 | \f3pwrite\f1 [ \f2\-i file\f1 ] [ \f2\-d\f1 ] [ \f2\-s skip\f1 ] [ \f2\-b size\f1 ] [ \f2\-S seed\f1 ] | |
e246ba5f NS |
116 | Writes a range of bytes in a specified blocksize from the given offset. |
117 | The bytes written can be either a set pattern or read in from another | |
118 | file before writing. | |
119 | .br | |
120 | The \f3\-i\f1 option allows an input file to be specified as the source | |
121 | of the data to be written. | |
122 | .br | |
48c46ee3 NS |
123 | The \f3\-d\f1 option will cause direct I/O, rather than the usual buffered |
124 | I/O, to be used when reading the input file. | |
e246ba5f NS |
125 | .br |
126 | The \f3\-s\f1 options specifies the number of bytes to skip from the | |
127 | start of the input file before starting to read. | |
128 | .br | |
129 | The \f3\-b\f1 option can be used to set the blocksize into which the | |
48c46ee3 | 130 | \f2write\f1(2) requests will be split. |
e246ba5f NS |
131 | The default blocksize is 4096 bytes. |
132 | The \f3\-S\f1 option is used to set the (repeated) fill pattern which | |
133 | is used when the data to write is not coming from a file. | |
134 | The default buffer fill pattern value is 0xcdcdcdcd. | |
135 | .TP | |
48c46ee3 NS |
136 | \f3w\f1 |
137 | See the \f3pwrite\f1 command. | |
e246ba5f | 138 | .TP |
48c46ee3 NS |
139 | \f3bmap\f1 [ \f2\-adlpv\f1 ] [ \f2\-n nx\f1 ] |
140 | Prints the block mapping for the current open file. | |
2a1888c5 | 141 | Refer to the \f2xfs_bmap\f1 manual page for complete documentation. |
e246ba5f | 142 | .TP |
54d46c1c NS |
143 | \f3extsize\f1 [ \f2\-R\f1 | \f2\-D\f1 ] [ \f2value\f1 ] |
144 | Display and/or modify the preferred extent size used when allocating | |
145 | space for the currently open file. | |
146 | If the \f2-R\f1 option is specified, a recursive descent is performed | |
147 | for all directory entries below the currently open file (\f2-D\f1 can | |
148 | be used to restrict the output to directories only). | |
149 | If the target file is a directory, then the inherited extent size | |
150 | is set for that directory (new files created in that directory | |
151 | inherit that extent size). | |
152 | The \f2value\f1 should be specified in bytes, or using one of the | |
153 | usual units suffixes (k, m, g, b, etc). | |
154 | The extent size is always reported in units of bytes. | |
155 | .TP | |
48c46ee3 NS |
156 | \f3allocsp\f1 \f2offset\f1 \f2length\f1 |
157 | Allocates zeroed space for part of a file using the XFS_IOC_ALLOCSP | |
2a1888c5 | 158 | system call described in the \f2xfs\f1 manual page. |
e246ba5f | 159 | .TP |
48c46ee3 NS |
160 | \f3freesp\f1 \f2offset\f1 \f2length\f1 |
161 | Frees space for part of a file using the XFS_IOC_FREESP | |
2a1888c5 | 162 | system call described in the \f2xfs\f1 manual page. |
48c46ee3 NS |
163 | .TP |
164 | \f3fadvise\f1 [ \f2\-dnrsw\f1 ] | |
165 | On platforms which support it, allows hints be given to the system | |
166 | regarding the expected I/O patterns on the file. | |
167 | The hints are similar to those of the \f3madvise\f1 command, | |
168 | discussed later. | |
169 | .TP | |
170 | \f3fdatasync\f1 | |
171 | Calls \f2fdatasync\f1(2) to flush the file's in-core data to disk. | |
172 | .TP | |
173 | \f3fsync\f1 | |
174 | Calls \f2fsync\f1(2) to flush all in-core file state to disk. | |
175 | .TP | |
176 | \f3s\f1 | |
177 | See the \f3fsync\f1 command. | |
e246ba5f NS |
178 | .TP |
179 | \f3resvsp\f1 \f2offset\f1 \f2length\f1 | |
180 | Allocates reserved, unwritten space for part of a file using the XFS_IOC_RESVSP | |
2a1888c5 | 181 | system call described in the \f2xfs\f1 manual page. |
e246ba5f NS |
182 | .TP |
183 | \f3unresvsp\f1 \f2offset\f1 \f2length\f1 | |
184 | Frees reserved space for part of a file using the XFS_IOC_UNRESVSP | |
2a1888c5 | 185 | system call described in the \f2xfs\f1 manual page. |
e246ba5f | 186 | .TP |
48c46ee3 NS |
187 | \f3truncate\f1 \f2offset\f1 |
188 | Truncates the current file at the given offset using \f2ftruncate\f1(2). | |
c0211f67 NS |
189 | .TP |
190 | \f3sendfile\f1 \f2\-i infile\f1 | \f2\-f N\f1 [ \f2offset\f1 \f2length\f1 ] | |
191 | On platforms which support it, allows a direct in-kernel copy between | |
192 | two file descriptors. | |
193 | The current open file is the target, the source must be specified as | |
194 | another open file (\f2-f\f1) or by path (\f2-i\f2). | |
48c46ee3 NS |
195 | |
196 | .SH MEMORY MAPPED I/O COMMANDS | |
197 | .TP | |
c0211f67 | 198 | \f3mmap\f1 [ \f2-rwx\f1 ] [[ N ] | [ \f2offset\f1 \f2length\f1 ]] |
48c46ee3 NS |
199 | With no arguments, \f3mmap\f1 shows the current mappings. |
200 | Specifying a single numeric argument sets the current mapping. | |
201 | If two arguments are specified (a range), a new mapping is created | |
202 | spanning the range, and the protection mode can be given as a combination of | |
203 | PROT_READ (\f2-r\f1), PROT_WRITE (\f2-w\f1), and PROT_EXEC (\f2-x\f1). | |
204 | .TP | |
205 | \f3mm\f1 | |
206 | See the \f3mmap\f1 command. | |
207 | .TP | |
208 | \f3munmap\f1 | |
209 | Unmaps the current memory mapping. | |
210 | .TP | |
211 | \f3mu\f1 | |
212 | See the \f3munmap\f1 command. | |
213 | .TP | |
214 | \f3mread\f1 [ \-\f2frv\f1 ] | |
215 | Accesses a segment of the current memory mapping, optionally dumping it to | |
216 | the standard output stream (with \f2-v\f1 or \f2-f\f1 option) for inspection. | |
217 | The accesses are performed sequentially from the start offset by default, | |
218 | but can also be done from the end backwards through the mapping if | |
219 | the \f2-r\f1 option in specified. | |
220 | The two verbose modes differ only in the relative offsets they display, | |
221 | the \f2-f\f1 option is relative to file start, whereas \f2-v\f1 shows | |
222 | offsets relative to the start of the mapping. | |
223 | .TP | |
224 | \f3mr\f1 | |
225 | See the \f3mread\f1 command. | |
226 | .TP | |
227 | \f3mwrite\f1 [ \f2-r\f1 ] [ \f2-S seed\f1 ] | |
228 | Stores a byte into memory for a range within a mapping. | |
229 | The default stored value is 'X', repeated to fill the range specified, | |
230 | but this can be changed using the \f2-S\f1 option. | |
231 | The memory stores are performed sequentially from the start offset by default, | |
232 | but can also be done from the end backwards through the mapping if the \-\f2r\f1 | |
233 | option in specified. | |
234 | .TP | |
235 | \f3mw\f1 | |
236 | See the \f3mwrite\f1 command. | |
237 | .TP | |
238 | \f3msync\f1 | |
239 | Writes all modified copies of pages over the specified range (or entire | |
240 | mapping if no range specified) to their backing storage locations. | |
241 | Also, optionally invalidates (\f2-i\f1) so that subsequent references to | |
242 | the pages will be obtained from their backing storage locations (instead | |
243 | of cached copies). | |
244 | The flush can be done synchronously (\f2-s\f1) or asynchronously (\f2-a\f1). | |
245 | .TP | |
246 | \f3ms\f1 | |
247 | See the \f3msync\f1 command. | |
248 | .TP | |
249 | \f3madvise\f1 [ \-\f2drwsw\f1 ] [ \f2offset\f1 \f2length\f1 ] | |
250 | Modifies page cache behavior when operating on the current mapping. | |
251 | The range arguments are required by some advise commands ([*] below). | |
252 | With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead). | |
253 | The \f2-d\f1 option says the pages will not be needed (POSIX_MADV_DONTNEED[*]). | |
254 | The \f2-r\f1 option says to expect random page references (POSIX_MADV_RANDOM), | |
255 | which sets readahead to zero. | |
256 | The \f2-s\f1 option says to expect sequential page references | |
257 | (POSIX_MADV_SEQUENTIAL), which doubles the default readahead on the file. | |
258 | The \f2-w\f1 option advises the specified pages will be needed | |
259 | again (POSIX_MADV_WILLNEED[*]) which forces the maximum readahead. | |
260 | .TP | |
261 | \f3mincore\f1 | |
262 | Dumps a list of pages or ranges of pages that are currently in core, | |
263 | for the current memory mapping. | |
264 | ||
265 | .SH OTHER COMMANDS | |
e246ba5f | 266 | .TP |
48c46ee3 NS |
267 | \f3print\f1 |
268 | Display a list of all open files and memory mapped regions. | |
269 | The current file and current mapping are distinguishable from | |
270 | any others. | |
271 | .TP | |
272 | \f3p\f1 | |
273 | See the \f3print\f1 command. | |
274 | .TP | |
275 | \f3quit\f1 | |
276 | Exit \f2xfs_io\f1. | |
277 | .TP | |
278 | \f3q\f1 | |
279 | See the \f3quit\f1 command. | |
280 | .TP | |
3392325d | 281 | \f3lsattr\f1 [ \f2\-R\f1 | \f2\-D\f1 | \f2\-a\f1 | \f2\-v\f1 ] |
48c46ee3 | 282 | List extended inode flags on the currently open file. |
3392325d NS |
283 | If the \f2-R\f1 option is specified, a recursive descent is performed |
284 | for all directory entries below the currently open file (\f2-D\f1 can | |
285 | be used to restrict the output to directories only). | |
286 | This is a depth first descent, it does not follow symlinks and | |
287 | it also does not cross mount points. | |
48c46ee3 | 288 | .TP |
3392325d | 289 | \f3chattr\f1 [ \f2\-R\f1 | \f2\-D\f1 ] [ \f2+/\-riasAdtPn\f1 ] |
48c46ee3 | 290 | Change extended inode flags on the currently open file. |
3392325d NS |
291 | The \f2-R\f1 and \f2-D\f1 options have the same meaning as above. |
292 | The mapping between each letter and the inode flags (refer to | |
293 | \f2xfsctl\f1(3) for the full list) is available via the \f3help\f1 command. | |
48c46ee3 NS |
294 | .TP |
295 | \f3freeze\f1 | |
296 | Suspend all write I/O requests to the filesystem of the current file. | |
297 | Only available in expert mode and requires privileges. | |
298 | .TP | |
299 | \f3thaw\f1 | |
300 | Undo the effects of a filesystem freeze operation. | |
301 | Only available in expert mode and requires privileges. | |
302 | .TP | |
303 | \f3inject\f1 [ \f2tag\f1 ] | |
304 | Inject errors into a filesystem to observe filesystem behavior at | |
305 | specific points under adverse conditions. | |
306 | Without an argument, displays the list of error tags available. | |
307 | Only available in expert mode and requires privileges. | |
308 | .TP | |
309 | \f3resblks\f1 [ \f2blocks\f1 ] | |
310 | Get and/or set count of reserved filesystem blocks using the | |
2a1888c5 | 311 | XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. |
48c46ee3 NS |
312 | Note \-\- this can be useful for exercising out of space behavior. |
313 | Only available in expert mode and requires privileges. | |
314 | .TP | |
315 | \f3shutdown\f1 [ \f2\-f\f1 ] | |
316 | Force the filesystem to shutdown (with or without flushing the log). | |
317 | Only available in expert mode and requires privileges. | |
318 | .TP | |
319 | \f3stat\f1 [ \f2\-v\f1 ] | |
e246ba5f | 320 | Selected statistics from \f2stat\f1(2) and the XFS_IOC_GETXATTR |
2a1888c5 | 321 | system call on the current file. |
e246ba5f NS |
322 | If the \f2-v\f1 option is specified, the atime (last access), mtime |
323 | (last modify), and ctime (last change) timestamps are also displayed. | |
324 | .TP | |
325 | \f3statfs\f1 | |
326 | Selected statistics from \f2statfs\f1(2) and the XFS_IOC_FSGEOMETRY | |
2a1888c5 | 327 | system call on the filesystem where the current file resides. |
258b00ea TS |
328 | .TP |
329 | \f3parent\f1 [ \f2\-cpv\f1 ] | |
330 | By default this command prints out the parent inode numbers, | |
331 | inode generation numbers and basenames of all the hardlinks which | |
332 | point to the inode of the current file. | |
333 | If the \f2-p\f1 option is specified, then the output is similar | |
334 | to the default output except pathnames up to the mount-point | |
335 | are printed out instead of the component name. | |
336 | If the \f2-c\f1 option is specified, then the file's filesystem | |
337 | will check all the parent attributes for consistency. | |
338 | If the \f2-v\f1 option is specified, then verbose output will be | |
339 | printed. | |
340 | Not currently operational on Linux. | |
2a1888c5 NS |
341 | |
342 | .SH IRIX SEE ALSO | |
343 | mkfs_xfs(1M), | |
344 | syssgi(2), | |
345 | xfs_bmap(1M), | |
346 | xfs_db(1M), | |
347 | xfs(4). | |
348 | ||
349 | .SH LINUX SEE ALSO | |
350 | mkfs.xfs(8), | |
351 | xfsctl(3), | |
352 | xfs_bmap(8), | |
353 | xfs_db(8), | |
354 | xfs(5). | |
48c46ee3 | 355 | |
e246ba5f NS |
356 | .SH SEE ALSO |
357 | fdatasync(2), | |
358 | fstat(2), | |
359 | fstatfs(2), | |
360 | fsync(2), | |
361 | ftruncate(2), | |
48c46ee3 | 362 | mmap(2), |
e246ba5f NS |
363 | open(2), |
364 | pread(2), | |
2a1888c5 | 365 | pwrite(2). |