      DFSee version 16.3 2019-07-30  (c) 1994-2019: Jan van Wijk
 =========================[ www.dfsee.com ]==========================

_______________________________________________________________________________

C O N T E N T S:
_______________________________________________________________________________

   Command reference    = overview of APFS specific commands
   Detailed description = description for every command


  Note: All generic commands can be found in DFSCMDS.TXT, for example:

        ALLOC,  CHECK,  CLONE,  RESIZE,  RECOVER,  SAVETO,  SCAN,  WIPE

_______________________________________________________________________________

C O M M A N D   R E F E R E N C E:
_______________________________________________________________________________

APFS specific commands

Active filesystem : APFS, specific commands are:

 BL              = Translate and display 'this' LSN as a block number
 BL block  [cmd] = Translate specified block-number to LSN, display using 'cmd'
 CATS [id][name] = Search FS-tree for INO and optional file/folder name
 COLlissions     = Find filename duplicates (HASH collisions) in APFS volume
 CP      [index] = Refresh to latest or specified checkpoint (history)
 DESC    [f [l]] = Describe object TYPE/SUBTYPE, and FS/XFIELD RECORD types
 DUMP   [params] = Dump recognized APFS blocks to display, with some filtering
 FOLDER [dirIno] = Display Catalog directory data for specified folder INO nr
 LEAVES [params] = Display contents of various APFS filesystem tree leaf-nodes
 LEAF       [id] = Determine NEXT-leaf ID for given/last leaf ID, 0 = FIRST
 SUPER           = Display the selected container SUPERBLOCK structure
 VI  [vol-index] = Select a volume from a list, or specified volume index
 VIRT   o x [-c] = Find blocknr for objec/transaction ID, volume or container

 For an up-to-date list of commands, use the '?' command


 APFS specific sector types  (see ??? command)

  's' = APFS C-superblock    'B' = APFS Btree (root)    'N' = APFS generic node
  'M' = APFS SpaceManager    'S' = Sp CAB lvl2 Index    'i' = Sp CIB lvl1 Index
  'm' = Sp  BitMap  Block    'O' = Object Map  Block    'c' = CheckPoint Map
  'D' = Volume Superblock    'Y' = Container Reaper     'y' = Cont. Reaper List
  'E' = EFIboot JumpStart    'F' = Fusion WrBk Cache    'f' = Fusion WrBk List
  'x' = Encr RollingState    'z' = General Bitmap       'Z' = Gen BitMap List

             For an up-to-date list, use the '???" command
_______________________________________________________________________________

D E T A I L E D   D E S C R I P T I O N:
_______________________________________________________________________________

BL               = Translate and display 'this' LSN as a block nr

 Purpose:       Display block value for the CURRENT sector 'this'

 Parameters:    none

 Output:        cluster value

 Remarks:       APFS specific, and alias for the generic 'CL' command
_______________________________________________________________________________

BL   block [cmd] = Translate hex block number to hex LSN, display using cmd

 Purpose:       Display sector for specified block in default or cmd format

 Parameters:    block   mandatory  Block value 0 .. max-block

                cmd     optional   Command to use for displaying the sector

 Output:        display of the sector

 Remarks:       APFS specific, and alias for the generic 'CL' command
_______________________________________________________________________________

CATS [id][name] = Search FS-tree for INO and optional file/folder name

 Purpose:       Search FS-tree for fsID and optional file/folder name, display result

 Parameters:    Id      Primary key: Parent-INO for DIR; INO for other (attribute) records\n"

                Key     Additional key value: Name for DIR or XATTR; sibling-ID for sibling link
                        Without a Key, it will search for an INODE record  for INO 'Id'

 Options:       -r:N    Select type of record to search, default INO, or DIR when a name is given
                        1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM

 Output:        A single line with either the type and location of the record found,
                or an error message

_______________________________________________________________________________

COLlissions     = Find filename duplicates (HASH collisions) in APFS volume

 Purpose:       Find any filename HASH value collisions in an APFS volume

 Parameters:    none

 Options:       -test:[mask]   Ignore DIR, optional mask some HASH bits (default 0xffffff)

                -refresh-      Do NOT synchronize to latest volume checkpoint automatically

 Output:        A single line for each file/directory where the HASH-value for its name
                is the same as for another one (the previous one in the catalog tree)
                with progress info on the status bar and a summary displayed at the end.

 Remarks:       The -test option is simply there to test the output format for
                this function, since actual hash collissions are extremely rare.
                (1 in 4 million, for names within a single directory)
                With '-test' identical names in DIFFERENT directories may cause a hit,
                resulting in thousands of them for a typical macOS APFS boot volume.

_______________________________________________________________________________

CP      [index] = Refresh to latest or specified checkpoint (history)",

 Purpose:       Determine latest valid checkpoint, optional offset by checkpoint index

 Parameters:    index    Number of checkpoints to go BACK in history, default 0

 Options:       -O:s     NO display of superblocks, no output     (silent)
                -O:q     Display superblocks in a compact format  (quiet)
                -O:v     Display superblocks with more detail     (verbose)

 Output:        Results of finding the checkpoint with related superblocks

 Remarks:       The -O: verbodity options work with many APFS commands,
                to control the amount/detail of the displayed information

                Volumes that are MOUNTED when opened, have a tendency to change,
                resulting in the disk contents being inconsistent for a while.
                This happens more quickly when there are many changes, which is
                the case for the macOS boot volume for example.

                Due to the 'copy on write' nature of the APFS filesystem, the
                most changed objects like superblocks and FS-tree nodes will
                be relocated all the time (using virtual to physical mappings)
                resulting in the displayed (and cached) values in DFSee become
                obsolete/invalid, causing all kinds of display/analysis errors.

                For the macOS system volume this can happen in mere SECONDS!

                The 'CP' command synchronizes to the LATEST state on the disk,
                refreshing the virtual-to-physical mapping trees, usually
                resolving the inconcistencies that way. However, in some cases
                you may need to (re)locate the information you were looking at
                by starting again from the ROOT (restarting 'browse' for example)

                Several commands, like 'browse', 'folder' and 'leaves' will
                automatically execute a 'cp' command at certain intervals
                to reduce the risk of inconcistencies when working.

                That said, the only SAFE and RELIABLE way to analyse an APFS
                filesystem is to UNMOUNT the filesystem, making them STABLE.

                One way to achieve that (unmount the filesystems, keep the disk)
                is to use the DFSee menu (using the macOS version of DFSee):

                        File ->
                           Device and Volume management ->
                              Unmount volumes from a disk ->
                                 ... select the disk with the APFS partition ...

                Make sure to select THAT disk, not the 'virtual' one created
                by macOS for each of the APFS partitions present.

                After that re-open the partition, or issue a manual 'cp' command.

                On (almost ?) all other operating systems, the APFS partition
                will not be mounted anyway, so it is safe to work that way.

                Also when creating an IMAGE (like a compressed IMZ) from an
                APFS partition, it is best to do that when it is UNMOUNTED
                or you will face the same problems when opeing the image
                for analysis ...

_______________________________________________________________________________

DUMP   [params] = Dump recognized and valid APFS blocks to display

 Purpose:       Iterate over all disk-blocks and display the recognized types

 Parameters:    *                 dump until end of partition, or <Esc> key
                blocks            # recognized blocks to dump,  default 2000

                start             blocknumber to start dumping, default 0

                types             sector-types to be included,  default all

 Options        Various options are available to select certain types of
                blocks or records (when the blocks are tree nodes)

    -dir:P      On tree/node objects, limit to parent-INO  P (use on FS-Tree only)
    -r:N        On tree/node objects, limit to record type N (use on Snap/FS-Tree)
                1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM
    -header-    Suppress display of header info, show blocknumber and contents only
    -list       On tree/node objects, add each found (DIR) record to the sector-list
    -name:wildc On tree/node objects, display DIR/XATTR only if wildcard name match
    -node       On tree/node objects, display NODEs only (tree) no LEAF (contents)
    -node-      On tree/node objects, display LEAFs only (contents) no NODE (tree)
    -raw        On tree/node objects, NO record interpretation, dump RAW key/value
    -tree[:st]  Limit to blocks with (tree) subtype 'st' default is 14 for FS-Tree
                14=FS-Tree  15=Extents-Tree  16=Snapshot-Tree  21=Fusion-Tree
    -X:Xid      Limit to blocks with Xid same/smaller as given transaction-ID 'Xid'
    -x:subType  Exclude blocks with object subtype given    (list with  'desc')
    -x          Exclude blocks with object subtype 9        (SpcMan Free-Queue)
    -y:subType  Exclude blocks with object subtype given    (list with  'desc')
    -y          Exclude blocks with object subtype 11              (Object Map)
    -z:subType  Exclude blocks with object subtype given    (list with  'desc')
    -z          Exclude blocks with object subtype 15  (Block-Extent-reference)

                For an exact and up-to-date list of options, use 'dump -?'

 Output:        Formatted contents of most of the know block-types, or a brief
                HEX-dump for blocks that are valid, but not recognized.

 Remarks:       When looking FS-tree (directory/Inode etc) information it will
                be MUCH faster to use the 'leaves' command instead, since that
                only searches the LEAF nodes in the catalog B-tree for the FS.
_______________________________________________________________________________

DESC    [f [l]] = Describe object TYPE/SUBTYPE, and FS/XFIELD RECORD types",

 Purpose:

 Parameters:    first   First numeric blocktype value to show the type description for
                last    Last  numeric blocktype value to show, default same as 'first'

 Output:        Numbered lists of the Blocktypes (with associated selection character),
                Btree record types as used in the FS, extent and snapshot B-trees, and
                the types of 'Xfields' as used in Directory and Inode record types.

 Remarks:       Without specified values, all defined types are listed, and the
                Btree FS/XFIELD RECORD types are listed with a short description as well

                The displayed output as of the 16.0 release of DFSee is:

 APFS block/object types/subtypes (see 'dump -?', 'leaves -?', 'find' and '???' commands)

 (sub) Type number :    1 = 0x0001 : Container Superblock         's' = Block/Sector selection char
 (sub) Type number :    2 = 0x0002 : Btree-Root                   'B' = Block/Sector selection char
 (sub) Type number :    3 = 0x0003 : Btree-Node                   'N' = Block/Sector selection char
 (sub) Type number :    4 = 0x0004 : Unknown block type!
 (sub) Type number :    5 = 0x0005 : Spacemanager                 'M' = Block/Sector selection char
 (sub) Type number :    6 = 0x0006 : Spm CAB level2 Index         'S' = Block/Sector selection char
 (sub) Type number :    7 = 0x0007 : Spm CIB level1 Index         'i' = Block/Sector selection char
 (sub) Type number :    8 = 0x0008 : Spm Bitmap                   'm' = Block/Sector selection char
 (sub) Type number :    9 = 0x0009 : Spm Free Queue
 (sub) Type number :   10 = 0x000A : Extent list
 (sub) Type number :   11 = 0x000B : Object Map                   'O' = Block/Sector selection char
 (sub) Type number :   12 = 0x000C : CheckPoint Map               'c' = Block/Sector selection char
 (sub) Type number :   13 = 0x000D : Volume Superblock            'D' = Block/Sector selection char
 (sub) Type number :   14 = 0x000E : FS tree
 (sub) Type number :   15 = 0x000F : Block-Extent-ref
 (sub) Type number :   16 = 0x0010 : Snapshot meta tree
 (sub) Type number :   17 = 0x0011 : Reaper object                'Y' = Block/Sector selection char
 (sub) Type number :   18 = 0x0012 : Reaper list                  'y' = Block/Sector selection char
 (sub) Type number :   19 = 0x0013 : Map Snapshot
 (sub) Type number :   20 = 0x0014 : EFI JumpStart, boot          'E' = Block/Sector selection char
 (sub) Type number :   21 = 0x0015 : Fusion Cached
 (sub) Type number :   22 = 0x0016 : Fusion WrBack Cache          'F' = Block/Sector selection char
 (sub) Type number :   23 = 0x0017 : Fusion WrBack List           'f' = Block/Sector selection char
 (sub) Type number :   24 = 0x0018 : Encr Rolling State           'x' = Block/Sector selection char
 (sub) Type number :   25 = 0x0019 : Gen Purpose Bitmap           'z' = Block/Sector selection char
 (sub) Type number :   26 = 0x001A : Gp Bitmap Tree

 Btree RECORD type :    1 = 0x0001 : SnapMeta      Xfield type :    1 = 0x0001 : SnapshotID
 Btree RECORD type :    2 = 0x0002 : PhysExtent    Xfield type :    2 = 0x0002 : DeltaTrOID
 Btree RECORD type :    3 = 0x0003 : Inode         Xfield type :    3 = 0x0003 : DocumentID
 Btree RECORD type :    4 = 0x0004 : Xattr         Xfield type :    4 = 0x0004 : FileName
 Btree RECORD type :    5 = 0x0005 : SiblingLnk    Xfield type :    5 = 0x0005 : PrevFsize
 Btree RECORD type :    6 = 0x0006 : DstreamId     Xfield type :    6 = 0x0006 : Reserved-6
 Btree RECORD type :    7 = 0x0007 : CryptState    Xfield type :    7 = 0x0007 : FinderInfo
 Btree RECORD type :    8 = 0x0008 : FileExtent    Xfield type :    8 = 0x0008 : DataStream
 Btree RECORD type :    9 = 0x0009 : DirEntry      Xfield type :    9 = 0x0009 : Reserved-9
 Btree RECORD type :   10 = 0x000A : StatDirect    Xfield type :   10 = 0x000A : DirStatKey
 Btree RECORD type :   11 = 0x000B : SnapName      Xfield type :   11 = 0x000B : FsMnt-UUID
 Btree RECORD type :   12 = 0x000C : MapSibling    Xfield type :   12 = 0x000C : Reserved-C
                                                   Xfield type :   13 = 0x000D : SparsBytes
                                                   Xfield type :   14 = 0x000E : Rdevice-ID

_______________________________________________________________________________

FOLDER [dirIno] = Display Catalog directory data for specified folder INO nr",

 Purpose:       Display the contents of a folder (directory) in a DFSee 'DIR' format

 Parameters:    dirIno      Inode number of the folder/directory to show

 Options:       -l-         Do NOT create a new sector list from the folder contents

 Output:        A table like display of directory entries, with two lines per
                listed file, subdirectory or symlink, in alternating colors

 Remarks:       Each entry is identified by a .NNNN number at the start of the line,
                represeting the index in the sector-list, and mofe detailed infomation
                about that entry can be displayed using a command like '.2' to show
                info on entry '.000002'
_______________________________________________________________________________

LEAVES [params] = Display contents of various APFS filesystem tree leaf-nodes",

 Purpose:       Display contents of APFS filesystem trees (leafs) , with some filtering

 Parameters:    *        display until the last tree LEAF node is reached, or <Esc> key
                leafs    # recognized LEAF nodes to display,  default 2000
                start    Leaf ID to start display, default 0

 Options:

    -refresh-   Do NOT synchronize to the latest volume checkpoint automatically
    -debug      Only list the LEAF (virtual) node ID values, no contents display\n

    -dir:P      On tree/node objects, limit to parent-INO  P (use on FS-Tree only)
    -r:N        On tree/node objects, limit to record type N (use on Snap/FS-Tree)
                1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM

    -header-    Suppress display of header info, show blocknumber and contents only
    -list       On tree/node objects, add each found (DIR) record to the sector-list
    -name:wildc On tree/node objects, display DIR/XATTR only if wildcard name match
    -raw        On tree/node objects, NO record interpretation, dump RAW key/value
    -tree[:st]  Use prepared LEAF-cache for selected tree, default is 14 for FS-Tree
                14=FS-Tree  15=Extents-Tree  16=Snapshot-Tree

    -X:Xid      Limit to blocks with Xid same/smaller as given transaction-ID 'Xid'
    -x:subType  Exclude blocks with object subtype given    (list with  'desc')
    -x          Exclude blocks with object subtype 9        (SpcMan Free-Queue)
    -y:subType  Exclude blocks with object subtype given    (list with  'desc')
    -y          Exclude blocks with object subtype 11              (Object Map)
    -z:subType  Exclude blocks with object subtype given    (list with  'desc')
    -z          Exclude blocks with object subtype 15  (Block-Extent-reference)

 Output:        One or two lines per record found/matching, formatted to show the
                most relevant information in that record

 Remarks:       The records as displayed in the sequence of 'leaf' nodes is determined
                by the primary/secondary key values, which are either the PARENT-INODE
                (for DIR-RECORDS) or the INODE (for most others) and the record type.
                For some record types there is a tertiary key value, for example the
                filename for DIR-RECORDS or the fileoffset for File-extent records.
_______________________________________________________________________________

LEAF       [id] = Determine NEXT-leaf ID for given/last leaf ID, and display leaf

 Purpose:       Display the NEXT (in filesystem Btree-ordering) LEAF node contents

 Parameters:    leaf Id    LEAF node ID to find/display (virtual or physical block-number)
                           when not specified, will find the NEXT LEAF node in the tree
                           Leaf-ID 0 will result in displaying the FIRST leaf in the tree.

 Options:       -tree[:st] Use prepared LEAF-cache for selected tree, default is 14 for FS-Tree
                           14=FS-Tree  15=Extents-Tree  16=Snapshot-Tree

 Output:        One or two lines per record found/matching, formatted to show the
                most relevant information in that record

 Remarks:       In addition to the specific '-tree' option, many of the selection
                or formatting options of the 'dump' and 'leaves' command also
                work with the 'leaf' command

                When starting with a 'leaf 0' command, and repeating just 'leaf'
                after that, the output will be very similar to the 'leaves'
                command that iterates over all known tree LEAF records.
_______________________________________________________________________________

SUPER           = Display the filesystem SUPERBLOCK sector

 Purpose:       Display the contents of the APFS container superblock

 Parameters:    none

 Output:        Dirty status and sone other container level details

_______________________________________________________________________________

VI  [vol-index] = Select a volume from a list, or specified volume index",

 Purpose:       Select a Volume to be used, with its associated directory-tree

 Parameters:    index   Volume index, 0 .. N                 (see 'super' display)

 Options:       -O:s     NO display of superblocks, no output     (silent)
                -O:q     Display superblocks in a compact format  (quiet)
                -O:v     Display superblocks with more detail     (verbose)

 Output:        Filesystem/superblock information, depening on verbosity

 Remarks:       And APFS container CAN contain multiple volumes, each with
                its own directory/file tree, but SHARING the same freespace
                blocks with the other volumes in the same container.

                A typical macOS bootdrive (Mojave) contains 4 volumes in
                its system APFS container partition.

                When opening a container (partition) the FIRST volume will
                be selected automatically, for the macOS system partition
                that is the regular user partition (called 'Macintosh HD')
_______________________________________________________________________________

VIRT   o x [-c] = Find blocknr for objec/transaction ID, volume or container",

 Purpose:       Find Object/Transaction-ID pair, in Volume/Container Object-Map, and display

 Parameters:    oid     Virtual Object-ID to find, from superblocks and related structures
                xid     Transaction-ID to match (max), matches ANY Xid when not specified

 Options:       -c      Search in overall CONTAINER Object-Map, not the selected-VOLUME one
                -O:q    Display object in a compact format, using less lines (quiet)
                -O:v    Display object with more detail,    using more lines (verbose)

 Output:        A display of the resulting block/sector, in the format suitable
                for that kind of block, or an error message when the supplied
                'oid' value does not represent a virtal object.
_______________________________________________________________________________

