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