Linux Cross Reference
Linux/fs/hfs/HFS.txt

     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
     <http://www-sccm.Stanford.EDU/~hargrove/HFS/>.
     ______________________________________________________________________
  
    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 <http://devworld.apple.com>.
 
         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 <http://www-sccm.Stanford.EDU/~hargrove/HFS/>)
   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
      used.  (If you can't reproduce the bug tell me everything you did
      the one time it did occur, but be warned that non-reproducible bugs
      can only rarely be fixed.)
 
   55..22..  HHooww ttoo RReeppoorrtt aa KKeerrnneell OOooppss oorr GGPPFF
 
   If you encounter a bug that causes a kernel Oops or a General
   Protection Fault then you'll need to collect some additional
   information for the bug report.  If you are loading the HFS filesystem
   as a module, then is important that you do this before rebooting,
   since the module is unlikely to be loaded at the same address after
   the reboot.
 
   You should include all the information that the kernel prints to the
   console or to the system logs.  However, the EIP and Stack Trace are
   addresses in _y_o_u_r kernel and mean nothing to me without more
   information.  Using your System.map file (or either ksymoops or klogd)
   determine which functions the EIP and Stack Trace are in.  If you do
   this by hand using your System.map file then the correct symbol is the
   one of type t or T with the largest address less than or equal to the
   one you are resolving.
 
   If you are loading the HFS filesystem as a module and the Oops or GPF
   was in the HFS code then the EIP and the top levels of the Stack Trace
   will be in a loadable module, rather than in the kernel proper.  So,
   their symbols will not be in the file System.map.  Therefore, you will
   need to use /proc/ksyms, or a loadmap produced by passing the -m
   option to insmod, to locate those symbols.
 
   66..  LLeeggaall NNoottiicceess
 
   66..11..  TThhiiss DDooccuummeenntt
 
   This document is Copyright (c) 1996, 1997 by Paul H. Hargrove.
 
   Permission is granted to make and distribute verbatim copies of this
   document provided the copyright notice and this permission notice are
   preserved on all copies.
 
   Permission is granted to copy and distribute modified versions of this
   document under the conditions for verbatim copies above, provided a
   notice clearly stating that the document is a modified version is also
   included in the modified document.
 
   Permission is granted to copy and distribute translations of this
   document into another language, under the conditions specified above
   for modified versions.
 
   Permission is granted to convert this document into another media
   under the conditions specified above for modified versions provided
   the requirement to acknowledge the source document is fulfilled by
   inclusion of an obvious reference to the source document in the new
   media. Where there is any doubt as to what defines ``obvious'' the
   copyright owner reserves the right to decide.
 
   66..22..  TThhee SSooffttwwaarree
 
   The HFS filesystem for Linux is Copyright (c) 1994-1997 by Paul H.
   Hargrove.
 
   This software is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.
 
   This software is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.
 
   You should have received a copy of the GNU General Public License
   along with this software in the file ``COPYING''; if not, write to the
   Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
   USA.
 
   66..22..11..  TThhee CCoolluummbbiiaa AApppplleeTTaallkk PPaacckkaaggee ffoorr UUNNIIXX
 
   The source code distribution of the Columbia AppleTalk Package for
   UNIX, version 6.0, (CAP) was used as a _s_p_e_c_i_f_i_c_a_t_i_o_n of the location
   and format of files used by CAP's Aufs.  No code from CAP appears in
   the HFS filesystem. The HFS filesystem is not a work ``derived'' from
   CAP in the sense of intellectual property law.
 
   66..22..22..  NNeettaattaallkk
 
   The source code distributions of Netatalk, versions 1.3.3b2 and 1.4b2,
   were used as a _s_p_e_c_i_f_i_c_a_t_i_o_n of the location and format of files used
   by Netatalk's afpd.  No code from Netatalk appears in the HFS
   filesystem.  The HFS filesystem is not a work ``derived'' from
   Netatalk in the sense of intellectual property law.
 
   66..33..  TTrraaddeemmaarrkkss
 
   +o  ``Finder'' is a trademarks of Apple Computer, Inc.
 
   +o  ``Apple'', ``AppleShare'', ``AppleTalk'' and ``Macintosh'' are
      registered trademarks of Apple Computer, Inc.
 
   +o  ``Microsoft'' and ``MS-DOS'' are registered trademarks of Microsoft
      Corporation.
 
   +o  All other trademarks are the property of their respective owners.