Changeset 15279 in project

Timestamp:

07/31/09 01:11:48 (10 years ago)

Author:

Jim Ursetto

Message:

hfs+: update wiki for v0.3

File:

• wiki/eggref/4/hfs+ (modified) (8 diffs)

wiki/eggref/4/hfs+

@@ -8 +8 @@
 
 The current implementation provides access to HFS+ extended
-attributes, including resource forks.
+attributes, including resource forks.  It also implements an
+interface to {{copyfile(3)}}.
 
 === Interface
@@ -24 +25 @@
 <nowiki>
 <table>
-<tr><td>#:nofollow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
+<tr><td>#:no-follow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
 </table>
 </nowiki>
@@ -36 +37 @@
 Returns a list containing one string per attribute name.
 
-  (list-extended-attributes "examples.scm" #:nofollow)
+  (list-extended-attributes "examples.scm" #:no-follow)
   ; => ("com.apple.FinderInfo" "com.apple.ResourceFork")
 
@@ -58 +59 @@
 {{VALUE}} may be a string or a blob.
 
-In addition to {{#:nofollow}}, {{set-extended-attribute!}} allows the
+In addition to {{#:no-follow}}, {{set-extended-attribute!}} allows the
 following two mutually-exclusive options:
 
@@ -93 +94 @@
 a resource fork but are not sure if one is already present.  See below
 for an example.
+
+==== copyfile
+
+<procedure>(copyfile from to . options)</procedure>
+
+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 [[http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/copyfile.3.html|copyfile(3) manpage]] for details.
+
+These options specify ''which'' data to copy:
+<nowiki>
+<table>
+<tr><td>#:acls</td><td>COPYFILE_ACL</td><td>Copy ACLs</td></tr>
+<tr><td>#:stat</td><td>COPYFILE_STAT</td><td>Copy POSIX stat(2) items</td></tr>
+<tr><td>#:extended-attributes</td><td>COPYFILE_XATTR</td><td>Copy HFS+ extended attributes</td></tr>
+<tr><td>#:data</td><td>COPYFILE_DATA</td><td>Copy file data</td></tr>
+<tr><td>#:security</td><td>COPYFILE_SECURITY</td><td>Equivalent to #:acls #:stat</td></tr>
+<tr><td>#:metadata</td><td>COPYFILE_METADATA</td><td>Equivalent to #:extended-attributes #:security</td></tr>
+<tr><td>#:all</td><td>COPYFILE_ALL</td><td>Equivalent to #:metadata #:data</td></tr>
+</table>
+</nowiki>
+
+These options are flags which affect the copy operation:
+
+<nowiki>
+<table>
+<tr><td>#:check</td><td>COPYFILE_CHECK</td><td>Dry-run; determine which metadata would be copied</td></tr>
+<tr><td>#:pack</td><td>COPYFILE_PACK</td><td>Pack metadata in FROM to TO in AppleDouble format</td></tr>
+<tr><td>#:unpack</td><td>COPYFILE_UNPACK</td><td>Apply packed metadata in FROM to TO</td></tr>
+<tr><td>#:exclusive</td><td>COPYFILE_EXCL</td><td>Raise error if TO already exists</td></tr>
+<tr><td>#:no-follow-source</td><td>COPYFILE_NOFOLLOW_SRC</td><td>Do not follow symlink on FROM</td></tr>
+<tr><td>#:no-follow-dest</td><td>COPYFILE_NOFOLLOW_DST</td><td>Do not follow symlink on TO</td></tr>
+<tr><td>#:no-follow</td><td>COPYFILE_NOFOLLOW</td><td>Equivalent to #:no-follow-source #:no-follow-dest</td></tr>
+<tr><td>#:move</td><td>COPYFILE_MOVE</td><td>Unlink FROM after the copy</td></tr>
+<tr><td>#:unlink</td><td>COPYFILE_UNLINK</td><td>Unlink TO prior to copy</td></tr>
+</table>
+</nowiki>
+
+===== 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
@@ -112 +179 @@
 
 Remove all extended attributes from {{FILE}}.
+
+==== copyfile-check
+
+<procedure>(copyfile-check from . options)</procedure>
+
+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:
+
+<nowiki>
+<table>
+<tr><td>acls</td><td>COPYFILE_ACL</td><td>ACLs</td></tr>
+<tr><td>stat</td><td>COPYFILE_STAT</td><td>POSIX stat(2) data</td></tr>
+<tr><td>extended-attributes</td><td>COPYFILE_XATTR</td><td>Extended attributes</tr>
+</table>
+</nowiki>
+
+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
+
+<procedure>(pack-appledouble from to . options)</procedure>
+
+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
+
+<procedure>(unpack-appledouble from to . options)</procedure>
+
+Unserialize all HFS+ metadata in AppleDouble file {{FROM}} to {{TO}}.
+Always returns true, or throws an error on I/O error.
 
 === Errors
@@ -153 +274 @@
 === Version history
 
+* 0.3 Add copyfile interface
 * 0.2 Add #:silent option to remove, clear-extended-attributes!
 * 0.1 Initial release
@@ -160 +282 @@
 BSD.
 
+The Apple header [[http://www.opensource.apple.com/source/Libc/Libc-391.5.18/darwin/copyfile.h|copyfile.h]] is not present on Tiger, so it is included in the egg.  The header is under the [[http://www.opensource.apple.com/apsl/|Apple Public Source License]].
+