Section 12.1. Analysis Tools

12.1. Analysis Tools

Let us first look at some tools and sources of information that will be useful in understanding the implementation and operation of HFS+.

12.1.1. HFSDebug

We will use hfsdebug, a command-line file system debugger, as a companion program to this chapter.^[5] The term debugger is somewhat of a misnomer because a key feature (rather, a limitation) of hfsdebug is that it always operates on an HFS+ volume in read-only mode. It also does not allow for interactive debugging. Nevertheless, it is meant as a useful tool for exploring HFS+ internals, since it allows you to browse, inspect, and analyze various aspects of the file system. It has the following primary features.

^[5] I created hfsdebug to explore the working of HFS+ and to quantify fragmentation in HFS+ volumes. hfsdebug is available for download on this book's accompanying web site (www.osxbook.com).

• It displays raw details of data structures associated with the volume as a whole. Examples of such data structures are the volume header, the master directory block (in the case of an HFS+ volume embedded in an HFS wrapper), the journal files, and the on-disk B-Trees, namely, the Catalog file, the Extents Overflow file, the Attributes file, and the Hot Files B-Tree. We will discuss each of these data structures in this chapter.

• It displays raw details of data structures associated with individual file system objects such as files, directories, aliases, symbolic links, and hard links. Examples of such data structures include standard attributes, extended attributes (including ACLs), and file extents. hfsdebug supports looking up a file system object in multiple ways, namely, using its catalog node ID (typicallybut not always, as we will seethe same as the inode number reported by the POSIX API), using a Carbon-style specification consisting of the object's node name and the catalog node ID of its parent, or using the object's POSIX path.

• It calculates various types of volume statistics, for example, a summary of the numbers and types of file system objects present on a volume, the space used by these objects, special cases such as invisible and empty files, the top N files ordered by size or degree of fragmentation, and details of hot files.

• It displays details of all fragmented files on a volume.

• It displays locations and sizes of all free extents on a volume.

hfsdebug supports only the HFS+ volume formatthe older HFS format is not supported. However, it does handle HFS+ variants such as journaled HFS+, embedded HFS+, and case-sensitive HFS+ (HFSX).

Since much of the raw information displayed by hfsdebug is not available through a standard programming interface, hfsdebug works by directly accessing the character device associated with a volume. This means several things.

• You will require superuser access to use hfsdebug on volumes whose character devices are accessible only to the superuser.^[6] This is the case for the root volume.

  ^[6] When you run hfsdebug as the superuser (via the sudo command, say), it drops its privileges once it has completed the privileged operations it needs to perform.

• You can use hfsdebug even on a mounted HFS+ volume.

• Since hfsdebug does not access a volume through the volume's associated block device or through some higher-level API, its operation does not interfere with the buffer cache.

• Unlike a block device, which allows I/O to be performed at arbitrary byte offsets, character device I/O must be performed in units of the device's sector size, with I/O offsets being aligned on a sector boundary.

• hfsdebug is oblivious of the nature of the underlying storage medium, which could be a disk drive, an optical disc, or a virtual disk such as a disk image.

Finally, hfsdebug can also display the contents of the in-memory HFS+-specific mount structure corresponding to a mounted HFS+ volume. This data resides in the kernel as an hfsmount structure [bsd/hfs/hfs.h], a pointer to which is held in the mnt_data field of the mount structure [bsd/sys/mount_internal.h] corresponding to that mount instance. hfsdebug uses the Mach VM interface to retrieve this data. We are interested in the hfsmount structure because some of its relevant constituents have no on-disk counterparts.

12.1.2. Interface for Retrieving File System Attributes

HFS+ supports the getattrlist() system call, which allows retrieval of several types of file system attributes. The complementary system call, setattrlist(), allows those attributes that are modifiable to be set programmatically. Note that these two system calls are standard vnode operations in the Mac OS X VFS layerApple-provided file systems typically implement these operations. The attributes accessible through these calls are divided into the following attribute groups:

• Common attribute group (ATTR_CMN_*)attributes applicable to any type of file system objects, for example, ATTR_CMN_NAME, ATTR_CMN_OBJTYPE, and ATTR_CMN_OWNERID

• Volume attribute group (ATTR_VOL_*)for example, ATTR_VOL_FSTYPE, ATTR_VOL_SIZE, ATTR_VOL_SPACEFREE, and ATTR_VOL_FILECOUNT

• Directory attribute group (ATTR_DIR_*)for example, ATTR_DIR_LINKCOUNT and ATTR_DIR_ENTRYCOUNT

• File attribute group (ATTR_FILE_*)for example, ATTR_FILE_TOTALSIZE, ATTR_FILE_FILETYPE, and ATTR_FILE_FORKCOUNT

• Fork attribute group (ATTR_FORK_*)attributes applicable to data or resource forks, for example, ATTR_FORK_TOTALSIZE and ATTR_FORK_ALLOCSIZE

Besides attributes, getattrlist() can also be used to retrieve volume capabilities, which specify what features and interfaces (from among a predefined list of features and another list of interfaces) a given volume supports. We will see an example of using getattrlist() in Section 12.11.

12.1.3. Mac OS X Command-Line Tools

In Chapter 11, we came across several file-system-related command-line tools available on Mac OS X. In particular, we used the hdiutil program to manipulate disk images. Besides its typical use, hdiutil can print information about the given HFS+ or HFS volume when used with the hfsanalyze option.

$ sudo hdiutil hfsanalyze /dev/rdisk0s3 0x00000000131173B6 (319910838) sectors total 0x131173B0 (319910832) partition blocks native block size: 0200 HFS Plus ...

12.1.4. HFS+ Source and Technical Note TN1150

To make the most out of the discussion in this chapter, it would be valuable to have access to the Mac OS X kernel source. The following parts of the kernel source tree are particularly relevant to this chapter:

• bsd/hfs/the core HFS+ implementation

• bsd/hfs/hfs_format.hdeclarations of fundamental HFS+ data structures

• bsd/vfs/vfs_journal.*implementation of the file-system-independent journaling mechanism

It is also recommended that you have a copy of Apple's Technical Note TN1150 ("HFS Plus Volume Format"), since it contains information that we refer to (but don't always cover) in this chapter.