Subversion Repositories or1k

  Macintosh HFS Filesystem for Linux

  Paul H. Hargrove, hargrove@sccm.Stanford.EDU

  version 0.95, 28 Apr 1997

  This document describes version 0.95 of the Macintosh HFS filesystem

  for Linux.  The most current versions of this document and the

  software are kept at The HFS for Linux Page

  .

  ______________________________________________________________________

  Table of Contents:

  1.      Introduction

  2.      Mounting HFS Filesystems

  2.1.    afpd

  2.2.    case={asis, lower}

  2.3.    conv={auto, binary, text}

  2.4.    creator=cccc

  2.5.    fork={cap, double, netatalk}

  2.6.    gid=n

  2.7.    names={7bit, 8bit, alpha, cap, latin, netatalk, trivial}

  2.8.    part=n

  2.9.    quiet

  2.10.   type=cccc

  2.11.   uid=n

  2.12.   umask=n

  3.      Writing to HFS Filesystems

  3.1.    Writing with fork=cap

  3.2.    Writing with fork=double

  3.3.    Writing with fork=netatalk

  4.      A Guide to Special File Formats

  4.1.    CAP .finderinfo Files

  4.2.    AppleDouble Header Files

  5.      Reporting Bugs

  5.1.    What Goes in a Bug Report

  5.2.    How to Report a Kernel Oops or GPF

  6.      Legal Notices

  6.1.    This Document

  6.2.    The Software

  6.2.1.  The Columbia AppleTalk Package for UNIX

  6.2.2.  Netatalk

  6.3.    Trademarks

  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  This software implements the Macintosh HFS filesystem under Linux.  It

  allows you to read and write HFS filesystems on floppy disks, CDROMs,

  hard drives, ZIP drives, etc.  It is _n_o_t an AppleShare client.

  If you use this software, please send me a note telling of your

  success or failure with it.  Your feedback lets me know that this

  project is not a waste of my time.

  This code is still experimental, so backup anything important before

  you start playing.  I'd like you to know that I've never lost any

  files while using this software, or I would not release it.  However,

  a ``better safe than sorry'' attitude is probably best.

  If, for instance, the buffer cache were to become corrupted you could

  start losing things on other disks.  Because of this, if you get a

  General Protection Fault, or a kernel Oops, I _s_t_r_o_n_g_l_y recommend that

  you reboot before writing any files.

  22..  MMoouunnttiinngg HHFFSS FFiilleessyysstteemmss

  Once you have the HFS filesystem compiled into the kernel or installed

  as a loadable module, you will be able to use hfs as a filesystem type

  option to mount.  For instance, to mount a Macintosh floppy disk on

  the directory /mnt using the default mount options you would execute

  ``mount -t hfs /dev/fd0 /mnt''.

  The remainder of this section describes the several mount options

  available to control how the HFS filesystem is mapped onto a Linux

  filesystem structure.  The values for the multiple-choice options

  (case, conv, fork and names) can be abbreviated by their first

  character.

  22..11..  aaffppdd

  If included in the options, then the behavior of the filesystem is

  changed to make it fully read-write compatible with Netatalk's afpd.

  In this mode you should not use normal user-level tools to modify the

  filesystem, though reading from it is acceptable.  This is because the

  return codes from some system calls are changed to fool afpd.  These

  changes will confuse many user-level tools.  In particular ``rm -r''

  will loop forever.

  This option implies fork=netatalk, which in turn implies

  names=netatalk.  If either of these options are explicitly set to

  something else they will take precedence and will confuse afpd.  The

  quiet option has no effect.  The case= option functions normally, but

  afpd usually does the same thing for you.  The conv= and part= options

  also function normally.

  You will probably want to use the uid=, gid= and umask= mount options.

  Note that because all the files on an HFS filesystem belong to a

  single user and group and have a single umask, the full AppleShare

  permission scheme will not work through Netatalk.

  One additional limitation is that the Desktop database on the disk is

  stored in afpd's format and is separate from any existing database

  maintained by the Finder when the volume is used on a Macintosh.

  Because of this mounting an HFS CDROM across the network to a

  Macintosh may result in applications and documents showing up with

  default application and document icons.  Additionally double clicking

  on a document will fail to start the correct application.  Both of

  these problems can be worked around by copying the application to a

  local disk on the Macintosh.

  This mode is known to be compatible with afpd from Netatalk versions

  1.4b1 and 1.4b2, and known to be incompatible with the afpd from

  version 1.3.3.  As of this writing Netatalk version 1.4 has not yet

  been released.  However, it is expected that this mode will be

  compatible with afpd from Netatalk version 1.4 when it is released.

  22..22..  ccaassee=={{aassiiss,, lloowweerr}}

  default value: asis

  This option determines if Macintosh filenames are presented in their

  original case or in all lowercase.  Filename lookup is always case

  insensitive, so either way foo and Foo refer to the same file but ls

  will list Foo with case=asis, and foo with case=lower.  (Same as for

  the HPFS filesystem.)

     aassiiss

        Filenames are reported in the case they were created with.

     lloowweerr

        Filenames are reported in lowercase.

  22..33..  ccoonnvv=={{aauuttoo,, bbiinnaarryy,, tteexxtt}}

  default value: binary

  This option controls CR<->NL conversion of Macintosh _d_a_t_a _f_o_r_k_s.  Any

  translation takes place only for files accessed with the read() and

  write() system calls (either directly or through the stdio functions).

  Access through mmap() is unaffected.  (Similar to the conv= option for

  the MS-DOS filesystem.)

     aauuttoo

        If the Finder's type for a file is TEXT or ttro, then CR

        characters are converted to NL characters when read, and NL

        characters are converted to CR characters when written.

        Be warned that some Macintosh applications create files with

        type TEXT even though the contents is clearly binary.

     bbiinnaarryy

        No CR<->NL conversion is done.

     tteexxtt

        In all data forks, regardless of the Finder's type for the file,

        CR characters are converted to NL characters when read, and NL

        characters are converted to CR characters when written.

  22..44..  ccrreeaattoorr==cccccccc

  default value: ``????''

  Specifies the 4-character string specifying the Finder's Creator for

  new files.

  22..55..  ffoorrkk=={{ccaapp,, ddoouubbllee,, nneettaattaallkk}}

  default value: cap

  This option determines how resource forks and the Finder's metadata

  are represented within the structure of the Linux filesystem.

     ccaapp

        The scheme used by the Columbia AppleTalk Package's AUFS.

        Associated with each directory are two special directories and a

        metadata file.  The directory ./bar is represented by:

        ..//bbaarr

           The directory itself, containing subdirectories, the data

           forks of files, and the following two special directories.

        ..//bbaarr//..rreessoouurrccee

           A special directory holding resource forks of the files in

           ./bar.

        ..//bbaarr//..ffiinnddeerriinnffoo

           A special directory holding metadata files for the files and

           subdirectories in ./bar.

        ..//..ffiinnddeerriinnffoo//bbaarr

           The metadata file for the directory ./bar.

        The files in a directory are represented as three files:

        ..//ffoooo

           The data fork of the file ./foo.

        ..//..rreessoouurrccee//ffoooo

           The resource fork of the file ./foo.

        ..//..ffiinnddeerriinnffoo//ffoooo

           The metadata file for the file ./foo.

        Additionally, the file .rootinfo in the root directory of the

        HFS filesystem is a metadata file for the root directory.

        Brief documentation on the format of file containing the

        Finder's metadata is included in the section ``A Guide to

        Special File Formats'' in this document.  More detailed

        information is available in the Columbia AppleTalk Package.

     ddoouubbllee

        The ``AppleDouble'' format recommended by Apple.  (Apple's other

        recommended format, ``AppleSingle'', is not yet implemented.)

        Associated with each directory is an AppleDouble ``header

        file''.  The directory ./bar is represented by:

        ..//bbaarr

           The directory itself, containing subdirectories, the data

           forks for files, and the header files for files and

           subdirectories.

        ..//%%bbaarr

           The header file for the directory ./bar, containing the

           Finder's metadata for the directory.

        The files in a directory are represented as two files:

        ..//ffoooo

           The data fork of the file ./foo.

        ..//%%ffoooo

           The header file for the file ./foo, containing the resource

           fork and the Finder's metadata for the file.

        Additionally, the file %RootInfo in the root directory of the

        HFS filesystem is a header file for the root directory.  This is

        not quite the %RootInfo file referred to in the AppleDouble

        specification.

        The header files used in this scheme are version 2 AppleDouble

        header files.  Their format is described briefly in the section

        ``A Guide to Special File Formats'' in this document.  They are

        documented in detail in ``AppleSingle/AppleDouble Formats:

        Developer's Note (9/94)'', available from Apple's Developer

        Services Page .

        Note that the naming convention for the header file can cause

        name conflicts.  For instance, using Apple's 7-bit ASCII name

        conversion (see the names mount option) the name %Desktop could

        be interpreted either as the header file for the file Desktop or

        as the file with 0xDE as the hexadecimal representation of its

        first character, and "sktop" as the remaining 5 characters.  The

        problem arises when both files exist, since only one will be

        accessible.  The behavior of the HFS filesystem in the case of

        such a conflict is undefined, and may change in future releases.

        (If this causes problems for you, please don't report it as a

        bug; I didn't design this ``standard'', Apple did.)

     nneettaattaallkk

        The scheme used by the Netatalk afpd.

        Associated with each directory is a special directory and a

        metadata file.  The directory ./bar is represented by:

        ..//bbaarr

           The directory itself, containing subdirectories, the data

           forks of files, and the following special directory.

        ..//bbaarr//..AApppplleeDDoouubbllee

           A special directory holding AppleDouble header files for

           ./bar and the files it contains, but not for the

           subdirectories it contains.

        ..//bbaarr//..AApppplleeDDoouubbllee//..PPaarreenntt

           The header file for the directory ./bar, containing the

           Finder's metadata for the directory.

        The files in a directory are represented as two files:

        ..//ffoooo

           The data fork of the file ./foo.

        ..//..AApppplleeDDoouubbllee//ffoooo

           The header file for file ./foo, containing the resource fork

           and the Finder's metadata.

        The header files used in this scheme are version 1 AppleDouble

        header files.  They are described briefly in the section ``A

        Guide to Special File Formats'' in this document.  The format is

        documented in detail in the ``Apple II File Type Notes'' under

        the type ``$E0.0002/$E0.0003-AppleDouble'', and in Appendix B of

        the ``A/UX Toolbox: Macintosh ROM Interface'' manual.

  22..66..  ggiidd==nn

  default value: gid of the mounting process

  Specifies the group that owns all files and directories on the

  filesystem.  (Same as for the MS-DOS and HPFS filesystems.)

  22..77..  nnaammeess=={{77bbiitt,, 88bbiitt,, aallpphhaa,, ccaapp,, llaattiinn,, nneettaattaallkk,, ttrriivviiaall}}

  default value: varies as follows

  +o  If the fork option is set to double, then names defaults to alpha.

  +o  If the fork option is set to netatalk, then names defaults to

     netatalk.

  +o  If the fork option is set to cap (or has taken that value by

     default), then names defaults to cap.

  This option determines how to convert between valid Macintosh

  filenames and valid Linux filenames.  The 7bit, 8bit and alpha options

  correspond to Apple's recommended conventions named ``7-bit ASCII'',

  ``8-bit'' and ``7-bit alphanumeric''.

     77bbiitt

        When converting from Macintosh filenames to Linux filenames the

        NULL (0x00), slash (/) and percent (%) characters and the

        extended 8-bit characters (hexadecimal codes 0x80-0xff) are

        replaced by a percent character (%) followed by the two-digit

        hexadecimal code for the character.

        When converting from Linux filenames to Macintosh filenames the

        string "%YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the string "%YZ" is unchanged.  A

        colon (:) is replaced by a pipe character (|).

     88bbiitt

        When converting from Macintosh filenames to Linux filenames the

        NULL (0x00), slash (/) and percent (%) characters are replaced

        by a percent character (%) followed by the two-digit hexadecimal

        code for the character.

        When converting from Linux filenames to Macintosh filenames the

        string "%YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the string "%YZ" is unchanged.  A

        colon (:) is replaced by a pipe character (|).

     aallpphhaa

        When converting from Macintosh filenames to Linux filenames only

        the alphanumeric characters (a-z, A-Z and 0-9), the underscore

        (_) and the last period (.) in the filename are unchanged.  The

        remaining characters are replaced by a percent character (%)

        followed by the two-digit hexadecimal code for the character.

        When converting from Linux filenames to Macintosh filenames the

        string "%YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the string "%YZ" is unchanged.  A

        colon (:) is replaced by a pipe character (|).

     ccaapp

        The convention used by the Columbia AppleTalk Package's AUFS.

        When converting from Macintosh filenames to Linux filenames the

        characters from space ( ) through tilde (~) (ASCII 32-126) are

        unchanged, with the exception of slash (/).  The slash (/) and

        all characters outside the range 32-126 are replaced by a colon

        (:) followed by the two-digit hexadecimal code for the

        character.

        When converting from Linux filenames to Macintosh filenames the

        string ":YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the colon is replaced by a pipe

        character (|).

     llaattiinn

        When converting from Macintosh filenames to Linux filenames the

        characters from space ( ) through tilde (~) (ASCII 32-126) are

        unchanged, with the exception of slash (/) and percent (%).  The

        extended 8-bit Macintosh characters with equivalents in the

        Latin-1 character set are replaced by those equivalents.  The

        remaining characters are replaced by a percent character (%)

        followed by the two-digit hexadecimal code for the character.

        When converting from Linux filenames to Macintosh filenames the

        string "%YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the string "%YZ" is unchanged. The

        Latin-1 characters with equivalents in the extended 8-bit

        Macintosh character set are replaced by those equivalents.  A

        colon (:) is replaced by a pipe character (|).

        Thanks to Holger Schemel (aeglos@valinor.owl.de) for

        contributing this conversion mode.

     nneettaattaallkk

        The convention used by the Netatalk afpd.

        When converting from Macintosh filenames to Linux filenames the

        characters from space ( ) through tilde (~) (ASCII 32-126) are

        unchanged, with the exception of slash (/) and any initial

        period (.).  The slash (/) and any initial period (.)  and all

        characters outside the range 32-126 are replaced by a colon (:)

        followed by the two-digit hexadecimal code for the character.

        When converting from Linux filenames to Macintosh filenames the

        string ":YZ" is replaced by the character with hexadecimal code

        0xYZ.  If 0xYZ is not a valid hexadecimal number or is the code

        for NULL or colon (:) then the colon is replaced by a pipe

        character (|).

     ttrriivviiaall

        When converting from Macintosh filenames to Linux filenames a

        slash character (/) is replaced by a colon (:).

        When converting from Linux filenames to Macintosh filenames a

        colon (:) is replaced by a slash character (/).

  22..88..  ppaarrtt==nn

  default value: 0

  Specifies which HFS partition to mount from a Macintosh CDROM or hard

  drive.  Partitions are numbered from 0 and count only those identified

  in the partition table as containing HFS filesystems.  This option is

  only useful when the Linux platform doesn't fully support Macintosh

  partition tables.  In particular on MkLinux and Linux-Pmac this option

  is useless.

  Note that in versions before 0.8.3 partitions were numbered from 1.

  22..99..  qquuiieett

  If included in the options, then chown and chmod operations will not

  return errors, but will instead fail silently.  (Same as for the MS-

  DOS and HPFS filesystems.)

  22..1100..  ttyyppee==cccccccc

  default value: ``????''

  Specifies the 4-character string specifying the Finder's Type for new

  files.

  22..1111..  uuiidd==nn

  default value: uid of the mounting process

  Specifies the user that owns all files and directories on the

  filesystem.  (Same as for the MS-DOS and HPFS filesystems.)

  22..1122..  uummaasskk==nn

  default value: umask of the mounting process

  Specifies (in octal) the umask used for all files and directories.

  (Same as for the MS-DOS and HPFS filesystems.)

  33..  WWrriittiinngg ttoo HHFFSS FFiilleessyysstteemmss

  Each of the values of the fork mount option yields a different

  representation of the Macintosh-specific parts of a file within the

  structure of the Linux filesystem.  There are, therefore, slightly

  different steps involved in copying files if you want to preserve the

  resource forks and the Finder's metadata.

  It is important to remember not to use normal user-level tools to

  modify a filesystem mounted with the afpd mount option.

  Regardless of the value of the fork mount option you can do virtually

  everything to the data fork of a file that you can to a file on any

  other filesystem.  The limitations are essentially the same as those

  imposed by the MS-DOS filesystem:

  +o  You can't change the uid or gid of files.

  +o  You can't set the set-uid, set-gid or sticky permission bits.

  +o  You can't clear the execute permission bits.

  Likewise you can do virtually everything to a directory that you can

  to a directory on another file system with the following exceptions:

  +o  You can't create, delete or rename resource forks of files or the

     Finder's metadata.  Note, however, that they are created (with

     defaults values), deleted and renamed along with the corresponding

     data fork or directory.

  +o  You can't change permissions on directories.

  +o  You can't change the uid or gid of directories.

  +o  You can't create multiple links to files.

  +o  You can't create symlinks, device files, sockets or FIFOs.

  33..11..  WWrriittiinngg wwiitthh ffoorrkk==ccaapp

  Unlike the other schemes for representing forked files, the CAP scheme

  presents the resource fork as an independent file; the resource fork

  of ./foo is ./.resource/foo.  Therefore, you can treat it as a normal

  file.  You can do anything to a resource fork that you can do to a

  data fork, except that you cannot enable execute permissions on a

  resource fork.  Therefore, resource forks are not suitable for holding

  Linux executables or shared libraries.

  If you plan to use the resource fork on a Macintosh then you must obey

  the format of a valid resource fork.  This format is documented in

  Chapter 1 of Apple's _I_n_s_i_d_e _M_a_c_i_n_t_o_s_h_: _M_o_r_e _M_a_c_i_n_t_o_s_h _T_o_o_l_b_o_x.  The

  filesystem knows nothing about this format and so does nothing to

  enforce it.

  The current support for reading and writing is sufficient to allow

  copying of entire directories with tar, as long as both the source and

  destination are mounted with fork=cap.  tar may complain about being

  unable to change the uid, gid or mode of files.  This is normal and is

  an unavoidable side effect of the having a single uid, gid and umask

  for the entire filesystem.

  It is impossible to create a resource fork or a Finder metadata file.

  However, they are created automatically when the data fork is created.

  Therefore, if you wish to copy a single file including both forks and

  the Finder's metadata then you must create the data fork first.  Then

  you can copy the resource fork and the Finder's metadata.  For

  instance to copy the file foo to dir/bar you should do the following:

  1. cp foo dir/bar

  2. cp .resource/foo dir/.resource/bar

  3. cp .finderinfo/foo dir/.finderinfo/bar

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  If you wish to move foo to dir/bar and foo and dir are on the same

  filesystem then you only need to execute ``mv foo dir/bar'' and the

  resource fork and the Finder's metadata will move too.  However, if

  foo and dir are on different filesystem then this will lose the

  resource fork and metadata.  Therefore, it is safest to always move

  files as follows:

  1. cp foo dir/bar

  2. cp .resource/foo dir/.resource/bar

  3. cp .finderinfo/foo dir/.finderinfo/bar

  4. rm foo

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  Directories have no resource fork but you may wish to create a

  directory which has the same location and view on the Finder's screen

  as an existing one.  This can be done by copying the Finder metadata

  file.  To give the directory bar the same location, layout, creation

  date and modify date as foo you simply execute ``cp .finderinfo/foo

  .finderinfo/bar''.

  When copying an entire directory with ``cp -R'' you may also wish to

  copy the metadata for the directory:

  1. cp -R foo bar

  2. cp .finderinfo/foo .finderinfo/bar

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.

  33..22..  WWrriittiinngg wwiitthh ffoorrkk==ddoouubbllee

  The current support for reading and writing header files is sufficient

  to allow copying of entire directories with tar, as long as both the

  source and destination are mounted with fork=double.  tar may complain

  about being unable to change the uid, gid or mode of files.  This is

  normal and is an unavoidable side effect of the having a single uid,

  gid and umask for the entire filesystem.

  It is impossible to create a header file.  However, they are created

  automatically when the data fork is created.  Therefore, if you wish

  to copy a single file including both forks and the Finder's metadata

  then you must create the data fork first.  Then you can copy the

  header file.  instance to copy the file foo to dir/bar you should do

  the following:

  1. cp foo dir/bar

  2. cp %foo dir/%bar

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  If you wish to move foo to dir/bar and foo and dir are on the same

  filesystem then you only need to execute ``mv foo dir/bar'' and the

  header file will move too.  However, if foo and dir are on different

  filesystem then this will lose the header file.  Therefore, it is

  safest to always move files as follows:

  1. cp foo dir/bar

  2. cp %foo dir/%bar

  3. rm foo

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  Directories have no resource fork but you may wish to create a

  directory which has the same location and view on the Finder's screen

  as an existing one.  This can be done by copying the corresponding

  header file.  To give the directory bar the same location, layout,

  creation date and modify date as foo simply execute ``cp %foo %bar''.

  When copying an entire directory with ``cp -R'' you may also wish to

  copy the header file for the directory as well:

  1. cp -R foo bar

  2. cp %foo %bar

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.

  33..33..  WWrriittiinngg wwiitthh ffoorrkk==nneettaattaallkk

  The current support for reading and writing header files is sufficient

  to allow copying of entire directories with tar, as long as both the

  source and destination are mounted fork=netatalk.  tar may complain

  about being unable to change the uid, gid or mode of files.  This is

  normal and is an unavoidable side effect of the having a single uid,

  gid and umask for the entire filesystem.

  It is impossible to create a header file.  However, they are created

  automatically when the data fork is created.  Therefore, if you wish

  to copy a single file including both forks and the Finder's metadata

  then you must create the data fork first.  Then you can copy the

  header file.  instance to copy the file foo to dir/bar you should do

  the following:

  1. cp foo dir/bar

  2. cp .AppleDouble/foo dir/.AppleDouble/bar

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  If you wish to move foo to dir/bar and foo and dir are on the same

  filesystem then you only need to execute ``mv foo dir/bar'' and the

  header file will move too.  However, if foo and dir are on different

  filesystem then this will lose the header file.  Therefore, it is

  safest to always move files as follows:

  1. cp foo dir/bar

  2. cp .AppleDouble/foo dir/.AppleDouble/bar

  3. rm foo

  You may get ``Operation not permitted'' errors from cp when it tries

  to change the permissions on files.  These errors can safely be

  ignored.  This method will work even if the file dir/bar exists.

  Directories have no resource fork but you may wish to create a

  directory which has the same location and view on the Finder's screen

  as an existing one.  This can be done by copying the corresponding

  header file.  To give the directory bar the same location, layout,

  creation date and modify date as foo you simply execute ``cp

  foo/.AppleDouble/.Parent bar/.AppleDouble/.Parent''.

  Because the fork=netatalk scheme holds the header file for a directory

  within that directory, directories can safely be copied with ``cp -R

  foo bar'' with no loss of information.  However, you may get

  ``Operation not permitted'' errors from cp when it tries to change the

  permissions on files.  These errors can safely be ignored.

  44..  AA GGuuiiddee ttoo SSppeecciiaall FFiillee FFoorrmmaattss

  Each of the values of the fork mount option yields different special

  files to represent the Macintosh-specific parts of a file within the

  structure of the Linux filesystem.  You can write to these special

  files to change things such as the Creator and Type of a file.

  However, to do so safely you must follow certain rules to avoid

  corrupting the data.  Additionally, there are certain fields in the

  special files that you can't change (writes to them will fail

  silently).

  44..11..  CCAAPP ..ffiinnddeerriinnffoo FFiilleess

  The Finder's metadata for the file ./foo in held in the file

  ./.finderinfo/foo.  The file has a fixed format defined in hfs_fs.h as

  follows:

       ______________________________________________________________________

       struct hfs_cap_info {

               __u8    fi_fndr[32];            /* Finder's info */

               __u16   fi_attr;                /* AFP attributes */

               __u8    fi_magic1;              /* Magic number: */

       #define HFS_CAP_MAGIC1          0xFF

               __u8    fi_version;             /* Version of this structure: */

       #define HFS_CAP_VERSION         0x10

               __u8    fi_magic;               /* Another magic number: */

       #define HFS_CAP_MAGIC           0xDA

               __u8    fi_bitmap;              /* Bitmap of which names are valid: */

       #define HFS_CAP_SHORTNAME       0x01

       #define HFS_CAP_LONGNAME        0x02

               __u8    fi_shortfilename[12+1]; /* "short name" (unused) */

               __u8    fi_macfilename[32+1];   /* Original (Macintosh) name */

               __u8    fi_comln;               /* Length of comment (always 0) */

               __u8    fi_comnt[200];          /* Finder comment (unused) */

               /* optional:    used by aufs only if compiled with USE_MAC_DATES */

               __u8    fi_datemagic;           /* Magic number for dates extension: */

       #define HFS_CAP_DMAGIC          0xDA

               __u8    fi_datevalid;           /* Bitmap of which dates are valid: */

       #define HFS_CAP_MDATE           0x01

       #define HFS_CAP_CDATE           0x02

               __u8    fi_ctime[4];            /* Creation date (in AFP format) */

               __u8    fi_mtime[4];            /* Modify date (in AFP format) */

               __u8    fi_utime[4];            /* Un*x time of last mtime change */

       };

       ______________________________________________________________________

  The type __u8 is an unsigned character, and __u16 is an unsigned

  16-bit integer.

  Currently only the fields fi_fndr, fi_attr, fi_ctime and fi_mtime can

  be changed.  Writes to the other fields are silently ignored.

  However, you shouldn't write random bytes to the other fields, since

  they may be writable in the future.

  The fi_fndr field is the ``Finder info'' and ``Extended Finder info''

  for a file or directory.  These structures are described in various

  books on Macintosh programming.  The portion of the most interest is

  probably the first 8 bytes which, for a file, give the 4-byte Type

  followed by the 4-byte Creator.

  The fi_attr field is the AFP attributes of the file or directory.

  While you can write any value to this field, only the ``write-

  inhibit'' bit is significant.  Setting or clearing this bit will clear

  or set the write bits in the file's permissions.  When you read from

  this field anything you may have written is lost.  If the file has

  write permissions enabled then you will read zero from this field.

  With write permission disabled you will read back 0x01 0xA0, which

  corresponds to setting the ``write-inhibit'', ``rename-inhibit'' and

  ``delete-inhibit'' bits.

  The fi_ctime and fi_mtime are the Macintosh created and modified time

  for the file or directory, and are 32-bit signed integers in network

  byteorder giving seconds from 00:00 GMT Jan. 1, 2000.

  44..22..  AApppplleeDDoouubbllee HHeeaaddeerr FFiilleess

  Both the fork=double and fork=netatalk schemes for representing forked

  files use AppleDouble header files to contain the resource fork and

  the Finder's metadata together in a single file.

  The AppleDouble format specifies a fixed-format header which describes

  which fields are contained in the remainder of the file, where they

  are located in the file and how long they are.  A full description of

  the version 1 format used when fork=netatalk is available from ??????.

  The version 2 format used when fork=double is documented in ??????.

  The discussion that follows assumes you have read and understood these

  documents, which may be difficult until I've replaced the ``??????''s

  above with something more informative :-).

  Due to the variable structure of an AppleDouble header file you must

  not use buffered I/O when reading or writing them; you should only use

  the read() and write() system calls.  It is also important that you

  make some effort to coordinate processes that are reading and writing

  the same header file, since a reader will receive the wrong data if

  the location of a given entry has changed since it read the descriptor

  for the entry.  If a process tries to read the descriptor table while

  it is changing then it is possible to read totally meaningless data.

  When a header file is opened it is initially presented with a default

  header layout.  You may write to the header to change the layout, but

  when all file descriptors for the file or directory have been closed

  the change in format is lost and subsequent opens will yield the

  default layout.  Changes to supported entries are made directly to the

  filesystem and are thus preserved when the file is closed and

  reopened.

  The HFS filesystem currently uses a fixed-size table to hold the

  descriptors.  Therefore you are limited to HFS_HDR_MAX (currently 10)

  descriptors.  In the unlikely event that you try to write a header

  with more descriptors, a warning will be issued by the kernel, and

  extra descriptors will be ignored.  This should be considered a bug

  and will hopefully change sooner rather than later.

  The results of specifying overlapping entries is undefined and should

  not be relied upon to remain unchanged from one version of the HFS

  filesystem to the next.  There is no valid reason to define

  overlapping entries, so just don't do it!

  Changes to the magic number and version fields are preserved until all

  file descriptors are closed, however the only significance given to

  them internally is that the 16 bytes following the version changes

  meaning according to the version.  For version 1 header files these 16

  bytes contain the string ``Macintosh'' followed by 7 spaces.  For any

  other value of the version field these 16 bytes are all zeros.  In

  either case writes to these 16 bytes are silently ignored.

  Since the magic number and version are given no other significance

  internally, you are free to do many things that violate the official

  formats.  For instance you can create an entry for the data fork in a

  header file with an AppleDouble magic number or create ``File Info''

  (id=7) entries in version 2 header files and ``File Dates Info''

  (id=8) entries in version 1 header files.  However, future versions of

  the filesystem may enforce the format more strictly.

  Entry id 1 (``Data Fork'') is read-only.  You should use the data file

  to modify the data fork.  The data fork is, of course, not supported

  for directories.

  Entry ids 2, 7, 8, 9 and 10 (``Resource Fork'', ``File Info'', ``File

  Dates Info'', ``Finder Info'' and ``Macintosh File Info'') are fully

  supported, meaning that their contents may be read and written and

  that data written is preserved when the file is closed and reopened.

  The resource fork is, of course, not supported for directories.

  Entry id 7 specifies some of the same data given by ids 8 and 10.  If

  you create a header file with an entry for id 7 and for ids 8 or 10,

  then the behavior with respect to their interaction is undefined.  A

  header that contains an entry for id 7 and for ids 8 or 10 is not

  valid as either a version 1 or a version 2 header file, so there is no

  reason to do this and future versions may prevent it.

  Entry id 3 (``Real Name'') is read-only, since it will change

  automatically when a file is renamed.  Writes to the corresponding

  entry are silently ignored.

  All other entry ids are ignored.  You may create descriptors for them;

  in fact the default header layout when fork=netatalk includes a

  descriptor for id 4 (``Comment'').  However writes to the entries

  corresponding to the ignored ids fail silently and reads from the

  entries always return zeros.  However, you shouldn't write random

  bytes to unsupported entries, since they may be supported in the

  future.

  All of the supported entry types except the data and resource forks

  have a fixed length.  If you give them a smaller length in the

  descriptor then you are unable to access part of the corresponding

  entry.  If you give them a larger length in the descriptor, then the

  corresponding entry is padded with zeros and writes to the extra space

  are silently ignored.

  Writes to the length field of descriptors for the data and resource

  forks will cause the corresponding fork to grow (with zero padding) or

  shrink to the indicated length.

  If you have an entry for the data fork then the descriptor's length

  field does not change automatically to reflect any modification of the

  data fork directly (the data does change however).  If the data fork

  is longer than the descriptor indicates, then a portion of it is

  inaccessible.  If the data fork is shorter than the descriptor

  indicates then reads will be padded with zeros.

  Writes beyond the end of the resource fork that extend into empty

  space between entries or beyond the end of the file will extend the

  fork, automatically changing the length field of the corresponding

  descriptor.  Writes to any other space between entries are silently

  ignored and read of such spaces always return zeros.

  Calling truncate() on a header file can change the length of the

  resource fork and such a change will automatically be reflected in the

  length field of the corresponding descriptor.  If truncate() shortens

  the file so that the entry for the resource fork would extend beyond

  the new end of the file then the fork is shortened to fit in the space

  that remains, or to zero bytes if the entry is now entirely beyond the

  end of the file.  If the last entry in a header file is the resource

  fork then a call to truncate() that extends the header file will

  extend the fork with zeros.  Note that this happens even if there was

  previously space between the end of the fork and the end of the file.

  55..  RReeppoorrttiinngg BBuuggss

  If you'd like any problems you encounter fixed, you'll need to provide

  a detailed bug report.  However, you should check the FAQ (available

  from the HFS for Linux Page )

  first to be certain that your problem is not a known limitation of the

  filesystem.  If your bug doesn't appear in the FAQ then you should e-mail

  me at hargrove@sccm.Stanford.EDU.

  55..11..  WWhhaatt GGooeess iinn aa BBuugg RReeppoorrtt

  When writing your bug report, include any facts you think might be

  relevant; I'd much rather have a bunch of extra facts than need to

  e-mail you to get the information.  At a minimum the following

  information should be included:

  +o  The version of the HFS filesystem you are using (see

     linux/fs/hfs/version.h).

  +o  The kernel version you are using.

  +o  Any unofficial kernel patches or loadable modules you are using.

  +o  If you are loading the HFS filesystem as a module, then version of

     the module utilities used to load hfs.o.

  +o  The type of media you are working with (floppy, CDROM, ZIP Drive,

     etc.).

  +o  The steps required to reproduce the bug, including mount options