HFSLEUTH(8)

NAME
HFSleuth - HFS+/HFSX file system inspection tool

SYNOPSIS
HFSleuth [ commands ... ]

DESCRIPTION
HFSleuth is an powerful tool meant to interface with, diagnose, and potentially fix HFS+ and HFSX file systems. It offers the ability to inspect and traverse these filesystems on mounted or unmounted partitions, as well as disk image files (.dmg). The HFS+ logic is entirely self contained and written from scratch, and uses only POSIX APIs, making it suitable for use on other UN*X like systems (e.g. Linux). The tool requires read access to raw disk (/dev/rdisk*) files to work with unmounted partitions, a permission usually given only to root/operator. For DMG manipulation, it requires no permissions other than the obvious readability of the DMG file.

OPTIONS
While originally accepting (many) options, HFSleuth is, at present, designed to be used interactively. This makes sense, considering the processing required when loading an HFS+/HFSX file system. The tool is easily scriptable, as it accepts its commands from standard input (<)

COMMANDS
HFSleuth provides a rich command line environment. Typing "?" or "help" will display the list of the commands. Commands may be abbreviated, so long as the abbreviation is not ambiguous. fs filesystem
  Specifies which file system HFSleuth will operate on. The argument can be a disk special device, mount point (OS X only), or a DMG file. HFSleuth will read the filesystem, optionally reading through any Apple Partition Map (APM) or GUID Partition Tables (GPT) to automatically locate a suitable HFS+ (or HFSX) partition. The HFSleuth prompt will change to display the volume label of the selected filesystem, along with the current working directory (initially, "/", the root).
  Running this command later with no argument will display the currently selected file system. Running it again with a different argument will change the selected file system to another. listfs (OS X only)
  Displays a list of presently mounted HFS+ or HFSX filesystems, along with their mount options. volinfo
  Displays the HFS volume header of the currently selected file system. Output is similar to the following Volume Header:
    Signature:              0x482B (H+)                 # H+: HFS+, HX: HFSX

    Version:                4                           # 4:  HFS+, 5:  HFSX
    Attributes:             80002000 - journaled        # Volume attributes
    Number of Files:        723823
    Number of Folders:      163174
    Free Blocks:            3074711                     # Unused allocation blocks
    Total Blocks:           61069442                    # total allocation blocks
    Block Size:             4096                        # Usually 4K on OS X, 8K on iOS
    ClumpSize:              65536                       # size of allocated block "clumps"
    Created on:             Sun Jul 22 15:16:18 2012    # Creation (format) date of FS
    Modified on:            Fri Feb 22 20:48:39 2013    # Modification (rw mount) date of FS
    Next CNID:              4854996                     # Next Catalog Node ID (inode #) hint
    Last Mounted by:        4846534a (HFSJ)             # HFSJ - Journaled mount. 10.0 - no journal
allocation
   Displays allocation bitmap statistics. The allocation bitmap (contained in the Volume Header) is a data fork representing all the blocks in the file system. This command will print out the number of available allocation blocks, as well as dump the bitmap into an HTML table view (/tmp/allocation.html). For DMGs, this map is always "perfect" (non-fragmented, one big contiguous chunk with free space at the end). For an actual file system, it can be quite interesting, with "holes". Note that the resulting HTML file can be downright huge, and can hang safari. I'm working on exporting to a better format (e.g. GIF). This still shows a valuable map of the disk fragmentation. catalog
  This command selects the filesystem catalog to be the active B-Tree, and dumps its details. The catalog holds all the files in the system (but not their extended attributes). The output of this command will be something like the following:
    catalog B-Tree dump:
    Tree type: 0 # Always "0" for a catalog
    Tree depth: 4 # Usually 4.
    Root node: 26803 # B-Tree root, for initial traversal
    First leaf: 26082 # First leaf node, for leaf traversal
    Last leaf: 44906 # Last leaf node, for leaf traversal
    Leaf records 1773998 # Leaf records contains files, folders and threads.
    Total nodes: 59008 # Total number of nodes in file system
    Free nodes: 13460 # Number of free nodes.
    Node size: 8192 # Size of a catalog node. Typically 8k
    Map node: 0 # Map node, if any (usually, none)
    Compare: CF # Case Folding (insensitive) for HFS+, Binary Compare for HFSX attributes
  This command selects the filesystem attribute B-Tree to be the active B-Tree, and dump its details. The attributes tree holds the extended attributes of files and folders on the system, some (but not all) of which are visible with xattr(1) and/or ls(1) -@. The output of the command is a dump of the tree, similar to catalog. dump Node
  Dumps the contents (all records) of the node specified in either "ls -li" compatible format (for catalog nodes) or raw format (for attribute nodes). Output may be formatted to XML, if toggled. snapshot
  This command saves the entire catalog to a file in /tmp. This is useful for (currently experimental) features, such as snapshot comparison, as well as undeletion of files (assuming their fork blocks have not been overwritten). Note the file created can be rather large, with a size of (catalog Total Nodes * Node size). In the example above, this would amount to 461MB. search target
  Search the file system for a file matching Catalog Node ID (CNID) number, or pathname specified in target. Functionally similar to find(1) -inum or -name, but much faster. pull pathname
  Retrieve the file specified by pathname, and copy it to /tmp. Especially useful for extracting a specific file from an unmounted file system, or from a disk image, even more so on non-Apple OSes.

SHELL-LIKE COMMANDS
HFSleuth supports directory navigation commands, presently "cd" and "ls". The "cd" command changes the working directory (and the indication on the prompt), and is symbolic-link aware. The "ls" command functions like an "ls -li", showing the CNID (inode number) and a long listing for each file in the present working directory. It additionally supports the '-h', '-O' and '-@' modifiers (as per the standard ls(1)). HFSleuth also supports the "!" character as a shell escape.

OPTIONS
xml
  Toggle XML output on/off color
  Toggle color output on/off (can also set externally with JCOLOR=1) debug
  Toggle debug output on/off. Useful for gaining insight into what happens "behind the scenes" (such as B-Tree lookups), as well as finding bugs. May be very verbose. (can also set externally with JDEBUG=1)

NOTE ON UNICODE SUPPORT
  HFS+/HFSX use UTF-16, in PPC (big endian) format. Most UNIX terminals use UTF-8. HFSleuth therefore emits all of its output in UTF-8, and translates its input to UTF-16. This has been tested with various languages and character sets, but it is more than possible something in the Unicode translation logic is buggy. If you can't see or access your favorite UTF-16 encoded file, just let me know.

HISTORY
HFSleuth first accompanied the author's book, "Mac OS X and iOS Internals - To The Apple's Core". The tool is provided as one of the free downloads provided for the book, and the latest version can always be obtained at http://www.newosxbook.com/. HFSleuth shares no code with any open sources, Apple's or otherwise. It relies on zlib and bz2lib for decompressing disk images. The inspiration for HFSleuth came from Amit Singh's "HFSDebug", which accompanied his excellent tome "Mac OS X Internals - A systems approach" (http://www.osxbook.com). That tool, however, has only been supplied as a PPC binary, which made it incompatible with OS X as of Lion, when Rosetta (the PPC emulation) was removed. Additionally, it has been superseded by FileXRay, a commercial tool.

BUGS
\x00\x00\x00\x00HFS+ Directory Data, being a directory name containing NULL bytes, is improperly displayed in "ls". This will be fixed sometime in the future, as it breaks the elegant unicode logic implemented (thanks, Apple!) Experimental functions deemed too unstable may not work in the publicly available version of this tool (and would likely be entirely disabled). If you feel daring, and would like to assist in beta-testing and improving this tool, simply contact the author anytime. Comments and suggestions for improvements are naturally welcome.

CHANGELOG
   11/11/2016 - Development resumed,
    - support for file compression (type 4, zlib) added
    - support for file compression type 8 (for MacOS compression as of 10.10)

STILL TO COME
put
   The inverse of pull, allows uploading a file to an HFS+/HFSX partition or DMG. support for file compression type 8 (for MacOS compression as of 10.10) Extensibility via DYLD_INSERT_LIBRARIES/LD_PRELOAD
   Allowing third party libraries to provide callbacks which will be called from HFSleuth

SEE ALSO
hdiutil(1)