Debian Codegraph @

upstream/debian-unstable/man8/xfs_db.8

raw
1 .TH xfs_db 8
2 .SH NAME
3 xfs_db \- debug an XFS filesystem
4 .SH SYNOPSIS
5 .B xfs_db
6 [
7 .B \-c
8 .I cmd
9 ] ... [
10 .BR \-i | r | x | F
11 ] [
12 .B \-f
13 ] [
14 .B \-l
15 .I logdev
16 ] [
17 .B \-R
18 .I rtdev
19 ] [
20 .B \-p
21 .I progname
22 ]
23 .I device
24 .br
25 .B xfs_db \-V
26 .SH DESCRIPTION
27 .B xfs_db
28 is used to examine an XFS filesystem. Under rare circumstances it can also
29 be used to modify an XFS filesystem, but that task is normally left to
30 .BR xfs_repair (8)
31 or to scripts such as
32 .BR xfs_admin (8)
33 that run
34 .BR xfs_db .
35 .PP
36 .SH OPTIONS
37 .TP
38 .BI \-c " cmd"
39 .B xfs_db
40 commands may be run interactively (the default) or as arguments
41 on the command line. Multiple
42 .B \-c
43 arguments may be given. The commands are run in the sequence given,
44 then the program exits.
45 .TP
46 .B \-f
47 Specifies that the filesystem image to be processed is stored in a
48 regular file at
49 .I device
50 (see the
51 .BR mkfs.xfs "(8) " -d
52 .I file
53 option).
54 This might happen if an image copy of a filesystem has been made into
55 an ordinary file with
56 .BR xfs_copy (8).
57 .TP
58 .B \-F
59 Specifies that we want to continue even if the superblock magic is not
60 correct. For use in
61 .BR xfs_metadump .
62 .TP
63 .B \-i
64 Allows execution on a mounted filesystem, provided it is mounted read-only.
65 Useful for shell scripts
66 which must only operate on filesystems in a guaranteed consistent state
67 (either unmounted or mounted read-only). These semantics are slightly
68 different to that of the
69 .B -r
70 option.
71 .TP
72 .BI \-l " logdev"
73 Specifies the device where the filesystems external log resides.
74 Only for those filesystems which use an external log. See the
75 .BR mkfs.xfs "(8) " \-l
76 option, and refer to
77 .BR xfs (5)
78 for a detailed description of the XFS log.
79 .TP
80 .BI \-p " progname"
81 Set the program name to
82 .I progname
83 for prompts and some error messages, the default value is
84 .BR xfs_db .
85 .TP
86 .B -R
87 .I rtdev
88 Specifies the device where the realtime data resides.
89 This is only relevant for filesystems that have a realtime section.
90 See the
91 .BR mkfs.xfs "(8) " \-r
92 option, and refer to
93 .BR xfs (5)
94 for a detailed description of the XFS realtime section.
95 .TP
96 .B -r
97 Open
98 .I device
99 or
100 .I filename
101 read-only. This option is required if the filesystem is mounted.
102 It is only necessary to omit this flag if a command that changes data
103 .RB ( write ", " blocktrash ", " crc )
104 is to be used.
105 .TP
106 .B \-x
107 Specifies expert mode.
108 This enables the
109 .RB ( write ", " blocktrash ", " crc
110 invalidate/revalidate) commands.
111 .TP
112 .B \-V
113 Prints the version number and exits.
114 .SH CONCEPTS
115 .B xfs_db
116 commands can be broken up into two classes. Most commands are for
117 the navigation and display of data structures in the filesystem.
118 Other commands are for scanning the filesystem in some way.
119 .PP
120 Commands which are used to navigate the filesystem structure take arguments
121 which reflect the names of filesystem structure fields.
122 There can be multiple field names separated by dots when the underlying
123 structures are nested, as in C.
124 The field names can be indexed (as an array index)
125 if the underlying field is an array.
126 The array indices can be specified as a range, two numbers separated by a dash.
127 .PP
128 .B xfs_db
129 maintains a current address in the filesystem.
130 The granularity of the address is a filesystem structure.
131 This can be a filesystem block,
132 an inode or quota (smaller than a filesystem block),
133 or a directory block (could be larger than a filesystem block).
134 There are a variety of commands to set the current address.
135 Associated with the current address is the current data type,
136 which is the structural type of this data.
137 Commands which follow the structure of the filesystem always set the type
138 as well as the address.
139 Commands which examine pieces of an individual file (inode) need the current
140 inode to be set, this is done with the
141 .B inode
142 command.
143 .PP
144 The current address/type information is actually maintained in a
145 stack that can be explicitly manipulated with the
146 .BR push ", " pop ", and " stack
147 commands.
148 This allows for easy examination of a nested filesystem structure.
149 Also, the last several locations visited are stored in a ring buffer
150 which can be manipulated with the
151 .BR forward ", " back ", and " ring
152 commands.
153 .PP
154 XFS filesystems are divided into a small number of allocation groups.
155 .B xfs_db
156 maintains a notion of the current allocation group which is
157 manipulated by some commands. The initial allocation group is 0.
158 .SH COMMANDS
159 .PP
160 Many commands have extensive online help. Use the
161 .B help
162 command for more details on any command.
163 .TP
164 .B a
165 See the
166 .B addr
167 command.
168 .TP
169 .BI ablock " filoff"
170 Set current address to the offset
171 .I filoff
172 (a filesystem block number) in the attribute area of the current inode.
173 .TP
174 .BI "addr [" field-expression ]
175 Set current address to the value of the
176 .IR field-expression .
177 This is used to "follow" a reference in one structure to the object
178 being referred to. If no argument is given, the current address is printed.
179 .TP
180 .BI "agf [" agno ]
181 Set current address to the AGF block for allocation group
182 .IR agno .
183 If no argument is given, use the current allocation group.
184 .TP
185 .BI "agfl [" agno ]
186 Set current address to the AGFL block for allocation group
187 .IR agno .
188 If no argument is given, use the current allocation group.
189 .TP
190 .BI "agi [" agno ]
191 Set current address to the AGI block for allocation group
192 .IR agno .
193 If no argument is given, use the current allocation group.
194 .TP
195 .BI "agresv [" agno ]
196 Displays the length, free block count, per-AG reservation size, and per-AG
197 reservation usage for a given AG.
198 If no argument is given, display information for all AGs.
199 .TP
200 .BI "attr_get [\-p|\-r|\-u|\-s|\-Z] [\-N " namefile "|" name "] "
201 Print the value of the specified extended attribute from the current file.
202 .RS 1.0i
203 .TP 0.4i
204 .B \-p
205 Sets the attribute in the parent namespace.
206 Only one namespace option can be specified.
207 .TP
208 .B \-r
209 Sets the attribute in the root namespace.
210 Only one namespace option can be specified.
211 .TP
212 .B \-u
213 Sets the attribute in the user namespace.
214 Only one namespace option can be specified.
215 .TP
216 .B \-s
217 Sets the attribute in the secure namespace.
218 Only one namespace option can be specified.
219 .TP
220 .B \-Z
221 Sets a filesystem property in the root namespace.
222 Only one namespace option can be specified.
223 .TP
224 .B \-N
225 Read the name from this file.
226 .RE
227 .TP
228 .BI "attr_list [\-p|\-r|\-u|\-s|\-Z] [\-v] "
229 Lists the extended attributes of the current file.
230 .RS 1.0i
231 .TP 0.4i
232 .B \-p
233 Sets the attribute in the parent namespace.
234 Only one namespace option can be specified.
235 .TP
236 .B \-r
237 Sets the attribute in the root namespace.
238 Only one namespace option can be specified.
239 .TP
240 .B \-u
241 Sets the attribute in the user namespace.
242 Only one namespace option can be specified.
243 .TP
244 .B \-s
245 Sets the attribute in the secure namespace.
246 Only one namespace option can be specified.
247 .TP
248 .B \-Z
249 Sets a filesystem property in the root namespace.
250 Only one namespace option can be specified.
251 .TP
252 .B \-v
253 Print the extended attribute values too.
254 .RE
255 .TP
256 .BI "attr_remove [\-p|\-r|\-u|\-s|\-Z] [\-n] [\-N " namefile "|" name "] "
257 Remove the specified extended attribute from the current file.
258 .RS 1.0i
259 .TP 0.4i
260 .B \-p
261 Sets the attribute in the parent namespace.
262 Only one namespace option can be specified.
263 .TP
264 .B \-r
265 Sets the attribute in the root namespace.
266 Only one namespace option can be specified.
267 .TP
268 .B \-u
269 Sets the attribute in the user namespace.
270 Only one namespace option can be specified.
271 .TP
272 .B \-s
273 Sets the attribute in the secure namespace.
274 Only one namespace option can be specified.
275 .TP
276 .B \-Z
277 Sets a filesystem property in the root namespace.
278 Only one namespace option can be specified.
279 .TP
280 .B \-N
281 Read the name from this file.
282 .TP
283 .B \-n
284 Do not enable 'noattr2' mode on V4 filesystems.
285 .RE
286 .TP
287 .BI "attr_set [\-p\-r|\-u|\-s|\-Z] [\-n] [\-R|\-C] [\-v " valuelen "|\-V " valuefile "] [\-N " namefile "|" name "] [" value "]"
288 Sets an extended attribute on the current file with the given name.
289 .RS 1.0i
290 .TP 0.4i
291 .B \-p
292 Sets the attribute in the parent namespace.
293 Only one namespace option can be specified.
294 .TP
295 .B \-r
296 Sets the attribute in the root namespace.
297 Only one namespace option can be specified.
298 .TP
299 .B \-u
300 Sets the attribute in the user namespace.
301 Only one namespace option can be specified.
302 .TP
303 .B \-s
304 Sets the attribute in the secure namespace.
305 Only one namespace option can be specified.
306 .TP
307 .B \-Z
308 Sets a filesystem property in the root namespace.
309 Only one namespace option can be specified.
310 .TP
311 .B \-N
312 Read the name from this file.
313 .TP
314 .B \-n
315 Do not enable 'noattr2' mode on V4 filesystems.
316 .TP
317 .B \-R
318 Replace the attribute.
319 The command will fail if the attribute does not already exist.
320 .TP
321 .B \-C
322 Create the attribute.
323 The command will fail if the attribute already exists.
324 .TP
325 .B \-V
326 Read the value from this file.
327 .TP
328 .B \-v
329 Set the attribute value to a string of this length containing the letter 'v'.
330 .RE
331 .TP
332 .B b
333 See the
334 .B back
335 command.
336 .TP
337 .B back
338 Move to the previous location in the position ring.
339 .TP
340 .B blockfree
341 Free block usage information collected by the last execution of the
342 .B blockget
343 command. This must be done before another
344 .B blockget
345 command can be given, presumably with different arguments than the previous one.
346 .TP
347 .BI "blockget [\-npvs] [\-b " bno "] ... [\-i " ino "] ..."
348 Get block usage.
349 The information is saved for use by a subsequent
350 .BR blockuse ", " ncheck ", or " blocktrash
351 command.
352 .RS 1.0i
353 .TP 0.4i
354 .B \-b
355 is used to specify filesystem block numbers about which verbose
356 information should be printed.
357 .TP
358 .B \-i
359 is used to specify inode numbers about which verbose information
360 should be printed.
361 .TP
362 .B \-n
363 is used to save pathnames for inodes visited, this is used to support the
364 .BR xfs_ncheck (8)
365 command. It also means that pathnames will be printed for inodes that have
366 problems. This option uses a lot of memory so is not enabled by default.
367 .TP
368 .B \-p
369 causes error messages to be prefixed with the filesystem name being
370 processed. This is useful if several copies of
371 .B xfs_db
372 are run in parallel.
373 .TP
374 .B \-s
375 restricts output to severe errors only. This is useful if the output is
376 too long otherwise.
377 .TP
378 .B \-v
379 enables verbose output. Messages will be printed for every block and
380 inode processed.
381 .RE
382 .TP
383 .BI "blocktrash [-z] [\-o " offset "] [\-n " count "] [\-x " min "] [\-y " max "] [\-s " seed "] [\-0|1|2|3] [\-t " type "] ..."
384 Trash randomly selected filesystem metadata blocks.
385 Trashing occurs to randomly selected bits in the chosen blocks.
386 This command is available only in debugging versions of
387 .BR xfs_db .
388 It is useful for testing
389 .BR xfs_repair "(8).
390 .RS 1.0i
391 .TP 0.4i
392 .BR \-0 " | " -1 " | " -2 " | " -3
393 These are used to set the operating mode for
394 .BR blocktrash .
395 Only one can be used:
396 .B \-0
397 changed bits are cleared;
398 .B \-1
399 changed bits are set;
400 .B -2
401 changed bits are inverted;
402 .B -3
403 changed bits are randomized.
404 .TP
405 .B \-n
406 supplies the
407 .I count
408 of block-trashings to perform (default 1).
409 .TP
410 .B \-o
411 supplies the bit
412 .I offset
413 at which to start trashing the block. If the value is preceded by a '+', the
414 trashing will start at a randomly chosen offset that is larger than the value
415 supplied. The default is to randomly choose an offset anywhere in the block.
416 .TP
417 .B \-s
418 supplies a
419 .I seed
420 to the random processing.
421 .TP
422 .B \-t
423 gives a
424 .I type
425 of blocks to be selected for trashing. Multiple
426 .B \-t
427 options may be given. If no
428 .B \-t
429 options are given then all metadata types can be trashed.
430 .TP
431 .B \-x
432 sets the
433 .I minimum
434 size of bit range to be trashed. The default value is 1.
435 .TP
436 .B \-y
437 sets the
438 .I maximum
439 size of bit range to be trashed. The default value is 1024.
440 .TP
441 .B \-z
442 trashes the block at the top of the stack. It is not necessary to
443 run
444 .BI blockget
445 if this option is supplied.
446 .RE
447 .TP
448 .BI "blockuse [\-n] [\-c " count ]
449 Print usage for current filesystem block(s).
450 For each block, the type and (if any) inode are printed.
451 .RS 1.0i
452 .TP 0.4i
453 .B \-c
454 specifies a
455 .I count
456 of blocks to process. The default value is 1 (the current block only).
457 .TP
458 .B \-n
459 specifies that file names should be printed. The prior
460 .B blockget
461 command must have also specified the
462 .B \-n
463 option.
464 .RE
465 .TP
466 .BI "bmap [\-a] [\-d] [" block " [" len ]]
467 Show the block map for the current inode.
468 The map display can be restricted to an area of the file with the
469 .I block
470 and
471 .I len
472 arguments. If
473 .I block
474 is given and
475 .I len
476 is omitted then 1 is assumed for len.
477 .IP
478 The
479 .B \-a
480 and
481 .B \-d
482 options are used to select the attribute or data
483 area of the inode, if neither option is given then both areas are shown.
484 .TP
485 .BI "bmapinflate [\-d " dirty_bytes "] [-e] [\-n " nr "]
486 Duplicates the first data fork mapping this many times, as if the mapping had
487 been repeatedly reflinked.
488 This is an expert-mode command for exercising high-refcount filesystems only.
489 Existing data fork mappings will be forgotten and the refcount btree will not
490 be updated.
491 This command leaves at least the refcount btree and the inode inconsistent;
492 .B xfs_repair
493 must be run afterwards.
494 .RS 1.0i
495 .TP 0.4i
496 .B \-d
497 Constrain the memory consumption of new dirty btree blocks to this quantity.
498 Defaults to 60MiB.
499 .TP 0.4i
500 .B \-e
501 Estimate the number of blocks and height of the new data fork mapping
502 structure and exit without changing anything.
503 .TP 0.4i
504 .B \-n
505 Create this many copies of the first mapping.
506 .RE
507 .TP
508 .B btdump [-a] [-i]
509 If the cursor points to a btree node, dump the btree from that block downward.
510 If instead the cursor points to an inode, dump the data fork block mapping btree if there is one.
511 If the cursor points to a directory or extended attribute btree node, dump that.
512 By default, only records stored in the btree are dumped.
513 .RS 1.0i
514 .TP 0.4i
515 .B \-a
516 If the cursor points at an inode, dump the extended attribute block mapping btree, if present.
517 .TP
518 .B \-i
519 Dump all keys and pointers in intermediate btree nodes, and all records in leaf btree nodes.
520 .RE
521 .TP
522 .BI "btheight [\-b " blksz "] [\-n " recs "] [\-w " max "|" min "|" absmax "|" avg "] btree types..."
523 For a given number of btree records and a btree type, report the number of
524 records and blocks for each level of the btree, and the total number of blocks.
525 The btree type must be given after the options.
526
527 A raw btree geometry can be provided in the format
528 "record_bytes:key_bytes:ptr_bytes:header_type", where header_type is one of
529 "short", "long", "shortcrc", or "longcrc".
530
531 The supported btree types are:
532 .IR bnobt ,
533 .IR cntbt ,
534 .IR inobt ,
535 .IR finobt ,
536 .IR bmapbt ,
537 .IR refcountbt ,
538 .IR rmapbt ,
539 .IR rtrefcountbt ,
540 and
541 .IR rtrmapbt .
542 The magic value
543 .I all
544 can be used to walk through all btree types.
545
546 Options are as follows:
547 .RS 1.0i
548 .TP 0.4i
549 .B \-b
550 is used to override the btree block size.
551 The default is the filesystem block size.
552 .TP
553 .B \-n
554 is used to specify the number of records to store.
555 This argument is required.
556 .TP
557 .B \-w absmax
558 shows the maximum possible height for the given btree types.
559 .TP
560 .B \-w max
561 shows only the best case scenario, which is when the btree blocks are
562 maximally loaded.
563 .TP
564 .B \-w min
565 shows only the worst case scenario, which is when the btree blocks are
566 half full.
567 .TP
568 .B \-w avg
569 shows only the average case scenario, which is when the btree blocks are
570 three quarters full.
571 .RE
572 .TP
573 .BI "convert " "type number" " [" "type number" "] ... " type
574 Convert from one address form to another.
575 The known
576 .IR type s,
577 with alternate names, are:
578 .RS 1.0i
579 .PD 0
580 .HP
581 .B agblock
582 or
583 .B agbno
584 (filesystem block within an allocation group)
585 .HP
586 .B agino
587 or
588 .B aginode
589 (inode number within an allocation group)
590 .HP
591 .B agnumber
592 or
593 .B agno
594 (allocation group number)
595 .HP
596 .B bboff
597 or
598 .B daddroff
599 (byte offset in a
600 .BR daddr )
601 .HP
602 .B blkoff
603 or
604 .B fsboff or
605 .B agboff
606 (byte offset in a
607 .B agblock
608 or
609 .BR fsblock )
610 .HP
611 .B byte
612 or
613 .B fsbyte
614 (byte address in filesystem)
615 .HP
616 .B daddr
617 or
618 .B bb
619 (disk address, 512-byte blocks)
620 .HP
621 .B fsblock
622 or
623 .B fsb
624 or
625 .B fsbno
626 (filesystem block, see the
627 .B fsblock
628 command)
629 .HP
630 .B ino
631 or
632 .B inode
633 (inode number)
634 .HP
635 .B inoidx
636 or
637 .B offset
638 (index of inode in filesystem block)
639 .HP
640 .B inooff
641 or
642 .B inodeoff
643 (byte offset in inode)
644 .PD
645 .RE
646 .IP
647 Only conversions that "make sense" are allowed.
648 The compound form (with more than three arguments) is useful for
649 conversions such as
650 .B convert agno
651 .I ag
652 .B agbno
653 .I agb
654 .BR fsblock .
655 .TP
656 .B crc [\-i|\-r|\-v]
657 Invalidates, revalidates, or validates the CRC (checksum)
658 field of the current structure, if it has one.
659 This command is available only on CRC-enabled filesystems.
660 With no argument, validation is performed.
661 Each command will display the resulting CRC value and state.
662 .RS 1.0i
663 .TP 0.4i
664 .B \-i
665 Invalidate the structure's CRC value (incrementing it by one),
666 and write it to disk.
667 .TP
668 .B \-r
669 Recalculate the current structure's correct CRC value, and write it to disk.
670 .TP
671 .B \-v
672 Validate and display the current value and state of the structure's CRC.
673 .RE
674 .TP
675 .BI "daddr [" -r "] [" d ]
676 Set current address to the daddr (512 byte block) given by
677 .IR d .
678 If no value for
679 .I d
680 is given, the current address is printed, expressed as a daddr.
681 The type is set to
682 .B data
683 (uninterpreted).
684
685 If an address and the
686 .B \-l
687 option are specified, the current address is set to the external log device.
688 If an address and the
689 .B \-r
690 option are specified, the current address is set to the realtime device.
691 .TP
692 .BI dblock " filoff"
693 Set current address to the offset
694 .I filoff
695 (a filesystem block number) in the data area of the current inode.
696 .TP
697 .BI "debug [" flagbits ]
698 Set debug option bits. These are used for debugging
699 .BR xfs_db .
700 If no value is given for
701 .IR flagbits ,
702 print the current debug option bits. These are for the use of the implementor.
703 .TP
704 .BI "dquot [" \-g | \-p | \-u ] " id"
705 Set current address to a group, project or user quota block for the given ID. Defaults to user quota.
706 .TP
707 .BI "dump_iunlinked [-a " agno " ] [-b " bucket " ] [-q] [-v]"
708 Dump the contents of unlinked buckets.
709
710 Options include:
711 .RS 1.0i
712 .TP 0.4i
713 .B \-a
714 Print only this AG's unlinked buckets.
715 .TP 0.4i
716 .B \-b
717 Print only this bucket within each AGI.
718 .TP 0.4i
719 .B \-q
720 Only print the essentials.
721 .TP 0.4i
722 .B \-v
723 Print resource usage of each file on the unlinked lists.
724 .RE
725 .TP
726 .BI "echo [" arg "] ..."
727 Echo the arguments to the output.
728 .TP
729 .B f
730 See the
731 .B forward
732 command.
733 .TP
734 .B forward
735 Move forward to the next entry in the position ring.
736 .TP
737 .B frag [\-adflqRrv]
738 Get file fragmentation data. This prints information about fragmentation
739 of file data in the filesystem (as opposed to fragmentation of freespace,
740 for which see the
741 .B freesp
742 command). Every file in the filesystem is examined to see how far from ideal
743 its extent mappings are. A summary is printed giving the totals.
744 .RS 1.0i
745 .TP 0.4i
746 .B \-v
747 sets verbosity, every inode has information printed for it.
748 The remaining options select which inodes and extents are examined.
749 If no options are given then all are assumed set,
750 otherwise just those given are enabled.
751 .TP
752 .B \-a
753 enables processing of attribute data.
754 .TP
755 .B \-d
756 enables processing of directory data.
757 .TP
758 .B \-f
759 enables processing of regular file data.
760 .TP
761 .B \-l
762 enables processing of symbolic link data.
763 .TP
764 .B \-q
765 enables processing of quota file data.
766 .TP
767 .B \-R
768 enables processing of realtime control file data.
769 .TP
770 .B \-r
771 enables processing of realtime file data.
772 .RE
773 .TP
774 .BI "freesp [\-bcds] [\-A " alignment "] [\-a " ag "] ... [\-e " i "] [\-h " h1 "] ... [\-m " m ]
775 Summarize free space for the filesystem. The free blocks are examined
776 and totalled, and displayed in the form of a histogram, with a count
777 of extents in each range of free extent sizes.
778 .RS 1.0i
779 .TP 0.4i
780 .B \-A
781 reports only free extents with starting blocks aligned to
782 .I alignment
783 blocks.
784 .TP
785 .B \-a
786 adds
787 .I ag
788 to the list of allocation groups to be processed. If no
789 .B \-a
790 options are given then all allocation groups are processed.
791 .TP
792 .B \-b
793 specifies that the histogram buckets are binary-sized, with the starting
794 sizes being the powers of 2.
795 .TP
796 .B \-c
797 specifies that
798 .B freesp
799 will search the by-size (cnt) space Btree instead of the default
800 by-block (bno) space Btree.
801 .TP
802 .B \-d
803 specifies that every free extent will be displayed.
804 .TP
805 .B \-e
806 specifies that the histogram buckets are
807 equal-sized, with the size specified as
808 .IR i .
809 .TP
810 .B \-h
811 specifies a starting block number for a histogram bucket as
812 .IR h1 .
813 Multiple
814 .BR \-h 's
815 are given to specify the complete set of buckets.
816 .TP
817 .B \-m
818 specifies that the histogram starting block numbers are powers of
819 .IR m .
820 This is the general case of
821 .BR \-b .
822 .TP
823 .B \-s
824 specifies that a final summary of total free extents,
825 free blocks, and the average free extent size is printed.
826 .RE
827 .TP
828 .B fsb
829 See the
830 .B fsblock
831 command.
832 .TP
833 .BI "fsblock [" fsb ]
834 Set current address to the fsblock value given by
835 .IR fsb .
836 If no value for
837 .I fsb
838 is given the current address is printed, expressed as an fsb.
839 The type is set to
840 .B data
841 (uninterpreted). XFS filesystem block numbers are computed
842 .RI (( agno " << " agshift ") | " agblock )
843 where
844 .I agshift
845 depends on the size of an allocation group. Use the
846 .B convert
847 command to convert to and from this form. Block numbers given for file blocks
848 (for instance from the
849 .B bmap
850 command) are in this form.
851 .TP
852 .BI "fsmap [ " start " ] [ " end " ]
853 Prints the mapping of disk blocks used by an XFS filesystem. The map
854 lists each extent used by files, allocation group metadata,
855 journalling logs, and static filesystem metadata, as well as any
856 regions that are unused. All blocks, offsets, and lengths are specified
857 in units of 512-byte blocks, no matter what the filesystem's block size is.
858 .BI "The optional " start " and " end " arguments can be used to constrain
859 the output to a particular range of disk blocks.
860 .TP
861 .BI "fuzz [\-c] [\-d] " "field action"
862 Write garbage into a specific structure field on disk.
863 Expert mode must be enabled to use this command.
864 The operation happens immediately; there is no buffering.
865 .IP
866 The fuzz command can take the following
867 .IR action "s"
868 against a field:
869 .RS 1.0i
870 .TP 0.4i
871 .B zeroes
872 Clears all bits in the field.
873 .TP 0.4i
874 .B ones
875 Sets all bits in the field.
876 .TP 0.4i
877 .B firstbit
878 Flips the first bit in the field.
879 For a scalar value, this is the highest bit.
880 .TP 0.4i
881 .B middlebit
882 Flips the middle bit in the field.
883 .TP 0.4i
884 .B lastbit
885 Flips the last bit in the field.
886 For a scalar value, this is the lowest bit.
887 .TP 0.4i
888 .B add
889 Adds a small value to a scalar field.
890 .TP 0.4i
891 .B sub
892 Subtracts a small value from a scalar field.
893 .TP 0.4i
894 .B random
895 Randomizes the contents of the field.
896 .RE
897 .IP
898 The following switches affect the write behavior:
899 .RS 1.0i
900 .TP 0.4i
901 .B \-c
902 Skip write verifiers and CRC recalculation; allows invalid data to be written
903 to disk.
904 .TP 0.4i
905 .B \-d
906 Skip write verifiers but perform CRC recalculation; allows invalid data to be
907 written to disk to test detection of invalid data.
908 .RE
909 .TP
910 .BI hash [-d|-p parent_ino]" strings
911 Prints the hash value of
912 .I string
913 using the hash function of the XFS directory and attribute implementation.
914
915 If the
916 .B \-d
917 option is specified, the directory-specific hash function is used.
918 This only makes a difference on filesystems with ascii case-insensitive
919 lookups enabled.
920
921 If the
922 .B \-p
923 option is specified, the parent pointer-specific hash function is used.
924 The parent directory inumber must be specified as an argument.
925 This only makes a difference on filesystems with ascii case-insensitive
926 lookups enabled.
927 .TP
928 .BI "hashcoll [-a] [-s seed] [-n " nr "] [-p " path "] -i | " names...
929 Create directory entries or extended attributes names that all have the same
930 hash value.
931 The metadump name obfuscation algorithm is used here.
932 Names are written to standard output, with a NULL between each name for use
933 with xargs -0.
934 .RS 1.0i
935 .PD 0
936 .TP 0.4i
937 .TP 0.4i
938 .B \-a
939 Create extended attribute names.
940 .TP 0.4i
941 .B \-i
942 Read the first name to create from standard input.
943 Up to 255 bytes are read.
944 If this option is not specified, first names are taken from the command line.
945 .TP 0.4i
946 .BI \-n " nr"
947 Create this many duplicated names.
948 The default is to create one name.
949 .TP 0.4i
950 .BI \-p " path"
951 Create directory entries or extended attributes in this file instead of
952 writing the names to standard output.
953 .TP 0.4i
954 .BI \-s " seed"
955 Seed the random number generator with this value.
956 .PD
957 .RE
958 .TP
959 .BI "help [" command ]
960 Print help for one or all commands.
961 .TP
962 .B info
963 Displays selected geometry information about the filesystem.
964 The output will have the same format that
965 .BR "mkfs.xfs" "(8)"
966 prints when creating a filesystem or
967 .BR "xfs_info" "(8)"
968 prints when querying a filesystem.
969 .TP
970 .BI "inode [" inode# ]
971 Set the current inode number. If no
972 .I inode#
973 is given, print the current inode number.
974 .TP
975 .BI "iunlink [-n " nr " ]"
976 Allocate inodes and put them on the unlinked list.
977
978 Options include:
979 .RS 1.0i
980 .TP 0.4i
981 .B \-n
982 Create this number of unlinked inodes.
983 If not specified, 1 inode will be created.
984 .RE
985 .TP
986 .BI "label [" label ]
987 Set the filesystem label. The filesystem label can be used by
988 .BR mount (8)
989 instead of using a device special file.
990 The maximum length of an XFS label is 12 characters \- use of a longer
991 .I label
992 will result in truncation and a warning will be issued. If no
993 .I label
994 is given, the current filesystem label is printed.
995 .TP
996 .BI "link [-i " ino "] [-m] [-p " path "] [-t " ftype "] name"
997 In the current directory, create a directory entry with the given
998 .I name
999 pointing to a file.
1000 The file must be specified either as a directory tree path as given by the
1001 .I path
1002 option; or directly as an inode number as given by the
1003 .I ino
1004 option.
1005 The file type in the directory entry will be determined from the mode of the
1006 child file unless the
1007 .I ftype
1008 option is given.
1009 The
1010 .B -m
1011 option specifies that the path lookup should be done in the metadata directory
1012 tree.
1013 The file being targetted must not be on the iunlink list.
1014 .TP
1015 .BI "log [stop | start " filename ]
1016 Start logging output to
1017 .IR filename ,
1018 stop logging, or print the current logging status.
1019 .TP
1020 .BI "logblock [" logbno ]
1021 Set current address to the log block value given by
1022 .IR logbno .
1023 If no value for
1024 .I logbno
1025 is given the current address is printed, expressed as an fsb.
1026 The type is set to
1027 .B data
1028 (uninterpreted).
1029 If the filesystem has an external log, then the address will be within the log
1030 device.
1031 If the filesystem has an internal log, then the address will be within the
1032 internal log.
1033 .TP
1034 .BI "logformat [\-c " cycle "] [\-s " sunit "]"
1035 Reformats the log to the specified log cycle and log stripe unit.
1036 This has the effect of clearing the log destructively.
1037 If the log cycle is not specified, the log is reformatted to the current cycle.
1038 If the log stripe unit is not specified, the stripe unit from the filesystem
1039 superblock is used.
1040 .TP
1041 .B logres
1042 Print transaction reservation size information for each transaction type.
1043 This makes it easier to find discrepancies in the reservation calculations
1044 between xfsprogs and the kernel, which will help when diagnosing minimum
1045 log size calculation errors.
1046 .TP
1047 .BI "ls [\-im] [" paths "]..."
1048 List the contents of a directory.
1049 If a path resolves to a directory, the directory will be listed.
1050 If no paths are supplied and the IO cursor points at a directory inode,
1051 the contents of that directory will be listed.
1052
1053 The output format is:
1054 directory cookie, inode number, file type, hash, name length, name.
1055 .RS 1.0i
1056 .TP 0.4i
1057 .B \-i
1058 Resolve each of the given paths to an inode number and print that number.
1059 If no paths are given and the IO cursor points to an inode, print the inode
1060 number.
1061 .TP
1062 .B \-m
1063 Absolute paths should be walked from the root of the metadata directory tree.
1064 .RE
1065 .TP
1066 .BI "metadump [\-egow] " filename
1067 Dumps metadata to a file. See
1068 .BR xfs_metadump (8)
1069 for more information.
1070 .TP
1071 .BI "ncheck [\-s] [\-i " ino "] ..."
1072 Print name-inode pairs. A
1073 .B blockget \-n
1074 command must be run first to gather the information.
1075 .RS 1.0i
1076 .TP 0.4i
1077 .B \-i
1078 specifies an inode number to be printed. If no
1079 .B \-i
1080 options are given then all inodes are printed.
1081 .TP
1082 .B \-s
1083 specifies that only setuid and setgid files are printed.
1084 .RE
1085 .TP
1086 .B p
1087 See the
1088 .B print
1089 command.
1090 .TP
1091 .BI "parent [\-m] [" paths "]..."
1092 List the parents of a file.
1093 If a path resolves to a file, the parents of that file will be listed.
1094 If no paths are supplied and the IO cursor points at an inode, the parents of
1095 that file will be listed.
1096 The
1097 .B \-m
1098 option causes absolute paths to be walked from the root of the metadata
1099 directory tree.
1100
1101 The output format is:
1102 inode number, inode generation, ondisk namehash, namehash, name length, name.
1103 .TP
1104 .BI "path [\-m] " dir_path
1105 Walk the directory tree to an inode using the supplied path.
1106 Absolute and relative paths are supported.
1107 The
1108 .B \-m
1109 option causes absolute paths to be walked from the root of the metadata
1110 directory tree.
1111 .TP
1112 .B pop
1113 Pop location from the stack.
1114 .TP
1115 .BI "print [" field-expression "] ..."
1116 Print field values.
1117 If no argument is given, print all fields in the current structure.
1118 .TP
1119 .BI "push [" command ]
1120 Push location to the stack. If
1121 .I command
1122 is supplied, set the current location to the results of
1123 .I command
1124 after pushing the old location.
1125 .TP
1126 .B q
1127 See the
1128 .B quit
1129 command.
1130 .TP
1131 .B quit
1132 Exit
1133 .BR xfs_db .
1134 .TP
1135 .BI "rdump [-s] [" "paths..." "] " "destination_dir"
1136 Recover the files given by the
1137 .B path
1138 arguments by copying them of the filesystem into the directory specified in
1139 .BR destination_dir .
1140
1141 If the
1142 .B -s
1143 option is specified, errors are fatal.
1144 By default, read errors are ignored in favor of recovering as much data from
1145 the filesystem as possible.
1146
1147 If zero
1148 .B paths
1149 are specified, the entire filesystem is dumped.
1150 If only one
1151 .B path
1152 is specified and it is a directory, the children of that directory will be
1153 copied directly to the destination.
1154 If multiple
1155 .B paths
1156 are specified, each file is copied into the directory as a new child.
1157
1158 If possible, sparse holes, xfs file attributes, and extended attributes will be
1159 preserved.
1160 .TP
1161 .BI "rgresv [" rgno ]
1162 Displays the per-rtgroup reservation size, and per-rtgroup
1163 reservation usage for a given realtime allocation group.
1164 If no argument is given, display information for all rtgroups.
1165 .TP
1166 .BI "rtblock [" rtbno ]
1167 Set current address to the location on the realtime device given by
1168 .IR rtbno .
1169 This value must be a realtime block number.
1170 If no value for
1171 .I rtbno
1172 is given the current address is printed, expressed as an rtbno.
1173 The type is set to
1174 .B data
1175 (uninterpreted).
1176 .TP
1177 .BI "rtextent [" rtxno ]
1178 Set current address to the location on the realtime device given by
1179 .IR rtextent .
1180 This value must be a linear address in units of realtime extents.
1181 If no value for
1182 .I rtextent
1183 is given the current address is printed, expressed as an rtextent.
1184 The type is set to
1185 .B data
1186 (uninterpreted).
1187 .TP
1188 .BI "ring [" index ]
1189 Show position ring (if no
1190 .I index
1191 argument is given), or move to a specific entry in the position ring given by
1192 .IR index .
1193 .TP
1194 .BI "rtconvert " "type number" " [" "type number" "] ... " type
1195 Convert from one address form to another for realtime section addresses.
1196 The known
1197 .IR type s,
1198 with alternate names, are:
1199 .RS 1.0i
1200 .PD 0
1201 .HP
1202 .B rgblock
1203 or
1204 .B rgbno
1205 (realtime block within a realtime group)
1206 .HP
1207 .B rgnumber
1208 or
1209 .B rgno
1210 (realtime group number)
1211 .HP
1212 .B bboff
1213 or
1214 .B daddroff
1215 (byte offset in a
1216 .BR daddr )
1217 .HP
1218 .B blkoff
1219 or
1220 .B fsboff or
1221 .B rtboff
1222 (byte offset in a
1223 .B rtblock
1224 or
1225 .BR rtextent )
1226 .HP
1227 .B byte
1228 or
1229 .B fsbyte
1230 (byte address in filesystem)
1231 .HP
1232 .B daddr
1233 or
1234 .B bb
1235 (disk address, 512-byte blocks)
1236 .HP
1237 .B rtblock
1238 or
1239 .B rtb
1240 or
1241 .B rtbno
1242 (realtime filesystem block, see the
1243 .B fsblock
1244 command)
1245 .HP
1246 .B rtx
1247 or
1248 .B rtextent
1249 (realtime extent)
1250 .HP
1251 .B rbmblock
1252 or
1253 .B rbmb
1254 (realtime bitmap block)
1255 .HP
1256 .B rbmword
1257 or
1258 .B rbmw
1259 (32-bit word within a realtime bitmap block)
1260 .HP
1261 .B rsumblock
1262 or
1263 .B rsmb
1264 (realtime summary file block)
1265 .HP
1266 .B rsuminfo
1267 or
1268 .B rsmi
1269 (32-bit counter within a realtime summary block)
1270 .HP
1271 .B rsumlog
1272 or
1273 .B rsml
1274 (log2len parameter used for summary file offset computations)
1275 .PD
1276 .RE
1277 .IP
1278 Only conversions that "make sense" are allowed.
1279 The compound form (with more than three arguments) is useful for
1280 conversions such as
1281 .B convert rgno
1282 .I rg
1283 .B rgbno
1284 .I rgb
1285 .BR rtblock .
1286
1287 Realtime summary file location conversions have the following rules:
1288 Each info word in the rt summary file counts the number of free extents of a
1289 given log2(length) that start in a given rt bitmap block.
1290
1291 To compute summary file location information for a given rt bitmap block, a
1292 log2(extent length) must be specified as the last type/number pair before the
1293 conversion type, and the type must be
1294 .BR rsumlog .
1295
1296 For example, these commands tell us where to look in the rt summary file for
1297 the number of free rtextents of length 2^21 starting in rt bitmap block 30:
1298
1299 .B rtconvert rbmblock 30 rsumlog 21 rsumblock
1300
1301 .B rtconvert rbmblock 30 rsumlog 21 rsuminfo
1302
1303 To compute the rt bitmap block from summary file location, the type/number
1304 pairs must be specified exactly in the order
1305 .BR rsumlog ", " rsuminfo ", " rsumblock .
1306
1307 For example, this command tells us which block in the rt bitmap file is
1308 summarized by info word 809 in rt summary block 10 assuming that the
1309 maximum free extent length is 2^21 rtextents:
1310
1311 .B rtconvert rsumlog 21 rsuminfo 809 rsumblock 10 rbmblock
1312
1313 .TP
1314 .B rtsb
1315 Set current address to the superblock header at the start of the realtime
1316 volume.
1317 .TP
1318 .BI "sb [" agno ]
1319 Set current address to SB header in allocation group
1320 .IR agno .
1321 If no
1322 .I agno
1323 is given, use the current allocation group number.
1324 .TP
1325 .BI "source " source-file
1326 Process commands from
1327 .IR source-file .
1328 .B source
1329 commands can be nested.
1330 .TP
1331 .B stack
1332 View the location stack.
1333 .TP
1334 .BI "type [" type ]
1335 Set the current data type to
1336 .IR type .
1337 If no argument is given, show the current data type.
1338 The possible data types are:
1339 .BR agf ", " agfl ", " agi ", " attr ", " bmapbta ", " bmapbtd ,
1340 .BR bnobt ", " cntbt ", " data ", " dir ", " dir2 ", " dqblk ,
1341 .BR inobt ", " inode ", " log ", " refcntbt ", " rmapbt ", " rtbitmap ,
1342 .BR rtsummary ", " sb ", " symlink ", " rtrmapbt ", " rtrefcbt ", and " text .
1343 See the TYPES section below for more information on these data types.
1344 .TP
1345 .BI "timelimit [" OPTIONS ]
1346 Print the minimum and maximum supported values for inode timestamps,
1347 quota expiration timers, and quota grace periods supported by this
1348 filesystem.
1349 Options include:
1350 .RS 1.0i
1351 .TP 0.4i
1352 .B \--bigtime
1353 Print the time limits of an XFS filesystem with the
1354 .B bigtime
1355 feature enabled.
1356 .TP 0.4i
1357 .B \--classic
1358 Print the time limits of a classic XFS filesystem.
1359 .TP 0.4i
1360 .B \--compact
1361 Print all limits as raw values on a single line.
1362 .TP 0.4i
1363 .B \--pretty
1364 Print the timestamps in the current locale's date and time format instead of
1365 raw seconds since the Unix epoch.
1366 .RE
1367 .TP
1368 .BI "unlink name"
1369 In the current directory, remove a directory entry with the given
1370 .IR name .
1371 The file being targetted will not be put on the iunlink list.
1372 .TP
1373 .BI "untorn_write_max [\-b " blockcount "|\-l " logres "]"
1374 If
1375 .B -l
1376 is specified, compute the maximum (in fsblocks) untorn write that we can
1377 emulate with copy on write given a log reservation size (in bytes).
1378 If
1379 .B -b
1380 is specified, compute the log reservation size that would be needed to
1381 emulate an untorn write of the given number of fsblocks.
1382 .TP
1383 .BI "uuid [" uuid " | " generate " | " rewrite " | " restore ]
1384 Set the filesystem universally unique identifier (UUID).
1385 The filesystem UUID can be used by
1386 .BR mount (8)
1387 instead of using a device special file.
1388 The
1389 .I uuid
1390 can be set directly to the desired UUID, or it can
1391 be automatically generated using the
1392 .B generate
1393 option. These options will both write the UUID into every copy of the
1394 superblock in the filesystem. On a CRC-enabled filesystem, this will
1395 set an incompatible superblock flag, and the filesystem will not be
1396 mountable with older kernels. This can be reverted with the
1397 .B restore
1398 option, which will copy the original UUID back into place and clear
1399 the incompatible flag as needed.
1400 .B rewrite
1401 copies the current UUID from the primary superblock
1402 to all secondary copies of the superblock.
1403 If no argument is given, the current filesystem UUID is printed.
1404 .TP
1405 .BI "version [" feature " | " "versionnum features2" ]
1406 Enable selected features for a filesystem (certain features can
1407 be enabled on an unmounted filesystem, after
1408 .BR mkfs.xfs (8)
1409 has created the filesystem).
1410 Support for unwritten extents can be enabled using the
1411 .B extflg
1412 option. Support for version 2 log format can be enabled using the
1413 .B log2
1414 option. Support for extended attributes can be enabled using the
1415 .B attr1
1416 or
1417 .B attr2
1418 option. Once enabled, extended attributes cannot be disabled, but the user
1419 may toggle between
1420 .B attr1
1421 and
1422 .B attr2
1423 at will (older kernels may not support the newer version).
1424 .IP
1425 If no argument is given, the current version and feature bits are printed.
1426 With one argument, this command will write the updated version number
1427 into every copy of the superblock in the filesystem.
1428 If two arguments are given, they will be used as numeric values for the
1429 .I versionnum
1430 and
1431 .I features2
1432 bits respectively, and their string equivalent reported
1433 (but no modifications are made).
1434 .TP
1435 .BI "write [\-c|\-d] [" "field value" "] ..."
1436 Write a value to disk.
1437 Specific fields can be set in structures (struct mode),
1438 or a block can be set to data values (data mode),
1439 or a block can be set to string values (string mode, for symlink blocks).
1440 The operation happens immediately: there is no buffering.
1441 .IP
1442 Struct mode is in effect when the current type is structural,
1443 i.e. not data. For struct mode, the syntax is "\c
1444 .B write
1445 .I field value\c
1446 ".
1447 .IP
1448 Data mode is in effect when the current type is data. In this case the
1449 contents of the block can be shifted or rotated left or right, or filled
1450 with a sequence, a constant value, or a random value. In this mode
1451 .B write
1452 with no arguments gives more information on the allowed commands.
1453 .RS 1.0i
1454 .TP 0.4i
1455 .B \-c
1456 Skip write verifiers and CRC recalculation; allows invalid data to be written
1457 to disk.
1458 .TP 0.4i
1459 .B \-d
1460 Skip write verifiers but perform CRC recalculation.
1461 This allows invalid data to be written to disk to
1462 test detection of invalid data. (This is not possible for some types.)
1463 .RE
1464 .SH TYPES
1465 This section gives the fields in each structure type and their meanings.
1466 Note that some types of block cover multiple actual structures,
1467 for instance directory blocks.
1468 .TP 1.0i
1469 .B agf
1470 The AGF block is the header for block allocation information;
1471 it is in the second 512-byte block of each allocation group.
1472 The following fields are defined:
1473 .RS 1.4i
1474 .PD 0
1475 .TP 1.2i
1476 .B magicnum
1477 AGF block magic number, 0x58414746 ('XAGF').
1478 .TP
1479 .B versionnum
1480 version number, currently 1.
1481 .TP
1482 .B seqno
1483 sequence number starting from 0.
1484 .TP
1485 .B length
1486 size in filesystem blocks of the allocation group. All allocation
1487 groups except the last one of the filesystem have the superblock's
1488 .B agblocks
1489 value here.
1490 .TP
1491 .B bnoroot
1492 block number of the root of the Btree holding free space
1493 information sorted by block number.
1494 .TP
1495 .B cntroot
1496 block number of the root of the Btree holding free space
1497 information sorted by block count.
1498 .TP
1499 .B bnolevel
1500 number of levels in the by-block-number Btree.
1501 .TP
1502 .B cntlevel
1503 number of levels in the by-block-count Btree.
1504 .TP
1505 .B flfirst
1506 index into the AGFL block of the first active entry.
1507 .TP
1508 .B fllast
1509 index into the AGFL block of the last active entry.
1510 .TP
1511 .B flcount
1512 count of active entries in the AGFL block.
1513 .TP
1514 .B freeblks
1515 count of blocks represented in the freespace Btrees.
1516 .TP
1517 .B longest
1518 longest free space represented in the freespace Btrees.
1519 .TP
1520 .B btreeblks
1521 number of blocks held in the AGF Btrees.
1522 .PD
1523 .RE
1524 .TP
1525 .B agfl
1526 The AGFL block contains block numbers for use of the block allocator;
1527 it is in the fourth 512-byte block of each allocation group.
1528 Each entry in the active list is a block number within the allocation group
1529 that can be used for any purpose if space runs low.
1530 The AGF block fields
1531 .BR flfirst ", " fllast ", and " flcount
1532 designate which entries are currently active.
1533 Entry space is allocated in a circular manner within the AGFL block.
1534 Fields defined:
1535 .RS 1.4i
1536 .PD 0
1537 .TP 1.2i
1538 .B bno
1539 array of all block numbers. Even those which are not active are printed.
1540 .PD
1541 .RE
1542 .TP
1543 .B agi
1544 The AGI block is the header for inode allocation information;
1545 it is in the third 512-byte block of each allocation group.
1546 Fields defined:
1547 .RS 1.4i
1548 .PD 0
1549 .TP 1.2i
1550 .B magicnum
1551 AGI block magic number, 0x58414749 ('XAGI').
1552 .TP
1553 .B versionnum
1554 version number, currently 1.
1555 .TP
1556 .B seqno
1557 sequence number starting from 0.
1558 .TP
1559 .B length
1560 size in filesystem blocks of the allocation group.
1561 .TP
1562 .B count
1563 count of inodes allocated.
1564 .TP
1565 .B root
1566 block number of the root of the Btree holding inode allocation information.
1567 .TP
1568 .B level
1569 number of levels in the inode allocation Btree.
1570 .TP
1571 .B freecount
1572 count of allocated inodes that are not in use.
1573 .TP
1574 .B newino
1575 last inode number allocated.
1576 .TP
1577 .B dirino
1578 unused.
1579 .TP
1580 .B unlinked
1581 an array of inode numbers within the allocation group. The entries
1582 in the AGI block are the heads of lists which run through the inode
1583 .B next_unlinked
1584 field. These inodes are to be unlinked the next time the filesystem is mounted.
1585 .PD
1586 .RE
1587 .TP
1588 .B attr
1589 An attribute fork is organized as a Btree with the actual data embedded
1590 in the leaf blocks. The root of the Btree is found in block 0 of the fork.
1591 The index (sort order) of the Btree is the hash value of the attribute name.
1592 All the blocks contain a
1593 .B blkinfo
1594 structure at the beginning, see type
1595 .B dir
1596 for a description. Nonleaf blocks are identical in format to those for
1597 version 1 and version 2 directories, see type
1598 .B dir
1599 for a description. Leaf blocks can refer to "local" or "remote" attribute
1600 values. Local values are stored directly in the leaf block.
1601 Leaf blocks contain the following fields:
1602 .RS 1.4i
1603 .PD 0
1604 .TP 1.2i
1605 .B hdr
1606 header containing a
1607 .B blkinfo
1608 structure
1609 .B info
1610 (magic number 0xfbee), a
1611 .B count
1612 of active entries,
1613 .B usedbytes
1614 total bytes of names and values, the
1615 .B firstused
1616 byte in the name area,
1617 .B holes
1618 set if the block needs compaction, and array
1619 .B freemap
1620 as for
1621 .B dir
1622 leaf blocks.
1623 .TP
1624 .B entries
1625 array of structures containing a
1626 .BR hashval ,
1627 .B nameidx
1628 (index into the block of the name), and flags
1629 .BR incomplete ,
1630 .BR root ,
1631 and
1632 .BR local .
1633 .TP
1634 .B nvlist
1635 array of structures describing the attribute names and values. Fields
1636 always present:
1637 .B valuelen
1638 (length of value in bytes),
1639 .BR namelen ,
1640 and
1641 .BR name .
1642 Fields present for local values:
1643 .B value
1644 (value string). Fields present for remote values:
1645 .B valueblk
1646 (fork block number of containing the value).
1647 .PD
1648 .RE
1649 .IP
1650 Remote values are stored in an independent block in the attribute fork.
1651 Prior to v5, value blocks had no structure, but in v5 they acquired a header
1652 structure with the following fields:
1653 .RS 1.4i
1654 .PD 0
1655 .TP 1.2i
1656 .B magic
1657 attr3 remote block magic number, 0x5841524d ('XARM').
1658 .TP
1659 .B offset
1660 Byte offset of this data block within the overall attribute value.
1661 .TP
1662 .B bytes
1663 Number of bytes stored in this block.
1664 .TP
1665 .B crc
1666 Checksum of the attribute block contents.
1667 .TP
1668 .B uuid
1669 Filesystem UUID.
1670 .TP
1671 .B owner
1672 Inode that owns this attribute value.
1673 .TP
1674 .B bno
1675 Block offset of this block within the inode's attribute fork.
1676 .TP
1677 .B lsn
1678 Log serial number of the last time this block was logged.
1679 .TP
1680 .B data
1681 The attribute value data.
1682 .PD
1683 .RE
1684 .TP
1685 .B bmapbt
1686 Files with many extents in their data or attribute fork will have the
1687 extents described by the contents of a Btree for that fork,
1688 instead of being stored directly in the inode.
1689 Each bmap Btree starts with a root block contained within the inode.
1690 The other levels of the Btree are stored in filesystem blocks.
1691 The blocks are linked to sibling left and right blocks at each level,
1692 as well as by pointers from parent to child blocks.
1693 Each block contains the following fields:
1694 .RS 1.4i
1695 .PD 0
1696 .TP 1.2i
1697 .B magic
1698 bmap Btree block magic number, 0x424d4150 ('BMAP').
1699 .TP
1700 .B level
1701 level of this block above the leaf level.
1702 .TP
1703 .B numrecs
1704 number of records or keys in the block.
1705 .TP
1706 .B leftsib
1707 left (logically lower) sibling block, 0 if none.
1708 .TP
1709 .B rightsib
1710 right (logically higher) sibling block, 0 if none.
1711 .TP
1712 .B recs
1713 [leaf blocks only] array of extent records.
1714 Each record contains
1715 .BR startoff ,
1716 .BR startblock ,
1717 .BR blockcount ,
1718 and
1719 .B extentflag
1720 (1 if the extent is unwritten).
1721 .TP
1722 .B keys
1723 [non-leaf blocks only] array of key records. These are the first key
1724 value of each block in the level below this one. Each record contains
1725 .BR startoff .
1726 .TP
1727 .B ptrs
1728 [non-leaf blocks only] array of child block pointers.
1729 Each pointer is a filesystem block number to the next level in the Btree.
1730 .PD
1731 .RE
1732 .TP
1733 .B bnobt
1734 There is one set of filesystem blocks forming the by-block-number
1735 allocation Btree for each allocation group. The root block of this
1736 Btree is designated by the
1737 .B bnoroot
1738 field in the corresponding AGF block.
1739 The blocks are linked to sibling left and right blocks at each level,
1740 as well as by pointers from parent to child blocks.
1741 Each block has the following fields:
1742 .RS 1.4i
1743 .PD 0
1744 .TP 1.2i
1745 .B magic
1746 BNOBT block magic number, 0x41425442 ('ABTB').
1747 .TP
1748 .B level
1749 level number of this block, 0 is a leaf.
1750 .TP
1751 .B numrecs
1752 number of data entries in the block.
1753 .TP
1754 .B leftsib
1755 left (logically lower) sibling block, 0 if none.
1756 .TP
1757 .B rightsib
1758 right (logically higher) sibling block, 0 if none.
1759 .TP
1760 .B recs
1761 [leaf blocks only] array of freespace records. Each record contains
1762 .B startblock
1763 and
1764 .BR blockcount .
1765 .TP
1766 .B keys
1767 [non-leaf blocks only] array of key records. These are the first value
1768 of each block in the level below this one. Each record contains
1769 .B startblock
1770 and
1771 .BR blockcount .
1772 .TP
1773 .B ptrs
1774 [non-leaf blocks only] array of child block pointers. Each pointer is a
1775 block number within the allocation group to the next level in the Btree.
1776 .PD
1777 .RE
1778 .TP
1779 .B cntbt
1780 There is one set of filesystem blocks forming the by-block-count
1781 allocation Btree for each allocation group. The root block of this
1782 Btree is designated by the
1783 .B cntroot
1784 field in the corresponding AGF block. The blocks are linked to sibling
1785 left and right blocks at each level, as well as by pointers from parent
1786 to child blocks. Each block has the following fields:
1787 .RS 1.4i
1788 .PD 0
1789 .TP 1.2i
1790 .B magic
1791 CNTBT block magic number, 0x41425443 ('ABTC').
1792 .TP
1793 .B level
1794 level number of this block, 0 is a leaf.
1795 .TP
1796 .B numrecs
1797 number of data entries in the block.
1798 .TP
1799 .B leftsib
1800 left (logically lower) sibling block, 0 if none.
1801 .TP
1802 .B rightsib
1803 right (logically higher) sibling block, 0 if none.
1804 .TP
1805 .B recs
1806 [leaf blocks only] array of freespace records. Each record contains
1807 .B startblock
1808 and
1809 .BR blockcount .
1810 .TP
1811 .B keys
1812 [non-leaf blocks only] array of key records. These are the first value
1813 of each block in the level below this one. Each record contains
1814 .B blockcount
1815 and
1816 .BR startblock .
1817 .TP
1818 .B ptrs
1819 [non-leaf blocks only] array of child block pointers. Each pointer is a
1820 block number within the allocation group to the next level in the Btree.
1821 .PD
1822 .RE
1823 .TP
1824 .B data
1825 User file blocks, and other blocks whose type is unknown, have this
1826 type for display purposes in
1827 .BR xfs_db .
1828 The block data is displayed in hexadecimal format.
1829 .TP
1830 .B dir
1831 A version 1 directory is organized as a Btree with the directory data
1832 embedded in the leaf blocks. The root of the Btree is found in block 0
1833 of the file. The index (sort order) of the Btree is the hash value of
1834 the entry name. All the blocks contain a
1835 .B blkinfo
1836 structure at the beginning with the following fields:
1837 .RS 1.4i
1838 .PD 0
1839 .TP 1.2i
1840 .B forw
1841 next sibling block.
1842 .TP
1843 .B back
1844 previous sibling block.
1845 .TP
1846 .B magic
1847 magic number for this block type.
1848 .RE
1849 .IP
1850
1851 The non-leaf (node) blocks have the following fields:
1852 .RS 1.4i
1853 .TP 1.2i
1854 .B hdr
1855 header containing a
1856 .B blkinfo
1857 structure
1858 .B info
1859 (magic number 0xfebe), the
1860 .B count
1861 of active entries, and the
1862 .B level
1863 of this block above the leaves.
1864 .TP
1865 .B btree
1866 array of entries containing
1867 .B hashval
1868 and
1869 .B before
1870 fields. The
1871 .B before
1872 value is a block number within the directory file to the child block, the
1873 .B hashval
1874 is the last hash value in that block.
1875 .RE
1876 .IP
1877
1878 The leaf blocks have the following fields:
1879 .RS 1.4i
1880 .TP 1.2i
1881 .B hdr
1882 header containing a
1883 .B blkinfo
1884 structure
1885 .B info
1886 (magic number 0xfeeb), the
1887 .B count
1888 of active entries,
1889 .B namebytes
1890 (total name string bytes),
1891 .B holes
1892 flag (block needs compaction), and
1893 .B freemap
1894 (array of
1895 .BR base ", " size
1896 entries for free regions).
1897 .TP
1898 .B entries
1899 array of structures containing
1900 .BR hashval ,
1901 .B nameidx
1902 (byte index into the block of the name string), and
1903 .BR namelen .
1904 .TP
1905 .B namelist
1906 array of structures containing
1907 .B inumber
1908 and
1909 .BR name .
1910 .RE
1911 .PD
1912 .TP
1913 .B dir2
1914 A version 2 directory has four kinds of blocks.
1915 Data blocks start at offset 0 in the file.
1916 There are two kinds of data blocks: single-block directories have
1917 the leaf information embedded at the end of the block, data blocks
1918 in multi-block directories do not.
1919 Node and leaf blocks start at offset 32GiB (with either a single
1920 leaf block or the root node block).
1921 Freespace blocks start at offset 64GiB.
1922 The node and leaf blocks form a Btree, with references to the data
1923 in the data blocks.
1924 The freespace blocks form an index of longest free spaces within the
1925 data blocks.
1926 .IP
1927 A single-block directory block contains the following fields:
1928 .RS 1.4i
1929 .PD 0
1930 .TP 1.2i
1931 .B bhdr
1932 header containing
1933 .B magic
1934 number 0x58443242 ('XD2B') and an array
1935 .B bestfree
1936 of the longest 3 free spaces in the block
1937 .RB ( offset ", " length ).
1938 .TP
1939 .B bu
1940 array of union structures. Each element is either an entry or a freespace.
1941 For entries, there are the following fields:
1942 .BR inumber ,
1943 .BR namelen ,
1944 .BR name ,
1945 and
1946 .BR tag .
1947 For freespace, there are the following fields:
1948 .B freetag
1949 (0xffff),
1950 .BR length ,
1951 and
1952 .BR tag .
1953 The
1954 .B tag
1955 value is the byte offset in the block of the start of the entry it
1956 is contained in.
1957 .TP
1958 .B bleaf
1959 array of leaf entries containing
1960 .B hashval
1961 and
1962 .BR address .
1963 The
1964 .B address
1965 is a 64-bit word offset into the file.
1966 .TP
1967 .B btail
1968 tail structure containing the total
1969 .B count
1970 of leaf entries and
1971 .B stale
1972 count of unused leaf entries.
1973 .RE
1974 .IP
1975
1976 A data block contains the following fields:
1977 .RS 1.4i
1978 .TP 1.2i
1979 .B dhdr
1980 header containing
1981 .B magic
1982 number 0x58443244 ('XD2D') and an array
1983 .B bestfree
1984 of the longest 3 free spaces in the block
1985 .RB ( offset ", " length ).
1986 .TP
1987 .B du
1988 array of union structures as for
1989 .BR bu .
1990 .RE
1991 .IP
1992
1993 Leaf blocks have two possible forms. If the Btree consists of a single
1994 leaf then the freespace information is in the leaf block,
1995 otherwise it is in separate blocks and the root of the Btree is
1996 a node block. A leaf block contains the following fields:
1997 .RS 1.4i
1998 .TP 1.2i
1999 .B lhdr
2000 header containing a
2001 .B blkinfo
2002 structure
2003 .B info
2004 (magic number 0xd2f1 for the single leaf case, 0xd2ff for the true
2005 Btree case), the total
2006 .B count
2007 of leaf entries, and
2008 .B stale
2009 count of unused leaf entries.
2010 .TP
2011 .B lents
2012 leaf entries, as for
2013 .BR bleaf .
2014 .TP
2015 .B lbests
2016 [single leaf only] array of values which represent the longest freespace
2017 in each data block in the directory.
2018 .TP
2019 .B ltail
2020 [single leaf only] tail structure containing
2021 .B bestcount
2022 count of
2023 .BR lbests .
2024 .RE
2025 .IP
2026
2027 A node block is identical to that for types
2028 .B attr
2029 and
2030 .BR dir .
2031
2032 A freespace block contains the following fields:
2033 .RS 1.4i
2034 .TP 1.2i
2035 .B fhdr
2036 header containing
2037 .B magic
2038 number 0x58443246 ('XD2F'),
2039 .B firstdb
2040 first data block number covered by this freespace block,
2041 .B nvalid
2042 number of valid entries, and
2043 .B nused
2044 number of entries representing real data blocks.
2045 .TP
2046 .B fbests
2047 array of values as for
2048 .BR lbests .
2049 .PD
2050 .RE
2051 .TP
2052 .B dqblk
2053 The quota information is stored in files referred to by the superblock
2054 .B uquotino
2055 and
2056 .B pquotino
2057 fields. Each filesystem block in a quota file contains a constant number of
2058 quota entries. The quota entry size is currently 136 bytes, so with a 4KiB
2059 filesystem block size there are 30 quota entries per block. The
2060 .B dquot
2061 command is used to locate these entries in the filesystem.
2062 The file entries are indexed by the user or project identifier
2063 to determine the block and offset.
2064 Each quota entry has the following fields:
2065 .RS 1.4i
2066 .PD 0
2067 .TP 1.5i
2068 .B magic
2069 magic number, 0x4451 ('DQ').
2070 .TP
2071 .B version
2072 version number, currently 1.
2073 .TP
2074 .B flags
2075 flags, values include 0x01 for user quota, 0x02 for project quota.
2076 .TP
2077 .B id
2078 user or project identifier.
2079 .TP
2080 .B blk_hardlimit
2081 absolute limit on blocks in use.
2082 .TP
2083 .B blk_softlimit
2084 preferred limit on blocks in use.
2085 .TP
2086 .B ino_hardlimit
2087 absolute limit on inodes in use.
2088 .TP
2089 .B ino_softlimit
2090 preferred limit on inodes in use.
2091 .TP
2092 .B bcount
2093 blocks actually in use.
2094 .TP
2095 .B icount
2096 inodes actually in use.
2097 .TP
2098 .B itimer
2099 time when service will be refused if soft limit is violated for inodes.
2100 .TP
2101 .B btimer
2102 time when service will be refused if soft limit is violated for blocks.
2103 .TP
2104 .B iwarns
2105 number of warnings issued about inode limit violations.
2106 .TP
2107 .B bwarns
2108 number of warnings issued about block limit violations.
2109 .TP
2110 .B rtb_hardlimit
2111 absolute limit on realtime blocks in use.
2112 .TP
2113 .B rtb_softlimit
2114 preferred limit on realtime blocks in use.
2115 .TP
2116 .B rtbcount
2117 realtime blocks actually in use.
2118 .TP
2119 .B rtbtimer
2120 time when service will be refused if soft limit is violated for realtime blocks.
2121 .TP
2122 .B rtbwarns
2123 number of warnings issued about realtime block limit violations.
2124 .PD
2125 .RE
2126 .TP
2127 .B inobt
2128 There is one set of filesystem blocks forming the inode allocation Btree for
2129 each allocation group. The root block of this Btree is designated by the
2130 .B root
2131 field in the corresponding AGI block.
2132 The blocks are linked to sibling left and right blocks at each level,
2133 as well as by pointers from parent to child blocks.
2134 Each block has the following fields:
2135 .RS 1.4i
2136 .PD 0
2137 .TP 1.2i
2138 .B magic
2139 INOBT block magic number, 0x49414254 ('IABT').
2140 .TP
2141 .B level
2142 level number of this block, 0 is a leaf.
2143 .TP
2144 .B numrecs
2145 number of data entries in the block.
2146 .TP
2147 .B leftsib
2148 left (logically lower) sibling block, 0 if none.
2149 .TP
2150 .B rightsib
2151 right (logically higher) sibling block, 0 if none.
2152 .TP
2153 .B recs
2154 [leaf blocks only] array of inode records. Each record contains
2155 .B startino
2156 allocation-group relative inode number,
2157 .B freecount
2158 count of free inodes in this chunk, and
2159 .B free
2160 bitmap, LSB corresponds to inode 0.
2161 .TP
2162 .B keys
2163 [non-leaf blocks only] array of key records. These are the first value of each
2164 block in the level below this one. Each record contains
2165 .BR startino .
2166 .TP
2167 .B ptrs
2168 [non-leaf blocks only] array of child block pointers. Each pointer is a
2169 block number within the allocation group to the next level in the Btree.
2170 .PD
2171 .RE
2172 .TP
2173 .B inode
2174 Inodes are allocated in "chunks" of 64 inodes each. Usually a chunk is
2175 multiple filesystem blocks, although there are cases with large filesystem
2176 blocks where a chunk is less than one block. The inode Btree (see
2177 .B inobt
2178 above) refers to the inode numbers per allocation group. The inode numbers
2179 directly reflect the location of the inode block on disk. Use the
2180 .B inode
2181 command to point
2182 .B xfs_db
2183 to a specific inode. Each inode contains four regions:
2184 .BR core ,
2185 .BR next_unlinked ,
2186 .BR u ", and "
2187 .BR a .
2188 .B core
2189 contains the fixed information.
2190 .B next_unlinked
2191 is separated from the core due to journaling considerations, see type
2192 .B agi
2193 field
2194 .BR unlinked .
2195 .B u
2196 is a union structure that is different in size and format depending
2197 on the type and representation of the file data ("data fork").
2198 .B a
2199 is an optional union structure to describe attribute data,
2200 that is different in size, format, and location depending on the presence
2201 and representation of attribute data, and the size of the
2202 .B u
2203 data ("attribute fork").
2204 .B xfs_db
2205 automatically selects the proper union members based on information
2206 in the inode.
2207 .IP
2208 The following are fields in the inode core:
2209 .RS 1.4i
2210 .PD 0
2211 .TP 1.2i
2212 .B magic
2213 inode magic number, 0x494e ('IN').
2214 .TP
2215 .B mode
2216 mode and type of file, as described in
2217 .BR chmod (2),
2218 .BR mknod (2),
2219 and
2220 .BR stat (2).
2221 .TP
2222 .B version
2223 inode version, 1 or 2.
2224 .TP
2225 .B format
2226 format of
2227 .B u
2228 union data (0: xfs_dev_t, 1: local file \- in-inode directory or symlink,
2229 2: extent list, 3: Btree root, 4: unique id [unused]).
2230 .TP
2231 .B nlinkv1
2232 number of links to the file in a version 1 inode.
2233 .TP
2234 .B nlinkv2
2235 number of links to the file in a version 2 inode.
2236 .TP
2237 .B projid_lo
2238 owner's project id (low word; version 2 inode only).
2239 .B projid_hi
2240 owner's project id (high word; version 2 inode only).
2241 .TP
2242 .B uid
2243 owner's user id.
2244 .TP
2245 .B gid
2246 owner's group id.
2247 .TP
2248 .B atime
2249 time last accessed (seconds and nanoseconds).
2250 .TP
2251 .B mtime
2252 time last modified.
2253 .TP
2254 .B ctime
2255 time created or inode last modified.
2256 .TP
2257 .B size
2258 number of bytes in the file.
2259 .TP
2260 .B nblocks
2261 total number of blocks in the file including indirect and attribute.
2262 .TP
2263 .B extsize
2264 basic/minimum extent size for the file.
2265 .TP
2266 .B nextents
2267 number of extents in the data fork.
2268 .TP
2269 .B naextents
2270 number of extents in the attribute fork.
2271 .TP
2272 .B forkoff
2273 attribute fork offset in the inode, in 64-bit words from the start of
2274 .BR u .
2275 .TP
2276 .B aformat
2277 format of
2278 .B a
2279 data (1: local attribute data, 2: extent list, 3: Btree root).
2280 .TP
2281 .B dmevmask
2282 DMAPI event mask.
2283 .TP
2284 .B dmstate
2285 DMAPI state information.
2286 .TP
2287 .B newrtbm
2288 file is the realtime bitmap and is "new" format.
2289 .TP
2290 .B prealloc
2291 file has preallocated data space after EOF.
2292 .TP
2293 .B realtime
2294 file data is in the realtime subvolume.
2295 .TP
2296 .B gen
2297 inode generation number.
2298 .RE
2299 .IP
2300
2301 The following fields are in the
2302 .B u
2303 data fork union:
2304 .RS 1.4i
2305 .TP 1.2i
2306 .B bmbt
2307 bmap Btree root. This looks like a
2308 .B bmapbtd
2309 block with redundant information removed.
2310 .TP
2311 .B bmx
2312 array of extent descriptors.
2313 .TP
2314 .B dev
2315 dev_t for the block or character device.
2316 .TP
2317 .B sfdir
2318 shortform (in-inode) version 1 directory. This consists of a
2319 .B hdr
2320 containing the
2321 .B parent
2322 inode number and a
2323 .B count
2324 of active entries in the directory, followed by an array
2325 .B list
2326 of
2327 .B hdr.count
2328 entries. Each such entry contains
2329 .BR inumber ,
2330 .BR namelen ,
2331 and
2332 .B name
2333 string.
2334 .TP
2335 .B sfdir2
2336 shortform (in-inode) version 2 directory. This consists of a
2337 .B hdr
2338 containing a
2339 .B count
2340 of active entries in the directory, an
2341 .B i8count
2342 of entries with inumbers that don't fit in a 32-bit value, and the
2343 .B parent
2344 inode number, followed by an array
2345 .B list
2346 of
2347 .B hdr.count
2348 entries. Each such entry contains
2349 .BR namelen ,
2350 a saved
2351 .B offset
2352 used when the directory is converted to a larger form, a
2353 .B name
2354 string, and the
2355 .BR inumber .
2356 .TP
2357 .B symlink
2358 symbolic link string value.
2359 .RE
2360 .IP
2361
2362 The following fields are in the
2363 .B a
2364 attribute fork union if it exists:
2365 .RS 1.4i
2366 .TP 1.2i
2367 .B bmbt
2368 bmap Btree root, as above.
2369 .TP
2370 .B bmx
2371 array of extent descriptors.
2372 .TP
2373 .B sfattr
2374 shortform (in-inode) attribute values. This consists of a
2375 .B hdr
2376 containing a
2377 .B totsize
2378 (total size in bytes) and a
2379 .B count
2380 of active entries, followed by an array
2381 .B list
2382 of
2383 .B hdr.count
2384 entries. Each such entry contains
2385 .BR namelen ,
2386 .BR valuelen ,
2387 .BR root
2388 flag,
2389 .BR name ,
2390 and
2391 .BR value .
2392 .PD
2393 .RE
2394 .TP
2395 .B log
2396 Log blocks contain the journal entries for XFS.
2397 It's not useful to examine these with
2398 .BR xfs_db ,
2399 use
2400 .BR xfs_logprint (8)
2401 instead.
2402 .TP
2403 .B refcntbt
2404 There is one set of filesystem blocks forming the reference count Btree for
2405 each allocation group. The root block of this Btree is designated by the
2406 .B refcntroot
2407 field in the corresponding AGF block. The blocks are linked to sibling left
2408 and right blocks at each level, as well as by pointers from parent to child
2409 blocks. Each block has the following fields:
2410 .RS 1.4i
2411 .PD 0
2412 .TP 1.2i
2413 .B magic
2414 REFC block magic number, 0x52334643 ('R3FC').
2415 .TP
2416 .B level
2417 level number of this block, 0 is a leaf.
2418 .TP
2419 .B numrecs
2420 number of data entries in the block.
2421 .TP
2422 .B leftsib
2423 left (logically lower) sibling block, 0 if none.
2424 .TP
2425 .B rightsib
2426 right (logically higher) sibling block, 0 if none.
2427 .TP
2428 .B recs
2429 [leaf blocks only] array of reference count records. Each record contains
2430 .BR startblock ,
2431 .BR blockcount ,
2432 and
2433 .BR refcount .
2434 .TP
2435 .B keys
2436 [non-leaf blocks only] array of key records. These are the first value
2437 of each block in the level below this one. Each record contains
2438 .BR startblock .
2439 .TP
2440 .B ptrs
2441 [non-leaf blocks only] array of child block pointers. Each pointer is a
2442 block number within the allocation group to the next level in the Btree.
2443 .PD
2444 .RE
2445 .TP
2446 .B rtrefcbt
2447 There is one reference count Btree for the entire realtime device. The
2448 .BR startblock " and "
2449 .B blockcount
2450 fields are 32 bits wide and record block counts within a realtime group.
2451 The root of this Btree is the realtime refcount inode, which is recorded in the
2452 metadata directory.
2453 Blocks are linked to sibling left and right blocks at each level, as well as by
2454 pointers from parent to child blocks.
2455 Each block has the following fields:
2456 .RS 1.4i
2457 .PD 0
2458 .TP 1.2i
2459 .B magic
2460 RTREFC block magic number, 0x52434e54 ('RCNT').
2461 .TP
2462 .B level
2463 level number of this block, 0 is a leaf.
2464 .TP
2465 .B numrecs
2466 number of data entries in the block.
2467 .TP
2468 .B leftsib
2469 left (logically lower) sibling block, 0 if none.
2470 .TP
2471 .B rightsib
2472 right (logically higher) sibling block, 0 if none.
2473 .TP
2474 .B recs
2475 [leaf blocks only] array of reference count records. Each record contains
2476 .BR startblock ,
2477 .BR blockcount ,
2478 and
2479 .BR refcount .
2480 .TP
2481 .B keys
2482 [non-leaf blocks only] array of key records. These are the first value
2483 of each block in the level below this one. Each record contains
2484 .BR startblock .
2485 .TP
2486 .B ptrs
2487 [non-leaf blocks only] array of child block pointers. Each pointer is a
2488 block number within the allocation group to the next level in the Btree.
2489 .PD
2490 .RE
2491 .TP
2492 .B rmapbt
2493 There is one set of filesystem blocks forming the reverse mapping Btree for
2494 each allocation group. The root block of this Btree is designated by the
2495 .B rmaproot
2496 field in the corresponding AGF block. The blocks are linked to sibling left
2497 and right blocks at each level, as well as by pointers from parent to child
2498 blocks. Each block has the following fields:
2499 .RS 1.4i
2500 .PD 0
2501 .TP 1.2i
2502 .B magic
2503 RMAP block magic number, 0x524d4233 ('RMB3').
2504 .TP
2505 .B level
2506 level number of this block, 0 is a leaf.
2507 .TP
2508 .B numrecs
2509 number of data entries in the block.
2510 .TP
2511 .B leftsib
2512 left (logically lower) sibling block, 0 if none.
2513 .TP
2514 .B rightsib
2515 right (logically higher) sibling block, 0 if none.
2516 .TP
2517 .B recs
2518 [leaf blocks only] array of reference count records. Each record contains
2519 .BR startblock ,
2520 .BR blockcount ,
2521 .BR owner ,
2522 .BR offset ,
2523 .BR attr_fork ,
2524 .BR bmbt_block ,
2525 and
2526 .BR unwritten .
2527 .TP
2528 .B keys
2529 [non-leaf blocks only] array of double-key records. The first ("low") key
2530 contains the first value of each block in the level below this one. The second
2531 ("high") key contains the largest key that can be used to identify any record
2532 in the subtree. Each record contains
2533 .BR startblock ,
2534 .BR owner ,
2535 .BR offset ,
2536 .BR attr_fork ,
2537 and
2538 .BR bmbt_block .
2539 .TP
2540 .B ptrs
2541 [non-leaf blocks only] array of child block pointers. Each pointer is a
2542 block number within the allocation group to the next level in the Btree.
2543 .PD
2544 .RE
2545 .TP
2546 .B rtrmapbt
2547 There is one reverse mapping Btree for each realtime group.
2548 The
2549 .BR startblock " and "
2550 .B blockcount
2551 fields are 32 bits wide and record blocks within a realtime group.
2552 The root of this Btree is the reverse-mapping inode, which is recorded in the
2553 metadata directory.
2554 Blocks are linked to sibling left and right blocks at each level, as well as by
2555 pointers from parent to child blocks.
2556 Each block has the following fields:
2557 .RS 1.4i
2558 .PD 0
2559 .TP 1.2i
2560 .B magic
2561 RTRMAP block magic number, 0x4d415052 ('MAPR').
2562 .TP
2563 .B level
2564 level number of this block, 0 is a leaf.
2565 .TP
2566 .B numrecs
2567 number of data entries in the block.
2568 .TP
2569 .B leftsib
2570 left (logically lower) sibling block, 0 if none.
2571 .TP
2572 .B rightsib
2573 right (logically higher) sibling block, 0 if none.
2574 .TP
2575 .B recs
2576 [leaf blocks only] array of reference count records. Each record contains
2577 .BR startblock ,
2578 .BR blockcount ,
2579 .BR owner ,
2580 .BR offset ,
2581 .BR attr_fork ,
2582 .BR bmbt_block ,
2583 and
2584 .BR unwritten .
2585 .TP
2586 .B keys
2587 [non-leaf blocks only] array of double-key records. The first ("low") key
2588 contains the first value of each block in the level below this one. The second
2589 ("high") key contains the largest key that can be used to identify any record
2590 in the subtree. Each record contains
2591 .BR startblock ,
2592 .BR owner ,
2593 .BR offset ,
2594 .BR attr_fork ,
2595 and
2596 .BR bmbt_block .
2597 .TP
2598 .B ptrs
2599 [non-leaf blocks only] array of child block pointers. Each pointer is a
2600 block number within the allocation group to the next level in the Btree.
2601 .PD
2602 .RE
2603 .TP
2604 .B rtbitmap
2605 If the filesystem has a realtime subvolume, then the
2606 .B rbmino
2607 field in the superblock refers to a file that contains the realtime bitmap.
2608 Each bit in the bitmap file controls the allocation of a single realtime extent
2609 (set == free). The bitmap is processed in 32-bit words, the LSB of a word is
2610 used for the first extent controlled by that bitmap word. The
2611 .B atime
2612 field of the realtime bitmap inode contains a counter
2613 that is used to control where the next new realtime file will start.
2614 .TP
2615 .B rtsummary
2616 If the filesystem has a realtime subvolume, then the
2617 .B rsumino
2618 field in the superblock refers to a file that contains the realtime summary
2619 data. The summary file contains a two-dimensional array of 16-bit values.
2620 Each value counts the number of free extent runs
2621 (consecutive free realtime extents)
2622 of a given range of sizes that starts in a given bitmap block.
2623 The size ranges are binary buckets (low size in the bucket is a power of 2).
2624 There are as many size ranges as are necessary given the size of the
2625 realtime subvolume.
2626 The first dimension is the size range,
2627 the second dimension is the starting bitmap block number
2628 (adjacent entries are for the same size, adjacent bitmap blocks).
2629 .TP
2630 .B sb
2631 There is one sb (superblock) structure per allocation group.
2632 It is the first disk block in the allocation group.
2633 Only the first one (block 0 of the filesystem) is actually used;
2634 the other blocks are redundant information for
2635 .BR xfs_repair (8)
2636 to use if the first superblock is damaged. Fields defined:
2637 .RS 1.4i
2638 .PD 0
2639 .TP 1.2i
2640 .B magicnum
2641 superblock magic number, 0x58465342 ('XFSB').
2642 .TP
2643 .B blocksize
2644 filesystem block size in bytes.
2645 .TP
2646 .B dblocks
2647 number of filesystem blocks present in the data subvolume.
2648 .TP
2649 .B rblocks
2650 number of filesystem blocks present in the realtime subvolume.
2651 .TP
2652 .B rextents
2653 number of realtime extents that
2654 .B rblocks
2655 contain.
2656 .TP
2657 .B uuid
2658 unique identifier of the filesystem.
2659 .TP
2660 .B logstart
2661 starting filesystem block number of the log (journal).
2662 If this value is 0 the log is "external".
2663 .TP
2664 .B rootino
2665 root inode number.
2666 .TP
2667 .B rbmino
2668 realtime bitmap inode number.
2669 .TP
2670 .B rsumino
2671 realtime summary data inode number.
2672 .TP
2673 .B rextsize
2674 realtime extent size in filesystem blocks.
2675 .TP
2676 .B agblocks
2677 size of an allocation group in filesystem blocks.
2678 .TP
2679 .B agcount
2680 number of allocation groups.
2681 .TP
2682 .B rbmblocks
2683 number of realtime bitmap blocks.
2684 .TP
2685 .B logblocks
2686 number of log blocks (filesystem blocks).
2687 .TP
2688 .B versionnum
2689 filesystem version information.
2690 This value is currently 1, 2, 3, or 4 in the low 4 bits.
2691 If the low bits are 4 then the other bits have additional meanings.
2692 1 is the original value.
2693 2 means that attributes were used.
2694 3 means that version 2 inodes (large link counts) were used.
2695 4 is the bitmask version of the version number.
2696 In this case, the other bits are used as flags
2697 (0x0010: attributes were used,
2698 0x0020: version 2 inodes were used,
2699 0x0040: quotas were used,
2700 0x0080: inode cluster alignment is in force,
2701 0x0100: data stripe alignment is in force,
2702 0x0200: the
2703 .B shared_vn
2704 field is used,
2705 0x1000: unwritten extent tracking is on,
2706 0x2000: version 2 directories are in use).
2707 .TP
2708 .B sectsize
2709 sector size in bytes, currently always 512.
2710 This is the size of the superblock and the other header blocks.
2711 .TP
2712 .B inodesize
2713 inode size in bytes.
2714 .TP
2715 .B inopblock
2716 number of inodes per filesystem block.
2717 .TP
2718 .B fname
2719 obsolete, filesystem name.
2720 .TP
2721 .B fpack
2722 obsolete, filesystem pack name.
2723 .TP
2724 .B blocklog
2725 log2 of
2726 .BR blocksize .
2727 .TP
2728 .B sectlog
2729 log2 of
2730 .BR sectsize .
2731 .TP
2732 .B inodelog
2733 log2 of
2734 .BR inodesize .
2735 .TP
2736 .B inopblog
2737 log2 of
2738 .BR inopblock .
2739 .TP
2740 .B agblklog
2741 log2 of
2742 .B agblocks
2743 (rounded up).
2744 .TP
2745 .B rextslog
2746 log2 of
2747 .BR rextents .
2748 .TP
2749 .B inprogress
2750 .BR mkfs.xfs (8)
2751 or
2752 .BR xfs_copy (8)
2753 aborted before completing this filesystem.
2754 .TP
2755 .B imax_pct
2756 maximum percentage of filesystem space used for inode blocks.
2757 .TP
2758 .B icount
2759 number of allocated inodes.
2760 .TP
2761 .B ifree
2762 number of allocated inodes that are not in use.
2763 .TP
2764 .B fdblocks
2765 number of free data blocks.
2766 .TP
2767 .B frextents
2768 number of free realtime extents.
2769 .TP
2770 .B uquotino
2771 user quota inode number.
2772 .TP
2773 .B pquotino
2774 project quota inode number; this is currently unused.
2775 .TP
2776 .B qflags
2777 quota status flags
2778 (0x01: user quota accounting is on,
2779 0x02: user quota limits are enforced,
2780 0x04: quotacheck has been run on user quotas,
2781 0x08: project quota accounting is on,
2782 0x10: project quota limits are enforced,
2783 0x20: quotacheck has been run on project quotas).
2784 .TP
2785 .B flags
2786 random flags. 0x01: only read-only mounts are allowed.
2787 .TP
2788 .B shared_vn
2789 shared version number (shared readonly filesystems).
2790 .TP
2791 .B inoalignmt
2792 inode chunk alignment in filesystem blocks.
2793 .TP
2794 .B unit
2795 stripe or RAID unit.
2796 .TP
2797 .B width
2798 stripe or RAID width.
2799 .TP
2800 .B dirblklog
2801 log2 of directory block size (filesystem blocks).
2802 .PD
2803 .RE
2804 .TP
2805 .B symlink
2806 Symbolic link blocks are used only when the symbolic link value does
2807 not fit inside the inode. The block content is just the string value.
2808 Bytes past the logical end of the symbolic link value have arbitrary values.
2809 .TP
2810 .B text
2811 User file blocks, and other blocks whose type is unknown,
2812 have this type for display purposes in
2813 .BR xfs_db .
2814 The block data is displayed in two columns: Hexadecimal format
2815 and printable ASCII chars.
2816 .SH DIAGNOSTICS
2817 Many messages can come from the
2818 .B blockget
2819 command.
2820 If the filesystem is completely corrupt, a core dump might
2821 be produced instead of the message
2822 .RS
2823 .I device
2824 .B is not a valid filesystem
2825 .RE
2826 .PP
2827 If the filesystem is very large (has many files) then
2828 .B blockget
2829 might run out of memory. In this case the message
2830 .RS
2831 .B out of memory
2832 .RE
2833 is printed.
2834 .PP
2835 The following is a description of the most likely problems and the associated
2836 messages.
2837 Most of the diagnostics produced are only meaningful with an understanding
2838 of the structure of the filesystem.
2839 .TP
2840 .BI "agf_freeblks " n ", counted " m " in ag " a
2841 The freeblocks count in the allocation group header for allocation group
2842 .I a
2843 doesn't match the number of blocks counted free.
2844 .TP
2845 .BI "agf_longest " n ", counted " m " in ag " a
2846 The longest free extent in the allocation group header for allocation group
2847 .I a
2848 doesn't match the longest free extent found in the allocation group.
2849 .TP
2850 .BI "agi_count " n ", counted " m " in ag " a
2851 The allocated inode count in the allocation group header for allocation group
2852 .I a
2853 doesn't match the number of inodes counted in the allocation group.
2854 .TP
2855 .BI "agi_freecount " n ", counted " m " in ag " a
2856 The free inode count in the allocation group header for allocation group
2857 .I a
2858 doesn't match the number of inodes counted free in the allocation group.
2859 .TP
2860 .BI "block " a/b " expected inum 0 got " i
2861 The block number is specified as a pair
2862 (allocation group number, block in the allocation group).
2863 The block is used multiple times (shared), between multiple inodes.
2864 This message usually follows a message of the next type.
2865 .TP
2866 .BI "block " a/b " expected type unknown got " y
2867 The block is used multiple times (shared).
2868 .TP
2869 .BI "block " a/b " type unknown not expected
2870 .SH SEE ALSO
2871 .BR mkfs.xfs (8),
2872 .BR xfs_admin (8),
2873 .BR xfs_copy (8),
2874 .BR xfs_logprint (8),
2875 .BR xfs_metadump (8),
2876 .BR xfs_ncheck (8),
2877 .BR xfs_repair (8),
2878 .BR mount (8),
2879 .BR chmod (2),
2880 .BR mknod (2),
2881 .BR stat (2),
2882 .BR xfs (5).