1 Macintosh HFS Filesystem for Linux
2 Paul H. Hargrove, hargrove@sccm.Stanford.EDU
3 version 0.95, 28 Apr 1997
5 This document describes version 0.95 of the Macintosh HFS filesystem
6 for Linux. The most current versions of this document and the
7 software are kept at The HFS for Linux Page
8 <http://www-sccm.Stanford.EDU/~hargrove/HFS/>.
9 ______________________________________________________________________
15 2. Mounting HFS Filesystems
19 2.2. case={asis, lower}
21 2.3. conv={auto, binary, text}
25 2.5. fork={cap, double, netatalk}
29 2.7. names={7bit, 8bit, alpha, cap, latin, netatalk, trivial}
41 3. Writing to HFS Filesystems
43 3.1. Writing with fork=cap
45 3.2. Writing with fork=double
47 3.3. Writing with fork=netatalk
49 4. A Guide to Special File Formats
51 4.1. CAP .finderinfo Files
53 4.2. AppleDouble Header Files
57 5.1. What Goes in a Bug Report
59 5.2. How to Report a Kernel Oops or GPF
67 6.2.1. The Columbia AppleTalk Package for UNIX
72 ______________________________________________________________________
74 1
\b1.
\b. I
\bIn
\bnt
\btr
\bro
\bod
\bdu
\buc
\bct
\bti
\bio
\bon
\bn
76 This software implements the Macintosh HFS filesystem under Linux. It
77 allows you to read and write HFS filesystems on floppy disks, CDROMs,
78 hard drives, ZIP drives, etc. It is _
\bn_
\bo_
\bt an AppleShare client.
80 If you use this software, please send me a note telling of your
81 success or failure with it. Your feedback lets me know that this
82 project is not a waste of my time.
84 This code is still experimental, so backup anything important before
85 you start playing. I'd like you to know that I've never lost any
86 files while using this software, or I would not release it. However,
87 a ``better safe than sorry'' attitude is probably best.
89 If, for instance, the buffer cache were to become corrupted you could
90 start losing things on other disks. Because of this, if you get a
91 General Protection Fault, or a kernel Oops, I _
\bs_
\bt_
\br_
\bo_
\bn_
\bg_
\bl_
\by recommend that
92 you reboot before writing any files.
94 2
\b2.
\b. M
\bMo
\bou
\bun
\bnt
\bti
\bin
\bng
\bg H
\bHF
\bFS
\bS F
\bFi
\bil
\ble
\bes
\bsy
\bys
\bst
\bte
\bem
\bms
\bs
96 Once you have the HFS filesystem compiled into the kernel or installed
97 as a loadable module, you will be able to use hfs as a filesystem type
98 option to mount. For instance, to mount a Macintosh floppy disk on
99 the directory /mnt using the default mount options you would execute
100 ``mount -t hfs /dev/fd0 /mnt''.
102 The remainder of this section describes the several mount options
103 available to control how the HFS filesystem is mapped onto a Linux
104 filesystem structure. The values for the multiple-choice options
105 (case, conv, fork and names) can be abbreviated by their first
108 2
\b2.
\b.1
\b1.
\b. a
\baf
\bfp
\bpd
\bd
110 If included in the options, then the behavior of the filesystem is
111 changed to make it fully read-write compatible with Netatalk's afpd.
112 In this mode you should not use normal user-level tools to modify the
113 filesystem, though reading from it is acceptable. This is because the
114 return codes from some system calls are changed to fool afpd. These
115 changes will confuse many user-level tools. In particular ``rm -r''
118 This option implies fork=netatalk, which in turn implies
119 names=netatalk. If either of these options are explicitly set to
120 something else they will take precedence and will confuse afpd. The
121 quiet option has no effect. The case= option functions normally, but
122 afpd usually does the same thing for you. The conv= and part= options
123 also function normally.
125 You will probably want to use the uid=, gid= and umask= mount options.
126 Note that because all the files on an HFS filesystem belong to a
127 single user and group and have a single umask, the full AppleShare
128 permission scheme will not work through Netatalk.
130 One additional limitation is that the Desktop database on the disk is
131 stored in afpd's format and is separate from any existing database
132 maintained by the Finder when the volume is used on a Macintosh.
133 Because of this mounting an HFS CDROM across the network to a
134 Macintosh may result in applications and documents showing up with
135 default application and document icons. Additionally double clicking
136 on a document will fail to start the correct application. Both of
137 these problems can be worked around by copying the application to a
138 local disk on the Macintosh.
140 This mode is known to be compatible with afpd from Netatalk versions
141 1.4b1 and 1.4b2, and known to be incompatible with the afpd from
142 version 1.3.3. As of this writing Netatalk version 1.4 has not yet
143 been released. However, it is expected that this mode will be
144 compatible with afpd from Netatalk version 1.4 when it is released.
146 2
\b2.
\b.2
\b2.
\b. c
\bca
\bas
\bse
\be=
\b={
\b{a
\bas
\bsi
\bis
\bs,
\b, l
\blo
\bow
\bwe
\ber
\br}
\b}
150 This option determines if Macintosh filenames are presented in their
151 original case or in all lowercase. Filename lookup is always case
152 insensitive, so either way foo and Foo refer to the same file but ls
153 will list Foo with case=asis, and foo with case=lower. (Same as for
154 the HPFS filesystem.)
157 Filenames are reported in the case they were created with.
160 Filenames are reported in lowercase.
162 2
\b2.
\b.3
\b3.
\b. c
\bco
\bon
\bnv
\bv=
\b={
\b{a
\bau
\but
\bto
\bo,
\b, b
\bbi
\bin
\bna
\bar
\bry
\by,
\b, t
\bte
\bex
\bxt
\bt}
\b}
164 default value: binary
166 This option controls CR<->NL conversion of Macintosh _
\bd_
\ba_
\bt_
\ba _
\bf_
\bo_
\br_
\bk_
\bs. Any
167 translation takes place only for files accessed with the read() and
168 write() system calls (either directly or through the stdio functions).
169 Access through mmap() is unaffected. (Similar to the conv= option for
170 the MS-DOS filesystem.)
173 If the Finder's type for a file is TEXT or ttro, then CR
174 characters are converted to NL characters when read, and NL
175 characters are converted to CR characters when written.
177 Be warned that some Macintosh applications create files with
178 type TEXT even though the contents is clearly binary.
180 b
\bbi
\bin
\bna
\bar
\bry
\by
181 No CR<->NL conversion is done.
184 In all data forks, regardless of the Finder's type for the file,
185 CR characters are converted to NL characters when read, and NL
186 characters are converted to CR characters when written.
188 2
\b2.
\b.4
\b4.
\b. c
\bcr
\bre
\bea
\bat
\bto
\bor
\br=
\b=c
\bcc
\bcc
\bcc
\bc
190 default value: ``????''
192 Specifies the 4-character string specifying the Finder's Creator for
195 2
\b2.
\b.5
\b5.
\b. f
\bfo
\bor
\brk
\bk=
\b={
\b{c
\bca
\bap
\bp,
\b, d
\bdo
\bou
\bub
\bbl
\ble
\be,
\b, n
\bne
\bet
\bta
\bat
\bta
\bal
\blk
\bk}
\b}
199 This option determines how resource forks and the Finder's metadata
200 are represented within the structure of the Linux filesystem.
203 The scheme used by the Columbia AppleTalk Package's AUFS.
205 Associated with each directory are two special directories and a
206 metadata file. The directory ./bar is represented by:
209 The directory itself, containing subdirectories, the data
210 forks of files, and the following two special directories.
212 .
\b./
\b/b
\bba
\bar
\br/
\b/.
\b.r
\bre
\bes
\bso
\bou
\bur
\brc
\bce
\be
213 A special directory holding resource forks of the files in
216 .
\b./
\b/b
\bba
\bar
\br/
\b/.
\b.f
\bfi
\bin
\bnd
\bde
\ber
\bri
\bin
\bnf
\bfo
\bo
217 A special directory holding metadata files for the files and
218 subdirectories in ./bar.
220 .
\b./
\b/.
\b.f
\bfi
\bin
\bnd
\bde
\ber
\bri
\bin
\bnf
\bfo
\bo/
\b/b
\bba
\bar
\br
221 The metadata file for the directory ./bar.
223 The files in a directory are represented as three files:
226 The data fork of the file ./foo.
228 .
\b./
\b/.
\b.r
\bre
\bes
\bso
\bou
\bur
\brc
\bce
\be/
\b/f
\bfo
\boo
\bo
229 The resource fork of the file ./foo.
231 .
\b./
\b/.
\b.f
\bfi
\bin
\bnd
\bde
\ber
\bri
\bin
\bnf
\bfo
\bo/
\b/f
\bfo
\boo
\bo
232 The metadata file for the file ./foo.
234 Additionally, the file .rootinfo in the root directory of the
235 HFS filesystem is a metadata file for the root directory.
237 Brief documentation on the format of file containing the
238 Finder's metadata is included in the section ``A Guide to
239 Special File Formats'' in this document. More detailed
240 information is available in the Columbia AppleTalk Package.
242 d
\bdo
\bou
\bub
\bbl
\ble
\be
243 The ``AppleDouble'' format recommended by Apple. (Apple's other
244 recommended format, ``AppleSingle'', is not yet implemented.)
246 Associated with each directory is an AppleDouble ``header
247 file''. The directory ./bar is represented by:
250 The directory itself, containing subdirectories, the data
251 forks for files, and the header files for files and
254 .
\b./
\b/%
\b%b
\bba
\bar
\br
255 The header file for the directory ./bar, containing the
256 Finder's metadata for the directory.
258 The files in a directory are represented as two files:
261 The data fork of the file ./foo.
263 .
\b./
\b/%
\b%f
\bfo
\boo
\bo
264 The header file for the file ./foo, containing the resource
265 fork and the Finder's metadata for the file.
267 Additionally, the file %RootInfo in the root directory of the
268 HFS filesystem is a header file for the root directory. This is
269 not quite the %RootInfo file referred to in the AppleDouble
272 The header files used in this scheme are version 2 AppleDouble
273 header files. Their format is described briefly in the section
274 ``A Guide to Special File Formats'' in this document. They are
275 documented in detail in ``AppleSingle/AppleDouble Formats:
276 Developer's Note (9/94)'', available from Apple's Developer
277 Services Page <http://devworld.apple.com>.
279 Note that the naming convention for the header file can cause
280 name conflicts. For instance, using Apple's 7-bit ASCII name
281 conversion (see the names mount option) the name %Desktop could
282 be interpreted either as the header file for the file Desktop or
283 as the file with 0xDE as the hexadecimal representation of its
284 first character, and "sktop" as the remaining 5 characters. The
285 problem arises when both files exist, since only one will be
286 accessible. The behavior of the HFS filesystem in the case of
287 such a conflict is undefined, and may change in future releases.
288 (If this causes problems for you, please don't report it as a
289 bug; I didn't design this ``standard'', Apple did.)
291 n
\bne
\bet
\bta
\bat
\bta
\bal
\blk
\bk
292 The scheme used by the Netatalk afpd.
294 Associated with each directory is a special directory and a
295 metadata file. The directory ./bar is represented by:
298 The directory itself, containing subdirectories, the data
299 forks of files, and the following special directory.
301 .
\b./
\b/b
\bba
\bar
\br/
\b/.
\b.A
\bAp
\bpp
\bpl
\ble
\beD
\bDo
\bou
\bub
\bbl
\ble
\be
302 A special directory holding AppleDouble header files for
303 ./bar and the files it contains, but not for the
304 subdirectories it contains.
306 .
\b./
\b/b
\bba
\bar
\br/
\b/.
\b.A
\bAp
\bpp
\bpl
\ble
\beD
\bDo
\bou
\bub
\bbl
\ble
\be/
\b/.
\b.P
\bPa
\bar
\bre
\ben
\bnt
\bt
307 The header file for the directory ./bar, containing the
308 Finder's metadata for the directory.
310 The files in a directory are represented as two files:
313 The data fork of the file ./foo.
315 .
\b./
\b/.
\b.A
\bAp
\bpp
\bpl
\ble
\beD
\bDo
\bou
\bub
\bbl
\ble
\be/
\b/f
\bfo
\boo
\bo
316 The header file for file ./foo, containing the resource fork
317 and the Finder's metadata.
319 The header files used in this scheme are version 1 AppleDouble
320 header files. They are described briefly in the section ``A
321 Guide to Special File Formats'' in this document. The format is
322 documented in detail in the ``Apple II File Type Notes'' under
323 the type ``$E0.0002/$E0.0003-AppleDouble'', and in Appendix B of
324 the ``A/UX Toolbox: Macintosh ROM Interface'' manual.
326 2
\b2.
\b.6
\b6.
\b. g
\bgi
\bid
\bd=
\b=n
\bn
328 default value: gid of the mounting process
330 Specifies the group that owns all files and directories on the
331 filesystem. (Same as for the MS-DOS and HPFS filesystems.)
333 2
\b2.
\b.7
\b7.
\b. n
\bna
\bam
\bme
\bes
\bs=
\b={
\b{7
\b7b
\bbi
\bit
\bt,
\b, 8
\b8b
\bbi
\bit
\bt,
\b, a
\bal
\blp
\bph
\bha
\ba,
\b, c
\bca
\bap
\bp,
\b, l
\bla
\bat
\bti
\bin
\bn,
\b, n
\bne
\bet
\bta
\bat
\bta
\bal
\blk
\bk,
\b, t
\btr
\bri
\biv
\bvi
\bia
\bal
\bl}
\b}
335 default value: varies as follows
337 +
\bo If the fork option is set to double, then names defaults to alpha.
339 +
\bo If the fork option is set to netatalk, then names defaults to
342 +
\bo If the fork option is set to cap (or has taken that value by
343 default), then names defaults to cap.
345 This option determines how to convert between valid Macintosh
346 filenames and valid Linux filenames. The 7bit, 8bit and alpha options
347 correspond to Apple's recommended conventions named ``7-bit ASCII'',
348 ``8-bit'' and ``7-bit alphanumeric''.
351 When converting from Macintosh filenames to Linux filenames the
352 NULL (0x00), slash (/) and percent (%) characters and the
353 extended 8-bit characters (hexadecimal codes 0x80-0xff) are
354 replaced by a percent character (%) followed by the two-digit
355 hexadecimal code for the character.
357 When converting from Linux filenames to Macintosh filenames the
358 string "%YZ" is replaced by the character with hexadecimal code
359 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
360 for NULL or colon (:) then the string "%YZ" is unchanged. A
361 colon (:) is replaced by a pipe character (|).
364 When converting from Macintosh filenames to Linux filenames the
365 NULL (0x00), slash (/) and percent (%) characters are replaced
366 by a percent character (%) followed by the two-digit hexadecimal
367 code for the character.
369 When converting from Linux filenames to Macintosh filenames the
370 string "%YZ" is replaced by the character with hexadecimal code
371 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
372 for NULL or colon (:) then the string "%YZ" is unchanged. A
373 colon (:) is replaced by a pipe character (|).
376 When converting from Macintosh filenames to Linux filenames only
377 the alphanumeric characters (a-z, A-Z and 0-9), the underscore
378 (_) and the last period (.) in the filename are unchanged. The
379 remaining characters are replaced by a percent character (%)
380 followed by the two-digit hexadecimal code for the character.
382 When converting from Linux filenames to Macintosh filenames the
383 string "%YZ" is replaced by the character with hexadecimal code
384 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
385 for NULL or colon (:) then the string "%YZ" is unchanged. A
386 colon (:) is replaced by a pipe character (|).
389 The convention used by the Columbia AppleTalk Package's AUFS.
391 When converting from Macintosh filenames to Linux filenames the
392 characters from space ( ) through tilde (~) (ASCII 32-126) are
393 unchanged, with the exception of slash (/). The slash (/) and
394 all characters outside the range 32-126 are replaced by a colon
395 (:) followed by the two-digit hexadecimal code for the
398 When converting from Linux filenames to Macintosh filenames the
399 string ":YZ" is replaced by the character with hexadecimal code
400 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
401 for NULL or colon (:) then the colon is replaced by a pipe
405 When converting from Macintosh filenames to Linux filenames the
406 characters from space ( ) through tilde (~) (ASCII 32-126) are
407 unchanged, with the exception of slash (/) and percent (%). The
408 extended 8-bit Macintosh characters with equivalents in the
409 Latin-1 character set are replaced by those equivalents. The
410 remaining characters are replaced by a percent character (%)
411 followed by the two-digit hexadecimal code for the character.
413 When converting from Linux filenames to Macintosh filenames the
414 string "%YZ" is replaced by the character with hexadecimal code
415 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
416 for NULL or colon (:) then the string "%YZ" is unchanged. The
417 Latin-1 characters with equivalents in the extended 8-bit
418 Macintosh character set are replaced by those equivalents. A
419 colon (:) is replaced by a pipe character (|).
421 Thanks to Holger Schemel (aeglos@valinor.owl.de) for
422 contributing this conversion mode.
424 n
\bne
\bet
\bta
\bat
\bta
\bal
\blk
\bk
425 The convention used by the Netatalk afpd.
427 When converting from Macintosh filenames to Linux filenames the
428 characters from space ( ) through tilde (~) (ASCII 32-126) are
429 unchanged, with the exception of slash (/) and any initial
430 period (.). The slash (/) and any initial period (.) and all
431 characters outside the range 32-126 are replaced by a colon (:)
432 followed by the two-digit hexadecimal code for the character.
434 When converting from Linux filenames to Macintosh filenames the
435 string ":YZ" is replaced by the character with hexadecimal code
436 0xYZ. If 0xYZ is not a valid hexadecimal number or is the code
437 for NULL or colon (:) then the colon is replaced by a pipe
440 t
\btr
\bri
\biv
\bvi
\bia
\bal
\bl
441 When converting from Macintosh filenames to Linux filenames a
442 slash character (/) is replaced by a colon (:).
444 When converting from Linux filenames to Macintosh filenames a
445 colon (:) is replaced by a slash character (/).
447 2
\b2.
\b.8
\b8.
\b. p
\bpa
\bar
\brt
\bt=
\b=n
\bn
451 Specifies which HFS partition to mount from a Macintosh CDROM or hard
452 drive. Partitions are numbered from 0 and count only those identified
453 in the partition table as containing HFS filesystems. This option is
454 only useful when the Linux platform doesn't fully support Macintosh
455 partition tables. In particular on MkLinux and Linux-Pmac this option
458 Note that in versions before 0.8.3 partitions were numbered from 1.
460 2
\b2.
\b.9
\b9.
\b. q
\bqu
\bui
\bie
\bet
\bt
462 If included in the options, then chown and chmod operations will not
463 return errors, but will instead fail silently. (Same as for the MS-
464 DOS and HPFS filesystems.)
466 2
\b2.
\b.1
\b10
\b0.
\b. t
\bty
\byp
\bpe
\be=
\b=c
\bcc
\bcc
\bcc
\bc
468 default value: ``????''
470 Specifies the 4-character string specifying the Finder's Type for new
473 2
\b2.
\b.1
\b11
\b1.
\b. u
\bui
\bid
\bd=
\b=n
\bn
475 default value: uid of the mounting process
477 Specifies the user that owns all files and directories on the
478 filesystem. (Same as for the MS-DOS and HPFS filesystems.)
480 2
\b2.
\b.1
\b12
\b2.
\b. u
\bum
\bma
\bas
\bsk
\bk=
\b=n
\bn
482 default value: umask of the mounting process
484 Specifies (in octal) the umask used for all files and directories.
485 (Same as for the MS-DOS and HPFS filesystems.)
487 3
\b3.
\b. W
\bWr
\bri
\bit
\bti
\bin
\bng
\bg t
\bto
\bo H
\bHF
\bFS
\bS F
\bFi
\bil
\ble
\bes
\bsy
\bys
\bst
\bte
\bem
\bms
\bs
489 Each of the values of the fork mount option yields a different
490 representation of the Macintosh-specific parts of a file within the
491 structure of the Linux filesystem. There are, therefore, slightly
492 different steps involved in copying files if you want to preserve the
493 resource forks and the Finder's metadata.
495 It is important to remember not to use normal user-level tools to
496 modify a filesystem mounted with the afpd mount option.
498 Regardless of the value of the fork mount option you can do virtually
499 everything to the data fork of a file that you can to a file on any
500 other filesystem. The limitations are essentially the same as those
501 imposed by the MS-DOS filesystem:
503 +
\bo You can't change the uid or gid of files.
505 +
\bo You can't set the set-uid, set-gid or sticky permission bits.
507 +
\bo You can't clear the execute permission bits.
509 Likewise you can do virtually everything to a directory that you can
510 to a directory on another file system with the following exceptions:
512 +
\bo You can't create, delete or rename resource forks of files or the
513 Finder's metadata. Note, however, that they are created (with
514 defaults values), deleted and renamed along with the corresponding
515 data fork or directory.
517 +
\bo You can't change permissions on directories.
519 +
\bo You can't change the uid or gid of directories.
521 +
\bo You can't create multiple links to files.
523 +
\bo You can't create symlinks, device files, sockets or FIFOs.
525 3
\b3.
\b.1
\b1.
\b. W
\bWr
\bri
\bit
\bti
\bin
\bng
\bg w
\bwi
\bit
\bth
\bh f
\bfo
\bor
\brk
\bk=
\b=c
\bca
\bap
\bp
527 Unlike the other schemes for representing forked files, the CAP scheme
528 presents the resource fork as an independent file; the resource fork
529 of ./foo is ./.resource/foo. Therefore, you can treat it as a normal
530 file. You can do anything to a resource fork that you can do to a
531 data fork, except that you cannot enable execute permissions on a
532 resource fork. Therefore, resource forks are not suitable for holding
533 Linux executables or shared libraries.
535 If you plan to use the resource fork on a Macintosh then you must obey
536 the format of a valid resource fork. This format is documented in
537 Chapter 1 of Apple's _
\bI_
\bn_
\bs_
\bi_
\bd_
\be _
\bM_
\ba_
\bc_
\bi_
\bn_
\bt_
\bo_
\bs_
\bh_
\b: _
\bM_
\bo_
\br_
\be _
\bM_
\ba_
\bc_
\bi_
\bn_
\bt_
\bo_
\bs_
\bh _
\bT_
\bo_
\bo_
\bl_
\bb_
\bo_
\bx. The
538 filesystem knows nothing about this format and so does nothing to
541 The current support for reading and writing is sufficient to allow
542 copying of entire directories with tar, as long as both the source and
543 destination are mounted with fork=cap. tar may complain about being
544 unable to change the uid, gid or mode of files. This is normal and is
545 an unavoidable side effect of the having a single uid, gid and umask
546 for the entire filesystem.
548 It is impossible to create a resource fork or a Finder metadata file.
549 However, they are created automatically when the data fork is created.
550 Therefore, if you wish to copy a single file including both forks and
551 the Finder's metadata then you must create the data fork first. Then
552 you can copy the resource fork and the Finder's metadata. For
553 instance to copy the file foo to dir/bar you should do the following:
557 2. cp .resource/foo dir/.resource/bar
559 3. cp .finderinfo/foo dir/.finderinfo/bar
561 You may get ``Operation not permitted'' errors from cp when it tries
562 to change the permissions on files. These errors can safely be
563 ignored. This method will work even if the file dir/bar exists.
565 If you wish to move foo to dir/bar and foo and dir are on the same
566 filesystem then you only need to execute ``mv foo dir/bar'' and the
567 resource fork and the Finder's metadata will move too. However, if
568 foo and dir are on different filesystem then this will lose the
569 resource fork and metadata. Therefore, it is safest to always move
574 2. cp .resource/foo dir/.resource/bar
576 3. cp .finderinfo/foo dir/.finderinfo/bar
580 You may get ``Operation not permitted'' errors from cp when it tries
581 to change the permissions on files. These errors can safely be
582 ignored. This method will work even if the file dir/bar exists.
584 Directories have no resource fork but you may wish to create a
585 directory which has the same location and view on the Finder's screen
586 as an existing one. This can be done by copying the Finder metadata
587 file. To give the directory bar the same location, layout, creation
588 date and modify date as foo you simply execute ``cp .finderinfo/foo
591 When copying an entire directory with ``cp -R'' you may also wish to
592 copy the metadata for the directory:
596 2. cp .finderinfo/foo .finderinfo/bar
598 You may get ``Operation not permitted'' errors from cp when it tries
599 to change the permissions on files. These errors can safely be
602 3
\b3.
\b.2
\b2.
\b. W
\bWr
\bri
\bit
\bti
\bin
\bng
\bg w
\bwi
\bit
\bth
\bh f
\bfo
\bor
\brk
\bk=
\b=d
\bdo
\bou
\bub
\bbl
\ble
\be
604 The current support for reading and writing header files is sufficient
605 to allow copying of entire directories with tar, as long as both the
606 source and destination are mounted with fork=double. tar may complain
607 about being unable to change the uid, gid or mode of files. This is
608 normal and is an unavoidable side effect of the having a single uid,
609 gid and umask for the entire filesystem.
611 It is impossible to create a header file. However, they are created
612 automatically when the data fork is created. Therefore, if you wish
613 to copy a single file including both forks and the Finder's metadata
614 then you must create the data fork first. Then you can copy the
615 header file. instance to copy the file foo to dir/bar you should do
622 You may get ``Operation not permitted'' errors from cp when it tries
623 to change the permissions on files. These errors can safely be
624 ignored. This method will work even if the file dir/bar exists.
626 If you wish to move foo to dir/bar and foo and dir are on the same
627 filesystem then you only need to execute ``mv foo dir/bar'' and the
628 header file will move too. However, if foo and dir are on different
629 filesystem then this will lose the header file. Therefore, it is
630 safest to always move files as follows:
638 You may get ``Operation not permitted'' errors from cp when it tries
639 to change the permissions on files. These errors can safely be
640 ignored. This method will work even if the file dir/bar exists.
642 Directories have no resource fork but you may wish to create a
643 directory which has the same location and view on the Finder's screen
644 as an existing one. This can be done by copying the corresponding
645 header file. To give the directory bar the same location, layout,
646 creation date and modify date as foo simply execute ``cp %foo %bar''.
648 When copying an entire directory with ``cp -R'' you may also wish to
649 copy the header file for the directory as well:
655 You may get ``Operation not permitted'' errors from cp when it tries
656 to change the permissions on files. These errors can safely be
659 3
\b3.
\b.3
\b3.
\b. W
\bWr
\bri
\bit
\bti
\bin
\bng
\bg w
\bwi
\bit
\bth
\bh f
\bfo
\bor
\brk
\bk=
\b=n
\bne
\bet
\bta
\bat
\bta
\bal
\blk
\bk
661 The current support for reading and writing header files is sufficient
662 to allow copying of entire directories with tar, as long as both the
663 source and destination are mounted fork=netatalk. tar may complain
664 about being unable to change the uid, gid or mode of files. This is
665 normal and is an unavoidable side effect of the having a single uid,
666 gid and umask for the entire filesystem.
668 It is impossible to create a header file. However, they are created
669 automatically when the data fork is created. Therefore, if you wish
670 to copy a single file including both forks and the Finder's metadata
671 then you must create the data fork first. Then you can copy the
672 header file. instance to copy the file foo to dir/bar you should do
677 2. cp .AppleDouble/foo dir/.AppleDouble/bar
679 You may get ``Operation not permitted'' errors from cp when it tries
680 to change the permissions on files. These errors can safely be
681 ignored. This method will work even if the file dir/bar exists.
683 If you wish to move foo to dir/bar and foo and dir are on the same
684 filesystem then you only need to execute ``mv foo dir/bar'' and the
685 header file will move too. However, if foo and dir are on different
686 filesystem then this will lose the header file. Therefore, it is
687 safest to always move files as follows:
691 2. cp .AppleDouble/foo dir/.AppleDouble/bar
695 You may get ``Operation not permitted'' errors from cp when it tries
696 to change the permissions on files. These errors can safely be
697 ignored. This method will work even if the file dir/bar exists.
699 Directories have no resource fork but you may wish to create a
700 directory which has the same location and view on the Finder's screen
701 as an existing one. This can be done by copying the corresponding
702 header file. To give the directory bar the same location, layout,
703 creation date and modify date as foo you simply execute ``cp
704 foo/.AppleDouble/.Parent bar/.AppleDouble/.Parent''.
706 Because the fork=netatalk scheme holds the header file for a directory
707 within that directory, directories can safely be copied with ``cp -R
708 foo bar'' with no loss of information. However, you may get
709 ``Operation not permitted'' errors from cp when it tries to change the
710 permissions on files. These errors can safely be ignored.
712 4
\b4.
\b. A
\bA G
\bGu
\bui
\bid
\bde
\be t
\bto
\bo S
\bSp
\bpe
\bec
\bci
\bia
\bal
\bl F
\bFi
\bil
\ble
\be F
\bFo
\bor
\brm
\bma
\bat
\bts
\bs
714 Each of the values of the fork mount option yields different special
715 files to represent the Macintosh-specific parts of a file within the
716 structure of the Linux filesystem. You can write to these special
717 files to change things such as the Creator and Type of a file.
718 However, to do so safely you must follow certain rules to avoid
719 corrupting the data. Additionally, there are certain fields in the
720 special files that you can't change (writes to them will fail
723 4
\b4.
\b.1
\b1.
\b. C
\bCA
\bAP
\bP .
\b.f
\bfi
\bin
\bnd
\bde
\ber
\bri
\bin
\bnf
\bfo
\bo F
\bFi
\bil
\ble
\bes
\bs
725 The Finder's metadata for the file ./foo in held in the file
726 ./.finderinfo/foo. The file has a fixed format defined in hfs_fs.h as
729 ______________________________________________________________________
730 struct hfs_cap_info {
731 __u8 fi_fndr[32]; /* Finder's info */
732 __u16 fi_attr; /* AFP attributes */
733 __u8 fi_magic1; /* Magic number: */
734 #define HFS_CAP_MAGIC1 0xFF
735 __u8 fi_version; /* Version of this structure: */
736 #define HFS_CAP_VERSION 0x10
737 __u8 fi_magic; /* Another magic number: */
738 #define HFS_CAP_MAGIC 0xDA
739 __u8 fi_bitmap; /* Bitmap of which names are valid: */
740 #define HFS_CAP_SHORTNAME 0x01
741 #define HFS_CAP_LONGNAME 0x02
742 __u8 fi_shortfilename[12+1]; /* "short name" (unused) */
743 __u8 fi_macfilename[32+1]; /* Original (Macintosh) name */
744 __u8 fi_comln; /* Length of comment (always 0) */
745 __u8 fi_comnt[200]; /* Finder comment (unused) */
746 /* optional: used by aufs only if compiled with USE_MAC_DATES */
747 __u8 fi_datemagic; /* Magic number for dates extension: */
748 #define HFS_CAP_DMAGIC 0xDA
749 __u8 fi_datevalid; /* Bitmap of which dates are valid: */
750 #define HFS_CAP_MDATE 0x01
751 #define HFS_CAP_CDATE 0x02
752 __u8 fi_ctime[4]; /* Creation date (in AFP format) */
753 __u8 fi_mtime[4]; /* Modify date (in AFP format) */
754 __u8 fi_utime[4]; /* Un*x time of last mtime change */
756 ______________________________________________________________________
758 The type __u8 is an unsigned character, and __u16 is an unsigned
761 Currently only the fields fi_fndr, fi_attr, fi_ctime and fi_mtime can
762 be changed. Writes to the other fields are silently ignored.
763 However, you shouldn't write random bytes to the other fields, since
764 they may be writable in the future.
766 The fi_fndr field is the ``Finder info'' and ``Extended Finder info''
767 for a file or directory. These structures are described in various
768 books on Macintosh programming. The portion of the most interest is
769 probably the first 8 bytes which, for a file, give the 4-byte Type
770 followed by the 4-byte Creator.
772 The fi_attr field is the AFP attributes of the file or directory.
773 While you can write any value to this field, only the ``write-
774 inhibit'' bit is significant. Setting or clearing this bit will clear
775 or set the write bits in the file's permissions. When you read from
776 this field anything you may have written is lost. If the file has
777 write permissions enabled then you will read zero from this field.
778 With write permission disabled you will read back 0x01 0xA0, which
779 corresponds to setting the ``write-inhibit'', ``rename-inhibit'' and
780 ``delete-inhibit'' bits.
782 The fi_ctime and fi_mtime are the Macintosh created and modified time
783 for the file or directory, and are 32-bit signed integers in network
784 byteorder giving seconds from 00:00 GMT Jan. 1, 2000.
786 4
\b4.
\b.2
\b2.
\b. A
\bAp
\bpp
\bpl
\ble
\beD
\bDo
\bou
\bub
\bbl
\ble
\be H
\bHe
\bea
\bad
\bde
\ber
\br F
\bFi
\bil
\ble
\bes
\bs
788 Both the fork=double and fork=netatalk schemes for representing forked
789 files use AppleDouble header files to contain the resource fork and
790 the Finder's metadata together in a single file.
792 The AppleDouble format specifies a fixed-format header which describes
793 which fields are contained in the remainder of the file, where they
794 are located in the file and how long they are. A full description of
795 the version 1 format used when fork=netatalk is available from ??????.
796 The version 2 format used when fork=double is documented in ??????.
797 The discussion that follows assumes you have read and understood these
798 documents, which may be difficult until I've replaced the ``??????''s
799 above with something more informative :-).
801 Due to the variable structure of an AppleDouble header file you must
802 not use buffered I/O when reading or writing them; you should only use
803 the read() and write() system calls. It is also important that you
804 make some effort to coordinate processes that are reading and writing
805 the same header file, since a reader will receive the wrong data if
806 the location of a given entry has changed since it read the descriptor
807 for the entry. If a process tries to read the descriptor table while
808 it is changing then it is possible to read totally meaningless data.
810 When a header file is opened it is initially presented with a default
811 header layout. You may write to the header to change the layout, but
812 when all file descriptors for the file or directory have been closed
813 the change in format is lost and subsequent opens will yield the
814 default layout. Changes to supported entries are made directly to the
815 filesystem and are thus preserved when the file is closed and
818 The HFS filesystem currently uses a fixed-size table to hold the
819 descriptors. Therefore you are limited to HFS_HDR_MAX (currently 10)
820 descriptors. In the unlikely event that you try to write a header
821 with more descriptors, a warning will be issued by the kernel, and
822 extra descriptors will be ignored. This should be considered a bug
823 and will hopefully change sooner rather than later.
825 The results of specifying overlapping entries is undefined and should
826 not be relied upon to remain unchanged from one version of the HFS
827 filesystem to the next. There is no valid reason to define
828 overlapping entries, so just don't do it!
830 Changes to the magic number and version fields are preserved until all
831 file descriptors are closed, however the only significance given to
832 them internally is that the 16 bytes following the version changes
833 meaning according to the version. For version 1 header files these 16
834 bytes contain the string ``Macintosh'' followed by 7 spaces. For any
835 other value of the version field these 16 bytes are all zeros. In
836 either case writes to these 16 bytes are silently ignored.
838 Since the magic number and version are given no other significance
839 internally, you are free to do many things that violate the official
840 formats. For instance you can create an entry for the data fork in a
841 header file with an AppleDouble magic number or create ``File Info''
842 (id=7) entries in version 2 header files and ``File Dates Info''
843 (id=8) entries in version 1 header files. However, future versions of
844 the filesystem may enforce the format more strictly.
846 Entry id 1 (``Data Fork'') is read-only. You should use the data file
847 to modify the data fork. The data fork is, of course, not supported
850 Entry ids 2, 7, 8, 9 and 10 (``Resource Fork'', ``File Info'', ``File
851 Dates Info'', ``Finder Info'' and ``Macintosh File Info'') are fully
852 supported, meaning that their contents may be read and written and
853 that data written is preserved when the file is closed and reopened.
854 The resource fork is, of course, not supported for directories.
856 Entry id 7 specifies some of the same data given by ids 8 and 10. If
857 you create a header file with an entry for id 7 and for ids 8 or 10,
858 then the behavior with respect to their interaction is undefined. A
859 header that contains an entry for id 7 and for ids 8 or 10 is not
860 valid as either a version 1 or a version 2 header file, so there is no
861 reason to do this and future versions may prevent it.
863 Entry id 3 (``Real Name'') is read-only, since it will change
864 automatically when a file is renamed. Writes to the corresponding
865 entry are silently ignored.
867 All other entry ids are ignored. You may create descriptors for them;
868 in fact the default header layout when fork=netatalk includes a
869 descriptor for id 4 (``Comment''). However writes to the entries
870 corresponding to the ignored ids fail silently and reads from the
871 entries always return zeros. However, you shouldn't write random
872 bytes to unsupported entries, since they may be supported in the
875 All of the supported entry types except the data and resource forks
876 have a fixed length. If you give them a smaller length in the
877 descriptor then you are unable to access part of the corresponding
878 entry. If you give them a larger length in the descriptor, then the
879 corresponding entry is padded with zeros and writes to the extra space
880 are silently ignored.
882 Writes to the length field of descriptors for the data and resource
883 forks will cause the corresponding fork to grow (with zero padding) or
884 shrink to the indicated length.
886 If you have an entry for the data fork then the descriptor's length
887 field does not change automatically to reflect any modification of the
888 data fork directly (the data does change however). If the data fork
889 is longer than the descriptor indicates, then a portion of it is
890 inaccessible. If the data fork is shorter than the descriptor
891 indicates then reads will be padded with zeros.
893 Writes beyond the end of the resource fork that extend into empty
894 space between entries or beyond the end of the file will extend the
895 fork, automatically changing the length field of the corresponding
896 descriptor. Writes to any other space between entries are silently
897 ignored and read of such spaces always return zeros.
899 Calling truncate() on a header file can change the length of the
900 resource fork and such a change will automatically be reflected in the
901 length field of the corresponding descriptor. If truncate() shortens
902 the file so that the entry for the resource fork would extend beyond
903 the new end of the file then the fork is shortened to fit in the space
904 that remains, or to zero bytes if the entry is now entirely beyond the
905 end of the file. If the last entry in a header file is the resource
906 fork then a call to truncate() that extends the header file will
907 extend the fork with zeros. Note that this happens even if there was
908 previously space between the end of the fork and the end of the file.
910 5
\b5.
\b. R
\bRe
\bep
\bpo
\bor
\brt
\bti
\bin
\bng
\bg B
\bBu
\bug
\bgs
\bs
912 If you'd like any problems you encounter fixed, you'll need to provide
913 a detailed bug report. However, you should check the FAQ (available
914 from the HFS for Linux Page <http://www-sccm.Stanford.EDU/~hargrove/HFS/>)
915 first to be certain that your problem is not a known limitation of the
916 filesystem. If your bug doesn't appear in the FAQ then you should e-mail
917 me at hargrove@sccm.Stanford.EDU.
919 5
\b5.
\b.1
\b1.
\b. W
\bWh
\bha
\bat
\bt G
\bGo
\boe
\bes
\bs i
\bin
\bn a
\ba B
\bBu
\bug
\bg R
\bRe
\bep
\bpo
\bor
\brt
\bt
921 When writing your bug report, include any facts you think might be
922 relevant; I'd much rather have a bunch of extra facts than need to
923 e-mail you to get the information. At a minimum the following
924 information should be included:
926 +
\bo The version of the HFS filesystem you are using (see
927 linux/fs/hfs/version.h).
929 +
\bo The kernel version you are using.
931 +
\bo Any unofficial kernel patches or loadable modules you are using.
933 +
\bo If you are loading the HFS filesystem as a module, then version of
934 the module utilities used to load hfs.o.
936 +
\bo The type of media you are working with (floppy, CDROM, ZIP Drive,
939 +
\bo The steps required to reproduce the bug, including mount options
940 used. (If you can't reproduce the bug tell me everything you did
941 the one time it did occur, but be warned that non-reproducible bugs
942 can only rarely be fixed.)
944 5
\b5.
\b.2
\b2.
\b. H
\bHo
\bow
\bw t
\bto
\bo R
\bRe
\bep
\bpo
\bor
\brt
\bt a
\ba K
\bKe
\ber
\brn
\bne
\bel
\bl O
\bOo
\bop
\bps
\bs o
\bor
\br G
\bGP
\bPF
\bF
946 If you encounter a bug that causes a kernel Oops or a General
947 Protection Fault then you'll need to collect some additional
948 information for the bug report. If you are loading the HFS filesystem
949 as a module, then is important that you do this before rebooting,
950 since the module is unlikely to be loaded at the same address after
953 You should include all the information that the kernel prints to the
954 console or to the system logs. However, the EIP and Stack Trace are
955 addresses in _
\by_
\bo_
\bu_
\br kernel and mean nothing to me without more
956 information. Using your System.map file (or either ksymoops or klogd)
957 determine which functions the EIP and Stack Trace are in. If you do
958 this by hand using your System.map file then the correct symbol is the
959 one of type t or T with the largest address less than or equal to the
960 one you are resolving.
962 If you are loading the HFS filesystem as a module and the Oops or GPF
963 was in the HFS code then the EIP and the top levels of the Stack Trace
964 will be in a loadable module, rather than in the kernel proper. So,
965 their symbols will not be in the file System.map. Therefore, you will
966 need to use /proc/ksyms, or a loadmap produced by passing the -m
967 option to insmod, to locate those symbols.
969 6
\b6.
\b. L
\bLe
\beg
\bga
\bal
\bl N
\bNo
\bot
\bti
\bic
\bce
\bes
\bs
971 6
\b6.
\b.1
\b1.
\b. T
\bTh
\bhi
\bis
\bs D
\bDo
\boc
\bcu
\bum
\bme
\ben
\bnt
\bt
973 This document is Copyright (c) 1996, 1997 by Paul H. Hargrove.
975 Permission is granted to make and distribute verbatim copies of this
976 document provided the copyright notice and this permission notice are
977 preserved on all copies.
979 Permission is granted to copy and distribute modified versions of this
980 document under the conditions for verbatim copies above, provided a
981 notice clearly stating that the document is a modified version is also
982 included in the modified document.
984 Permission is granted to copy and distribute translations of this
985 document into another language, under the conditions specified above
986 for modified versions.
988 Permission is granted to convert this document into another media
989 under the conditions specified above for modified versions provided
990 the requirement to acknowledge the source document is fulfilled by
991 inclusion of an obvious reference to the source document in the new
992 media. Where there is any doubt as to what defines ``obvious'' the
993 copyright owner reserves the right to decide.
995 6
\b6.
\b.2
\b2.
\b. T
\bTh
\bhe
\be S
\bSo
\bof
\bft
\btw
\bwa
\bar
\bre
\be
997 The HFS filesystem for Linux is Copyright (c) 1994-1997 by Paul H.
1000 This software is free software; you can redistribute it and/or modify
1001 it under the terms of the GNU General Public License as published by
1002 the Free Software Foundation; either version 2, or (at your option)
1005 This software is distributed in the hope that it will be useful, but
1006 WITHOUT ANY WARRANTY; without even the implied warranty of
1007 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1008 General Public License for more details.
1010 You should have received a copy of the GNU General Public License
1011 along with this software in the file ``COPYING''; if not, write to the
1012 Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
1015 6
\b6.
\b.2
\b2.
\b.1
\b1.
\b. T
\bTh
\bhe
\be C
\bCo
\bol
\blu
\bum
\bmb
\bbi
\bia
\ba A
\bAp
\bpp
\bpl
\ble
\beT
\bTa
\bal
\blk
\bk P
\bPa
\bac
\bck
\bka
\bag
\bge
\be f
\bfo
\bor
\br U
\bUN
\bNI
\bIX
\bX
1017 The source code distribution of the Columbia AppleTalk Package for
1018 UNIX, version 6.0, (CAP) was used as a _
\bs_
\bp_
\be_
\bc_
\bi_
\bf_
\bi_
\bc_
\ba_
\bt_
\bi_
\bo_
\bn of the location
1019 and format of files used by CAP's Aufs. No code from CAP appears in
1020 the HFS filesystem. The HFS filesystem is not a work ``derived'' from
1021 CAP in the sense of intellectual property law.
1023 6
\b6.
\b.2
\b2.
\b.2
\b2.
\b. N
\bNe
\bet
\bta
\bat
\bta
\bal
\blk
\bk
1025 The source code distributions of Netatalk, versions 1.3.3b2 and 1.4b2,
1026 were used as a _
\bs_
\bp_
\be_
\bc_
\bi_
\bf_
\bi_
\bc_
\ba_
\bt_
\bi_
\bo_
\bn of the location and format of files used
1027 by Netatalk's afpd. No code from Netatalk appears in the HFS
1028 filesystem. The HFS filesystem is not a work ``derived'' from
1029 Netatalk in the sense of intellectual property law.
1031 6
\b6.
\b.3
\b3.
\b. T
\bTr
\bra
\bad
\bde
\bem
\bma
\bar
\brk
\bks
\bs
1033 +
\bo ``Finder'' is a trademarks of Apple Computer, Inc.
1035 +
\bo ``Apple'', ``AppleShare'', ``AppleTalk'' and ``Macintosh'' are
1036 registered trademarks of Apple Computer, Inc.
1038 +
\bo ``Microsoft'' and ``MS-DOS'' are registered trademarks of Microsoft
1041 +
\bo All other trademarks are the property of their respective owners.