Search:  
Gentoo Wiki

Hfsplus


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc
Hexley, the mascot of Darwin
Hexley, the mascot of Darwin

HFS+, HFS Plus, or Mac OS Extended are names for a file system developed by Apple Computer to replace their Hierarchical File System (HFS). In addition to being the default file system on modern Apple computers, HFS+ is one of two formats that are supported by the iPod hard-disk based music player. HFS+ supports UNIX style file permissions, and has support in the kernel. The following series of steps adds support for HFS+ capability and tools.

This HOWTO shows how to patch Apple's utilities to work under Linux. These utilities include mkfs.hfsplus and fsck.hfsplus. These Darwin utilities allow creating and repairing of HFS+ partitions in Linux.

The Darwin tools are not to be confused with the Penquin PPC tools (i.e. hpmount, hpfsck) contained in the Gentoo package sys-fs/hfsplusutils. They do not operate or mount newer hfsplus partitions, but are the only hfsplus tools included on a Gentoo PPC LiveCD. A number of Linux distributions omit HFSplus kernel support.

The Linux kernel driver at this time does not support writing to HFS+ journaled drives and partitions. Writing to a hfsplus partition is only possible after journaling has been disabled. While the Linux HFS+ driver is technically stable, it is not recommended for production environments.

Contents

Adding HFS+ Kernel Support

In order for Linux to read the HFS+ partition maps and partitions, kernel support is required. In Linux kernel 2.6 and newer, HFS+ support is included but may not be enabled; however, in Linux kernel 2.4 support can be added by patching the kernel. This patch can be obtained from an SourceForge project called linux-hfsplus. The following steps assume use of a 2.6 kernel or a HFS+ patched 2.4 kernel. Type the following commands at a terminal to launch the kernel configuration program.

cd /usr/src/linux
make xconfig

After the qconf program opens, expand Device Drivers, File Systems, and Miscellaneous filesystems then enable Apple Extended HFS file system support and Apple Macintosh file system support. Then under Partition Types enable Macintosh partition map support. Save changes by pressing Ctrl-S and close the qconf program. Recompile and install your new kernel.

Testing Kernel Support

Once the HFS+ support has been added to the kernel the filesystem can be mounted and manipulated by the operating system. The following command will query kernel for HFS+ support; it should return hfs and hfsplus.

grep hfs /proc/filesystems
hfs
hfsplus

Note that you might need to modprobe the hfs and hfsplus modules if you compiled them as modules.

Listing of Partitions

The /proc/partitions file contains a listing of all partitions currently connected on the system. For example, the fourth generation Apple formatted iPods have three partitions. The first partition is a partition map, the second is a firmware partition, and the third is a HFS+ partition. The sdx prefix, where x is a letter in the alphabet, is used for SCSI emulation for Firewire and USB. In the following case, the iPod is located at sda.

cat /proc/partitions
major minor  #blocks  name
   3     0   48122708 hda
   3     1   47070418 hda1
   3     2    1052257 hda2
   8    48   39063023 sda
   8    49         31 sda1
   8    50      32768 sda2
   8    51   39030224 sda3
Note: Under Linux the HFS/HFS+ partition map is represented as a the first partition in sdX1; on the other hand, PC BIOS/MSDOS partition maps are not included as a separate partition and are located in the first ~32KB of the raw disk device (/dev/hda or /dev/sda)

This shows how Macintosh Partition maps are treated as separate partitions under Linux, by counting blocks contained within partitions.

      Macintosh disk      PC/MSDOS disk
            31 sda1             33 (hidden partition map)
+        32768 sda2       47070418 hda1
+     39030224 sda3        1052257 hda2                 
-------------------------------------------------------------
=     39063023 sda        48122708 hda

Using GNU Parted to View Partitions

Many Linux distributions do not include the partitioning tool parted; instead, despite its inability to interpret Macintosh partition maps, most use fdisk. In Gentoo, parted can be installed using the emerge command, or similar command in other distributions.

emerge parted
parted /dev/sda
GNU Parted 1.6.23
Copyright (C) 1998 - 2005 Free Software Foundation, Inc.
This program is free software, covered by the GNU General Public License.
Using /dev/sda
(parted) print
Disk geometry for /dev/sdd: 0kB - 40GB
Disk label type: mac
Number  Start   End     Size    Filesystem  Name                  Flags
1       1kB     32kB    32kB                 partition map         
2       32kB    34MB    34MB                 firmware              
3       34MB    40GB    40GB                 disk       

While parted does allow viewing of the Macintosh partition maps, it does not support modification, identification, or creation of these partitions.

Note: Using a gentoo patched version of parted and mac-fdisk for PPC you can manipulate mac partitions see here; however these patched tools may be masked on x86

Compiling Apple's Filesystem Tools

Darwin Package ported to Linux
Darwin Package ported to Linux
Warning: This tools are not x86_64 compatible. See Gentoo bugzilla link at bottom
Warning: A hack was made for x86_64 that seems to work. See Ubuntu Forums link at bottom

The following commands run as root will download, compile, and install Apple's open source HFS+ tools.

The diskdev package, including most Darwin kernel code, is under the APSL (Apple Public Source License). The patches themselves are licensed under the GPL; however, their use may fall under restrictions from the APSL.

Port the Darwin Disk Utilites

The OS X 10.4.[4-7] / Darwin 8.[4-7](x86) tools can be ported to x86/PPC Linux.

Gentoo

Gentoo users can use Portage

emerge diskdev_cmds

Manual Installs

If wget doesn't work for you, you can download the source with a web browser at the Apple repositories but you will need to sign up for an ADC login. When using these instructions on systems other than Gentoo, you need to use GCC 3.4 and libssl-dev to compile. With these installed you should either symlink gcc-3.4 --> gcc temporarily or edit Makefile.lnx to use gcc-3.4 specifically. Works on Ubuntu 7.10 Gutsy 4.18.2008. Download the Apple Source Code

wget http://www.mythic-beasts.com/resources/appletv/mb_boot_tv/diskdev_cmds-332.14.patch.bz2
tar zxf diskdev_cmds-332.14.tar.gz
bunzip2 -c diskdev_cmds-332.14.patch.bz2 | patch -p0
cd diskdev_cmds-332.14
make -f Makefile.lnx
cp newfs_hfs.tproj/newfs_hfs /sbin/mkfs.hfsplus
cp fsck_hfs.tproj/fsck_hfs /sbin/fsck.hfsplus
cd /sbin
ln -s mkfs.hfsplus mkfs.hfs
ln -s fsck.hfsplus fsck.hfs

Other Versions

Also experimental x86/PPC OS X 10.4.[4-7] / Darwin 8.[4-7](PPC) is available using the above instructions below files.

http://www.ecl.udel.edu/~mcgee/diskdev_cmds/hfs-tools-332.11.1.ebuild
http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-332.14.tar.gz
http://www.ecl.udel.edu/~mcgee/diskdev_cmds/diskdev_cmds-332.11.1.patch.bz2

Josejx's current x86/PPC Linux port from OS X 10.4.3 / Darwin 8.3

http://www.ecl.udel.edu/~mcgee/diskdev_cmds/hfs-tools-332.11.ebuild
http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-332.11.tar.gz
http://dev.gentoo.org/~josejx/diskdev_cmds-332.11.patch.bz2

The original, now outdated, x86 Linux port from OS X 10.2.[5-6] / Darwin 6.[5-6] is available below.

http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-208.11.tar.gz
http://www.ardistech.com/hfsplus/diskdev_cmds.diff.gz

Creating HFS+ Filesystems with mkfs.hfsplus

Warning: At this time -J (journaled) should be avoided under Linux. See next section on Journaling.
Note: At this time -s (case-sensitive) should be avoided in kernels before 2.6.16. Also, do not use -s on an iPod as it will not always detect your music. See next section on mounting.

Code: Output of mkfs.hfsplus
mkfs.hfsplus
usage: mkfs.hfsplus [-h | -w] [-N] [hfsplus-options] special-device
  options:
        -h create an HFS format filesystem (HFS Plus is the default)
        -N do not create file system, just print out parameters
        -s use case-sensitive filenames (default is case-insensitive)   
        -w add a HFS wrapper (i.e. Native Mac OS 9 bootable)
  where hfsplus-options are:
        -J [journal-size] make this HFS+ volume journaled               
        -G group-id (for root directory)
        -U user-id (for root directory)
        -M access-mask (for root directory)
        -b allocation block size (4096 optimal)
        -c clump size list (comma separated)
                e=blocks (extents file)
                c=blocks (catalog file)
                a=blocks (attributes file)
                b=blocks (bitmap file)
                d=blocks (user data fork)
                r=blocks (user resource fork)
        -i starting catalog node id
        -n b-tree node size list (comma separated)
                e=size (extents b-tree)
                c=size (catalog b-tree)
                a=size (attributes b-tree)
        -v volume name (in ascii or UTF-8)
  examples:
        mkfs.hfsplus -v Untitled /dev/rdisk0s7 
        mkfs.hfsplus -v Untitled -n c=4096,e=1024 /dev/rdisk0s7 
        mkfs.hfsplus -w -v Untitled -c b=64,c=1024 /dev/rdisk0s7

mkfs.hfsplus can be used to initialize/format/create the filesystem.

mkfs.hfsplus -v iPod /dev/sda3
Initialized /dev/sdd3 as a 37 GB HFS Plus volume

Use gtkpod or some other program to create iPod folder structure and add music.

Disable Journaling

Note: Kernels older than 2.6.15 may incorrectly mount journalized partitions read/write
2.6.15-rc4 journaling kernel fix.

If you plan to work with a HFS+ partition under Linux and OS-X make sure journaling is disabled. Kernels older than 2.6.15 will mount journalized partitions read-write by default. When these older kernels will make changes to the filesystem without updating the journal the inconsistencies created which could lead to data loss.

To disable journaling on a parition under Apple OS-X terminal (non-destructive)

diskutil disableJournal volumeName

You can also use the "Disk Utility" GUI

have the iPod mounted
select the iPod
hold the option key and click file->disable journaling 

Or you could reformat the partition under Linux

mkfs.hfsplus -v "iPod" /dev/sdXn

Mounting HFS+ partitions

Some HFS+ filesystems are wrapped inside of an HFS file system in order to display an error message on a Macintosh that does not support HFS+ and provide boot support. If the partition is wrapped inside of HFS partition, a special filesystem type option will be required to mount the drive. This command will show a common way to mount both wrapped and unwrapped hfsplus partitions.

mount -t hfsplus /dev/sda3 /mnt/ipod

Hfsplus partitions which are journalized (read-only)

mount -t hfsplus -o ro /dev/sda3 /mnt/ipod

Common HFS+ kernel error messages

Warning: Journaled HFS+ partitions should be mounted readonly
dmesg | tail -n 1
HFS+-fs: write access to a journaled filesystem is not supported, use the force option at your own risk, mounting read-only.

Recommended solution: disable journaling on the partiton.

Warning: Case-sensitive HFS+ (HFSX) partitions cannot mount
dmesg | tail -n 1
HFS+-fs: unable to find HFS+ superblock.

Recommended solution: Update to 2.6.16 kernel which supports HFSX, but remember the partition may still be journaled; see above.

To check for errors after mounting the drive or at any other time, run the following command.

dmesg | tail -n 1
HFS+-fs warning: Filesystem was not cleanly unmounted, running fsck.hfsplus is recommended. mounting read-only.

Repairing a HFS+ Filesystem using Fsck.hfsplus

The error message, shown at the end of section above, recommends running fsck.hfsplus. This particular tool is not available in any standard PC Linux distribution; however, fsck.hfsplus was installed above. Should the volume be damaged, fsck.hfsplus's output could be similar to the below.


Code: fsck.hfsplus Usage

fsck.hfsplus

fsck.hfsplus: missing special-device
usage: fsck.hfsplus [-dfl m [mode] npqruy] special-device
  d = output debugging info
  f = force fsck even if clean (preen only) 
  l = live fsck (lock down and test-only)
  m arg = octal mode used when creating lost+found directory 
  n = assume a no response 
  p = just fix normal inconsistencies 
  q = quick check returns clean, dirty, or failure 
  r = rebuild catalog btree 
  u = usage 
  y = assume a yes response


Code: Example of a Damaged Volume

fsck.hfsplus /dev/sda3

** /dev/sda3 
** Checking HFS Plus volume.
** Checking Extents Overflow file.
** Checking Catalog file.
Keys out of order 
(4, 1)
** Rebuilding Catalog B-tree.
** Checking HFS Plus volume.
** Checking Extents Overflow file.
** Checking Catalog file.
** Checking Catalog hierarchy.
Invalid directory item count
(It should be 0 instead of 1)
** Checking volume bitmap.
Volume Bit Map needs minor repair
** Checking volume information.
Invalid volume free block count
(It should be 7809542 not 7809541)
** Repairing volume.


Code: Example of a Clean Volume

fsck.hfsplus /dev/sda3

** /dev/sda3
** Checking HFS Plus volume.
** Checking Extents Overflow file.
** Checking Catalog file.
** Checking Catalog hierarchy.
** Checking volume bitmap.
** Checking volume information.
** The volume iPod appears to be OK.

Additional Information Links

Retrieved from "http://www.gentoo-wiki.info/Hfsplus"

Last modified: Thu, 04 Sep 2008 00:08:00 +0000 Hits: 55,027