source: project/wiki/eggref/4/hfs+

Last change on this file was 15279, checked in by Jim Ursetto, 11 years ago

hfs+: update wiki for v0.3

File size: 9.6 KB
Line 
1== hfs+
2
3[[toc:]]
4
5=== Synopsis
6
7'''hfs+''' is a interface to the HFS+ filesystem on Mac OS X 10.4 and above.
8
9The current implementation provides access to HFS+ extended
10attributes, including resource forks.  It also implements an
11interface to {{copyfile(3)}}.
12
13=== Interface
14
15==== Overview
16
17All calls taking a {{FILE}} argument accept either a filename or an
18open POSIX file descriptor.
19
20All calls taking an {{ATTRIBUTE}} argument accept either a string
21or a symbol.
22
23All extended attribute calls allow the following options:
24
25<nowiki>
26<table>
27<tr><td>#:no-follow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
28</table>
29</nowiki>
30
31==== list-extended-attributes
32
33<procedure>(list-extended-attributes file . options)</procedure>
34
35List extended attribute names of {{FILE}}.
36
37Returns a list containing one string per attribute name.
38
39  (list-extended-attributes "examples.scm" #:no-follow)
40  ; => ("com.apple.FinderInfo" "com.apple.ResourceFork")
41
42==== get-extended-attribute
43
44<procedure>(get-extended-attribute file attribute . options)</procedure>
45
46Get the value of extended attribute {{ATTRIBUTE}} from {{FILE}}.
47
48Returns a string representing the value.  The string may contain binary data.
49
50Returns {{#f}} if the attribute does not exist.
51
52==== set-extended-attribute!
53
54<procedure>(set-extended-attribute! file attribute value . options)</procedure>
55
56Set extended attribute {{ATTRIBUTE}} on {{FILE}} to {{VALUE}}, and return
57an unspecified value.
58
59{{VALUE}} may be a string or a blob.
60
61In addition to {{#:no-follow}}, {{set-extended-attribute!}} allows the
62following two mutually-exclusive options:
63
64<nowiki>
65<table>
66<tr><td>#:create</td><td>Raise error if attribute exists.</td></tr>
67<tr><td>#:replace</td><td>Raise error if attribute does not exist.</td></tr>
68</table>
69</nowiki>
70
71If neither option is specified, existing attribute values are silently
72overwritten.
73
74 (set-extended-attribute! "examples.scm" 'org.callcc "courtesy of Chicken")
75 (get-extended-attribute "examples.scm" 'org.callcc)
76 ; => "courtesy of Chicken"
77
78==== remove-extended-attribute!
79
80<procedure>(remove-extended-attribute! file attribute . options)</procedure>
81
82Remove extended attribute {{ATTRIBUTE}} from {{FILE}}.  By default, if
83{{ATTRIBUTE}} does not exist, an error is signaled.
84
85{{remove-extended-attribute!}} also accepts the following options:
86
87<nowiki>
88<table>
89<tr><td>#:silent</td><td>Do not raise an error if the attribute is missing.</td></tr>
90</table>
91</nowiki>
92
93The #:silent option is useful if, for example, you wish to truncate
94a resource fork but are not sure if one is already present.  See below
95for 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.
162
163=== Utilities
164
165==== get-extended-attributes
166
167<procedure>(get-extended-attributes file . options)</procedure>
168
169Returns an alist mapping attribute names (symbols) to values (strings).
170
171 (get-extended-attributes "examples.scm")
172 ;=> ((com.apple.FinderInfo . "TEXTEMAx")
173      (com.apple.ResourceFork . "courtesy of Chicken")
174      (org.callcc . "courtesy of Chicken"))
175
176==== clear-extended-attributes!
177
178<procedure>(clear-extended-attributes! file . options)</procedure>
179
180Remove 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.
235
236=== Errors
237
238If the system API returns an unrecoverable error, a Scheme error will
239be raised.  The exception is of type {{(exn file hfs+)}}.
240
241=== Notes
242
243==== Resource forks
244
245Special care is required when writing resource fork data.  OS X will
246''not'' truncate an existing resource fork if you write a shorter
247value, so you must remove the resource fork prior to writing.
248
249Incorrect example:
250
251 $ echo -n "courtesy of the command-line" > examples.scm/rsrc
252 $ csi -q -R hfs+ <<EOF
253 (set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
254                          "courtesy of Chicken")
255 EOF
256 $ cat examples.scm/rsrc ; echo
257 courtesy of Chickenmand-line
258
259Correct example:
260
261 $ echo -n "courtesy of the command-line" > examples.scm/rsrc
262 $ csi -q -R hfs+ <<EOF
263 (remove-extended-attribute! "examples.scm" 'com.apple.ResourceFork #:silent)
264 (set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
265                          "courtesy of Chicken" #:create)
266 EOF
267 $ cat examples.scm/rsrc ; echo
268 courtesy of Chicken
269
270=== Author
271
272Jim Ursetto
273
274=== Version history
275
276* 0.3 Add copyfile interface
277* 0.2 Add #:silent option to remove, clear-extended-attributes!
278* 0.1 Initial release
279
280=== License
281
282BSD.
283
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 TracBrowser for help on using the repository browser.