hfs+

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

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. It also implements an interface to copyfile(3).

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:

#:no-follow

Do not follow symlinks; operate on the symlink itself.

list-extended-attributes

list-extended-attributes file #!rest optionsprocedure

List extended attribute names of FILE.

Returns a list containing one string per attribute name.

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

get-extended-attribute

get-extended-attribute file attribute #!rest optionsprocedure

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!

set-extended-attribute! file attribute value #!rest optionsprocedure

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

VALUE may be a string or a blob.

In addition to #:no-follow, 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!

remove-extended-attribute! file attribute #!rest optionsprocedure

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.

copyfile

copyfile from to #!rest optionsprocedure

Copies FROM file to TO file using the OS X copyfile(3) API, preserving HFS+ metadata as specified in copyfile OPTIONS. Always returns a true value, indicating success; failure will raise an error. In the current implementation, both FROM and TO must be filenames; ports are not accepted.

If the #:check option is given, copyfile will determine which metadata would be copied from the source, without copying it. It returns zero if there is no corresponding metadata, and a positive value if there is metadata to copy. Either way, the return value is true, indicating success.

If #:pack is given, copyfile serializes the desired metadata to an AppleDouble file named by the TO argument. #:unpack is the opposite of #:pack. This AppleDouble file is the same format as that produced when writing a file to a non-HFS+ filesystem, such as across a network to NFS or Samba. Because an AppleDouble file is always created when packing, even if there is no metadata to copy, you may wish to use #:check first to avoid this.

copyfile options

Refer to the copyfile(3) manpage for details.

These options specify which data to copy:

#:acls	COPYFILE_ACL	Copy ACLs
#:stat	COPYFILE_STAT	Copy POSIX stat(2) items
#:extended-attributes	COPYFILE_XATTR	Copy HFS+ extended attributes
#:data	COPYFILE_DATA	Copy file data
#:security	COPYFILE_SECURITY	Equivalent to #:acls #:stat
#:metadata	COPYFILE_METADATA	Equivalent to #:extended-attributes #:security
#:all	COPYFILE_ALL	Equivalent to #:metadata #:data

These options are flags which affect the copy operation:

#:check	COPYFILE_CHECK	Dry-run; determine which metadata would be copied
#:pack	COPYFILE_PACK	Pack metadata in FROM to TO in AppleDouble format
#:unpack	COPYFILE_UNPACK	Apply packed metadata in FROM to TO
#:exclusive	COPYFILE_EXCL	Raise error if TO already exists
#:no-follow-source	COPYFILE_NOFOLLOW_SRC	Do not follow symlink on FROM
#:no-follow-dest	COPYFILE_NOFOLLOW_DST	Do not follow symlink on TO
#:no-follow	COPYFILE_NOFOLLOW	Equivalent to #:no-follow-source #:no-follow-dest
#:move	COPYFILE_MOVE	Unlink FROM after the copy
#:unlink	COPYFILE_UNLINK	Unlink TO prior to copy

copyfile deficiencies

copyfile(3) is present on OS X 10.4, but not officially supported. On 10.4, we recommend using copyfile only to pack and unpack metadata to and from AppleDouble format. Certain options do not work properly: #:move has no effect; #:no-follow has no effect during a pack/unpack; #:data will fail with an error (and may even cause a segfault). There may be other deficiencies.

Utilities

get-extended-attributes

get-extended-attributes file #!rest optionsprocedure

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!

clear-extended-attributes! file #!rest optionsprocedure: Remove all extended attributes from FILE.

copyfile-check

copyfile-check from #!rest optionsprocedure

Determines if any metadata is present in FROM using the #:check option to copyfile. Returns a list of symbols denoting metadata types that are present, from the following possibilities:

acls	COPYFILE_ACL	ACLs
stat	COPYFILE_STAT	POSIX stat(2) data
extended-attributes	COPYFILE_XATTR	Extended attributes

Note: another way to check merely for the presence of metadata is to use the #:check option to copyfile. A positive value means present, a zero value means not present.

Example:

#;> (copyfile-check "foo.txt" #:metadata)
(acls stat extended-attributes)
#;> (copyfile-check "foo.txt" #:extended-attributes)
(extended-attributes)
#;> (copyfile-check "bar.txt" #:metadata)
()
#;> (> (copyfile "foo.txt" #f #:check #:metadata) 0)
#t
#;> (> (copyfile "bar.txt" #f #:check #:metadata) 0)
#f

pack-appledouble

pack-appledouble from to #!rest optionsprocedure

Serialize all HFS+ metadata (extended attributes, ACLs, stat(2) data) in FROM to AppleDouble file TO. Returns false when no metadata was present (and does not write a file) or true if metadata was present (and a file is written). May also throw a file error.

Extra options are passed into copyfile; relevant ones might be #:exclusive, #:move and #:no-follow, although #:move and #:no-follow do not work correctly under Tiger.

unpack-appledouble

unpack-appledouble from to #!rest optionsprocedure: Unserialize all HFS+ metadata in AppleDouble file FROM to TO. Always returns true, or throws an error on I/O error.

$ 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

0.3 Add copyfile interface
0.2 Add #:silent option to remove, clear-extended-attributes!
0.1 Initial release

License

BSD.

The Apple header copyfile.h is not present on Tiger, so it is included in the egg. The header is under the Apple Public Source License.

chickadee » hfs+

Identifier search