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 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 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.