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

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

hfs+ wiki doc

File size: 4.2 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.
11
12=== Interface
13
14==== Overview
15
16All calls taking a {{FILE}} argument accept either a filename or an
17open POSIX file descriptor.
18
19All calls taking an {{ATTRIBUTE}} argument accept either a string
20or a symbol.
21
22All extended attribute calls allow the following options:
23
24<nowiki>
25<table>
26<tr><td>#:nofollow</td><td>Do not follow symlinks; operate on the symlink itself.</td></tr>
27</table>
28</nowiki>
29
30==== list-extended-attributes
31
32<procedure>(list-extended-attributes file . options)</procedure>
33
34List extended attribute names of {{FILE}}.
35
36Returns a list containing one string per attribute name.
37
38  (list-extended-attributes "examples.scm" #:nofollow)
39  ; => ("com.apple.FinderInfo" "com.apple.ResourceFork")
40
41==== get-extended-attribute
42
43<procedure>(get-extended-attribute file attribute . options)</procedure>
44
45Get the value of extended attribute {{ATTRIBUTE}} from {{FILE}}.
46
47Returns a string representing the value.  The string may contain binary data.
48
49Returns {{#f}} if the attribute does not exist.
50
51==== set-extended-attribute!
52
53<procedure>(set-extended-attribute! file attribute value . options)</procedure>
54
55Set extended attribute {{ATTRIBUTE}} on {{FILE}} to {{VALUE}}, and return
56an unspecified value.
57
58{{VALUE}} may be a string or a blob.
59
60In addition to {{#:nofollow}}, {{set-extended-attribute!}} allows the
61following two mutually-exclusive options:
62
63<nowiki>
64<table>
65<tr><td>#:create</td><td>Raise error if attribute exists.</td></tr>
66<tr><td>#:replace</td><td>Raise error if attribute does not exist.</td></tr>
67</table>
68</nowiki>
69
70If neither option is specified, existing attribute values are silently
71overwritten.
72
73 (set-extended-attribute! "examples.scm" 'org.callcc "courtesy of Chicken")
74 (get-extended-attribute "examples.scm" 'org.callcc)
75 ; => "courtesy of Chicken"
76
77==== remove-extended-attribute!
78
79<procedure>(remove-extended-attribute! file attribute . options)</procedure>
80
81Remove extended attribute {{ATTRIBUTE}} from {{FILE}}.  By default, if
82{{ATTRIBUTE}} does not exist, an error is signaled.
83
84{{remove-extended-attribute!}} also accepts the following options:
85
86<nowiki>
87<table>
88<tr><td>#:silent</td><td>Do not raise an error if the attribute is missing.</td></tr>
89</table>
90</nowiki>
91
92The #:silent option is useful if, for example, you wish to truncate
93a resource fork but are not sure if one is already present.  See below
94for an example.
95
96=== Utilities
97
98==== get-extended-attributes
99
100<procedure>(get-extended-attributes file . options)</procedure>
101
102Returns an alist mapping attribute names (symbols) to values (strings).
103
104 (get-extended-attributes "examples.scm")
105 ;=> ((com.apple.FinderInfo . "TEXTEMAx")
106      (com.apple.ResourceFork . "courtesy of Chicken")
107      (org.callcc . "courtesy of Chicken"))
108
109==== clear-extended-attributes!
110
111<procedure>(clear-extended-attributes! file . options)</procedure>
112
113Remove all extended attributes from {{FILE}}.
114
115=== Errors
116
117If the system API returns an unrecoverable error, a Scheme error will
118be raised.  The exception is of type {{(exn file hfs+)}}.
119
120=== Notes
121
122==== Resource forks
123
124Special care is required when writing resource fork data.  OS X will
125''not'' truncate an existing resource fork if you write a shorter
126value, so you must remove the resource fork prior to writing.
127
128Incorrect example:
129
130 $ echo -n "courtesy of the command-line" > examples.scm/rsrc
131 $ csi -q -R hfs+ <<EOF
132 (set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
133                          "courtesy of Chicken")
134 EOF
135 $ cat examples.scm/rsrc ; echo
136 courtesy of Chickenmand-line
137
138Correct example:
139
140 $ echo -n "courtesy of the command-line" > examples.scm/rsrc
141 $ csi -q -R hfs+ <<EOF
142 (remove-extended-attribute! "examples.scm" 'com.apple.ResourceFork #:silent)
143 (set-extended-attribute! "examples.scm" 'com.apple.ResourceFork
144                          "courtesy of Chicken" #:create)
145 EOF
146 $ cat examples.scm/rsrc ; echo
147 courtesy of Chicken
148
149=== Author
150
151Jim Ursetto
152
153=== Version history
154
155* 0.2 Add #:silent option to remove, clear-extended-attributes!
156* 0.1 Initial release
157
158=== License
159
160BSD.
161
Note: See TracBrowser for help on using the repository browser.