Changeset 15279 in project


Ignore:
Timestamp:
07/31/09 01:11:48 (10 years ago)
Author:
Jim Ursetto
Message:

hfs+: update wiki for v0.3

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/hfs+

    r15013 r15279  
    88
    99The current implementation provides access to HFS+ extended
    10 attributes, including resource forks.
     10attributes, including resource forks.  It also implements an
     11interface to {{copyfile(3)}}.
    1112
    1213=== Interface
     
    2425<nowiki>
    2526<table>
    26 <tr><td>#:nofollow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
     27<tr><td>#:no-follow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
    2728</table>
    2829</nowiki>
     
    3637Returns a list containing one string per attribute name.
    3738
    38   (list-extended-attributes "examples.scm" #:nofollow)
     39  (list-extended-attributes "examples.scm" #:no-follow)
    3940  ; => ("com.apple.FinderInfo" "com.apple.ResourceFork")
    4041
     
    5859{{VALUE}} may be a string or a blob.
    5960
    60 In addition to {{#:nofollow}}, {{set-extended-attribute!}} allows the
     61In addition to {{#:no-follow}}, {{set-extended-attribute!}} allows the
    6162following two mutually-exclusive options:
    6263
     
    9394a resource fork but are not sure if one is already present.  See below
    9495for an example.
     96
     97==== copyfile
     98
     99<procedure>(copyfile from to . options)</procedure>
     100
     101Copies {{FROM}} file to {{TO}} file using the OS X {{copyfile(3)}}
     102API, preserving HFS+ metadata as specified in copyfile {{OPTIONS}}.
     103Always returns a true value, indicating success; failure will raise an
     104error.  In the current implementation, both {{FROM}} and {{TO}} must
     105be filenames; ports are not accepted.
     106
     107If the {{#:check}} option is given, {{copyfile}} will determine which
     108metadata would be copied from the source, without copying it.  It
     109returns zero if there is no corresponding metadata, and a positive
     110value if there is metadata to copy.  Either way, the return value is
     111true, indicating success.
     112
     113If {{#:pack}} is given, {{copyfile}} serializes the desired metadata
     114to an AppleDouble file named by the {{TO}} argument.  {{#:unpack}} is
     115the opposite of {{#:pack}}.  This AppleDouble file is the same format
     116as that produced when writing a file to a non-HFS+ filesystem, such as
     117across a network to NFS or Samba.  Because an AppleDouble file is
     118always created when packing, even if there is no metadata to copy, you
     119may wish to use {{#:check}} first to avoid this.
     120
     121===== copyfile options
     122
     123Refer to the [[http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/copyfile.3.html|copyfile(3) manpage]] for details.
     124
     125These options specify ''which'' data to copy:
     126<nowiki>
     127<table>
     128<tr><td>#:acls</td><td>COPYFILE_ACL</td><td>Copy ACLs</td></tr>
     129<tr><td>#:stat</td><td>COPYFILE_STAT</td><td>Copy POSIX stat(2) items</td></tr>
     130<tr><td>#:extended-attributes</td><td>COPYFILE_XATTR</td><td>Copy HFS+ extended attributes</td></tr>
     131<tr><td>#:data</td><td>COPYFILE_DATA</td><td>Copy file data</td></tr>
     132<tr><td>#:security</td><td>COPYFILE_SECURITY</td><td>Equivalent to #:acls #:stat</td></tr>
     133<tr><td>#:metadata</td><td>COPYFILE_METADATA</td><td>Equivalent to #:extended-attributes #:security</td></tr>
     134<tr><td>#:all</td><td>COPYFILE_ALL</td><td>Equivalent to #:metadata #:data</td></tr>
     135</table>
     136</nowiki>
     137
     138These options are flags which affect the copy operation:
     139
     140<nowiki>
     141<table>
     142<tr><td>#:check</td><td>COPYFILE_CHECK</td><td>Dry-run; determine which metadata would be copied</td></tr>
     143<tr><td>#:pack</td><td>COPYFILE_PACK</td><td>Pack metadata in FROM to TO in AppleDouble format</td></tr>
     144<tr><td>#:unpack</td><td>COPYFILE_UNPACK</td><td>Apply packed metadata in FROM to TO</td></tr>
     145<tr><td>#:exclusive</td><td>COPYFILE_EXCL</td><td>Raise error if TO already exists</td></tr>
     146<tr><td>#:no-follow-source</td><td>COPYFILE_NOFOLLOW_SRC</td><td>Do not follow symlink on FROM</td></tr>
     147<tr><td>#:no-follow-dest</td><td>COPYFILE_NOFOLLOW_DST</td><td>Do not follow symlink on TO</td></tr>
     148<tr><td>#:no-follow</td><td>COPYFILE_NOFOLLOW</td><td>Equivalent to #:no-follow-source #:no-follow-dest</td></tr>
     149<tr><td>#:move</td><td>COPYFILE_MOVE</td><td>Unlink FROM after the copy</td></tr>
     150<tr><td>#:unlink</td><td>COPYFILE_UNLINK</td><td>Unlink TO prior to copy</td></tr>
     151</table>
     152</nowiki>
     153
     154===== copyfile deficiencies
     155
     156{{copyfile(3)}} is present on OS X 10.4, but not officially supported.
     157On 10.4, we recommend using {{copyfile}} only to pack and unpack
     158metadata to and from AppleDouble format.  Certain options do not work
     159properly: {{#:move}} has no effect; {{#:no-follow}} has no effect
     160during a pack/unpack; #:data will fail with an error (and may even
     161cause a segfault).  There may be other deficiencies.
    95162
    96163=== Utilities
     
    112179
    113180Remove all extended attributes from {{FILE}}.
     181
     182==== copyfile-check
     183
     184<procedure>(copyfile-check from . options)</procedure>
     185
     186Determines if any metadata is present in {{FROM}} using the
     187{{#:check}} option to {{copyfile}}.  Returns a list of symbols
     188denoting metadata types that are present, from the following
     189possibilities:
     190
     191<nowiki>
     192<table>
     193<tr><td>acls</td><td>COPYFILE_ACL</td><td>ACLs</td></tr>
     194<tr><td>stat</td><td>COPYFILE_STAT</td><td>POSIX stat(2) data</td></tr>
     195<tr><td>extended-attributes</td><td>COPYFILE_XATTR</td><td>Extended attributes</tr>
     196</table>
     197</nowiki>
     198
     199Note: another way to check merely for the presence of metadata is to use the
     200{{#:check}} option to copyfile.  A positive value means present, a zero value
     201means not present.
     202
     203Example:
     204
     205 #;> (copyfile-check "foo.txt" #:metadata)
     206 (acls stat extended-attributes)
     207 #;> (copyfile-check "foo.txt" #:extended-attributes)
     208 (extended-attributes)
     209 #;> (copyfile-check "bar.txt" #:metadata)
     210 ()
     211 #;> (> (copyfile "foo.txt" #f #:check #:metadata) 0)
     212 #t
     213 #;> (> (copyfile "bar.txt" #f #:check #:metadata) 0)
     214 #f
     215
     216==== pack-appledouble
     217
     218<procedure>(pack-appledouble from to . options)</procedure>
     219
     220Serialize all HFS+ metadata (extended attributes, ACLs, stat(2) data)
     221in {{FROM}} to AppleDouble file {{TO}}.  Returns false when no metadata
     222was present (and does not write a file) or true if metadata was present
     223(and a file is written).  May also throw a file error.
     224
     225Extra options are passed into {{copyfile}}; relevant ones might be
     226{{#:exclusive}}, {{#:move}} and {{#:no-follow}}, although {{#:move}}
     227and {{#:no-follow}} do not work correctly under Tiger.
     228
     229==== unpack-appledouble
     230
     231<procedure>(unpack-appledouble from to . options)</procedure>
     232
     233Unserialize all HFS+ metadata in AppleDouble file {{FROM}} to {{TO}}.
     234Always returns true, or throws an error on I/O error.
    114235
    115236=== Errors
     
    153274=== Version history
    154275
     276* 0.3 Add copyfile interface
    155277* 0.2 Add #:silent option to remove, clear-extended-attributes!
    156278* 0.1 Initial release
     
    160282BSD.
    161283
     284The 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]].
     285
Note: See TracChangeset for help on using the changeset viewer.