You are looking at historical revision 15013 of this page. It may differ significantly from its current revision.

hfs+

Synopsis

hfs+ is a interface to the HFS+ filesystem on Mac OS X 10.4 and above.

The current implementation provides access to HFS+ extended attributes, including resource forks.

Interface

Overview

All calls taking a FILE argument accept either a filename or an open POSIX file descriptor.

All calls taking an ATTRIBUTE argument accept either a string or a symbol.

All extended attribute calls allow the following options:

#:nofollow Do not follow symlinks; operate on the symlink itself.

list-extended-attributes

[procedure] (list-extended-attributes file . options)

List extended attribute names of FILE.

Returns a list containing one string per attribute name.

 (list-extended-attributes "examples.scm" #:nofollow)
 ; => ("com.apple.FinderInfo" "com.apple.ResourceFork")

get-extended-attribute

[procedure] (get-extended-attribute file attribute . options)

Get the value of extended attribute ATTRIBUTE from FILE.

Returns a string representing the value. The string may contain binary data.

Returns #f if the attribute does not exist.

set-extended-attribute!

[procedure] (set-extended-attribute! file attribute value . options)

Set extended attribute ATTRIBUTE on FILE to VALUE, and return an unspecified value.

VALUE may be a string or a blob.

In addition to #:nofollow, set-extended-attribute! allows the following two mutually-exclusive options:

#:create Raise error if attribute exists.
#:replace Raise error if attribute does not exist.

If neither option is specified, existing attribute values are silently overwritten.

(set-extended-attribute! "examples.scm" 'org.callcc "courtesy of Chicken")
(get-extended-attribute "examples.scm" 'org.callcc)
; => "courtesy of Chicken"

remove-extended-attribute!

[procedure] (remove-extended-attribute! file attribute . options)

Remove extended attribute ATTRIBUTE from FILE. By default, if ATTRIBUTE does not exist, an error is signaled.

remove-extended-attribute! also accepts the following options:

#:silent Do not raise an error if the attribute is missing.

The #:silent option is useful if, for example, you wish to truncate a resource fork but are not sure if one is already present. See below for an example.

Utilities

get-extended-attributes

[procedure] (get-extended-attributes file . options)

Returns an alist mapping attribute names (symbols) to values (strings).

(get-extended-attributes "examples.scm")
;=> ((com.apple.FinderInfo . "TEXTEMAx")
     (com.apple.ResourceFork . "courtesy of Chicken")
     (org.callcc . "courtesy of Chicken"))

clear-extended-attributes!

[procedure] (clear-extended-attributes! file . options)

Remove all extended attributes from FILE.

Errors

If the system API returns an unrecoverable error, a Scheme error will be raised. The exception is of type (exn file hfs+).

Notes

Resource forks

Special care is required when writing resource fork data. OS X will not truncate an existing resource fork if you write a shorter value, so you must remove the resource fork prior to writing.

Incorrect example:

$ echo -n "courtesy of the command-line" > examples.scm/rsrc
$ csi -q -R hfs+ <<EOF
(set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
                         "courtesy of Chicken")
EOF
$ cat examples.scm/rsrc ; echo
courtesy of Chickenmand-line

Correct example:

$ echo -n "courtesy of the command-line" > examples.scm/rsrc
$ csi -q -R hfs+ <<EOF
(remove-extended-attribute! "examples.scm" 'com.apple.ResourceFork #:silent)
(set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
                         "courtesy of Chicken" #:create)
EOF
$ cat examples.scm/rsrc ; echo
courtesy of Chicken

Author

Jim Ursetto

Version history

License

BSD.