| blob | 5756736a19567c956f7e6862790290fd75c1220e |
1 .\" $NetBSD: prop_dictionary.3,v 1.18 2011/09/30 22:08:18 jym Exp $
2 .\"
3 .\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Jason R. Thorpe.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd December 5, 2009
31 .Dt PROP_DICTIONARY 3
32 .Os
33 .Sh NAME
34 .Nm prop_dictionary ,
35 .Nm prop_dictionary_create ,
36 .Nm prop_dictionary_create_with_capacity ,
37 .Nm prop_dictionary_copy ,
38 .Nm prop_dictionary_copy_mutable ,
39 .Nm prop_dictionary_count ,
40 .Nm prop_dictionary_ensure_capacity ,
41 .Nm prop_dictionary_iterator ,
42 .Nm prop_dictionary_all_keys ,
43 .Nm prop_dictionary_make_immutable ,
44 .\".Nm prop_dictionary_mutable ,
45 .Nm prop_dictionary_get ,
46 .Nm prop_dictionary_set ,
47 .Nm prop_dictionary_remove ,
48 .Nm prop_dictionary_get_keysym ,
49 .Nm prop_dictionary_set_keysym ,
50 .Nm prop_dictionary_remove_keysym ,
51 .Nm prop_dictionary_externalize ,
52 .Nm prop_dictionary_internalize ,
53 .Nm prop_dictionary_externalize_to_file ,
54 .Nm prop_dictionary_internalize_from_file ,
55 .Nm prop_dictionary_externalize_to_pref ,
56 .Nm prop_dictionary_internalize_from_pref ,
57 .Nm prop_dictionary_equals ,
58 .Nm prop_dictionary_keysym_cstring_nocopy ,
59 .Nm prop_dictionary_keysym_equals
60 .Nd dictionary property collection object
61 .Sh LIBRARY
62 .Lb libprop
63 .Sh SYNOPSIS
64 .In libprop/proplib.h
65 .\"
66 .Ft prop_dictionary_t
67 .Fn prop_dictionary_create "void"
68 .Ft prop_dictionary_t
69 .Fn prop_dictionary_create_with_capacity "unsigned int capacity"
70 .\"
71 .Ft prop_dictionary_t
72 .Fn prop_dictionary_copy "prop_dictionary_t dict"
73 .Ft prop_dictionary_t
74 .Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
75 .\"
76 .Ft unsigned int
77 .Fn prop_dictionary_count "prop_dictionary_t dict"
78 .Ft bool
79 .Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
80 "unsigned int capacity"
81 .\"
82 .Ft prop_object_iterator_t
83 .Fn prop_dictionary_iterator "prop_dictionary_t dict"
84 .Ft prop_array_t
85 .Fn prop_dictionary_all_keys "prop_dictionary_t dict"
86 .\"
87 .Ft void
88 .Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
89 .\".Ft bool
90 .\".Fn prop_dictionary_mutable "prop_dictionary_t dict"
91 .\"
92 .Ft prop_object_t
93 .Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
94 .Ft bool
95 .Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
96 "prop_object_t obj"
97 .Ft void
98 .Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
99 .\"
100 .Ft prop_object_t
101 .Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
102 "prop_dictionary_keysym_t keysym"
103 .Ft bool
104 .Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
105 "prop_dictionary_keysym_t keysym" "prop_object_t obj"
106 .Ft void
107 .Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
108 "prop_dictionary_keysym_t keysym"
109 .\"
110 .Ft bool
111 .Fn prop_dictionary_equals "prop_dictionary_t dict1" "prop_dictionary_t dict2"
112 .\"
113 .Ft const char *
114 .Fn prop_dictionary_keysym_cstring_nocopy "prop_dictionary_keysym_t sym"
115 .\"
116 .Ft bool
117 .Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
118 "prop_dictionary_keysym_t keysym2"
119 .\"
120 .Ft char *
121 .Fn prop_dictionary_externalize "prop_dictionary_t dict"
122 .Ft prop_dictionary_t
123 .Fn prop_dictionary_internalize "const char *xml"
124 .\"
125 .Ft bool
126 .Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
127 "const char *path"
128 .Ft prop_dictionary_t
129 .Fn prop_dictionary_internalize_from_file "const char *path"
130 .\"
131 .Ft bool
132 .Fn prop_dictionary_externalize_to_pref "prop_dictionary_t dict" \
133 "struct plistref *pref"
134 .Ft bool
135 .Fn prop_dictionary_internalize_from_pref "const struct plistref *pref" \
136 "prop_dictionary_t *dictp"
137 .\"
138 .Sh DESCRIPTION
139 The
140 .Nm prop_dictionary
141 family of functions operate on the dictionary property collection object type.
142 A dictionary is an unordered set of objects stored as key-value pairs.
143 .Bl -tag -width "xxxxx"
144 .It Fn prop_dictionary_create "void"
145 Create an empty dictionary.
146 The dictionary initially has no capacity.
147 Returns
148 .Dv NULL
149 on failure.
150 .It Fn prop_dictionary_create_with_capacity "unsigned int capacity"
151 Create a dictionary with the capacity to store
152 .Fa capacity
153 objects.
154 Returns
155 .Dv NULL
156 on failure.
157 .It Fn prop_dictionary_copy "prop_dictionary_t dict"
158 Copy a dictionary.
159 The new dictionary has an initial capacity equal to the number of objects
160 stored in the dictionary being copied.
161 The new dictionary contains references to the original dictionary's objects,
162 not copies of those objects
163 .Pq i.e. a shallow copy is made .
164 If the original dictionary is immutable, the resulting dictionary is also
165 immutable.
166 .It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
167 Like
168 .Fn prop_dictionary_copy ,
169 except the resulting dictionary is always mutable.
170 .It Fn prop_dictionary_count "prop_dictionary_t dict"
171 Returns the number of objects stored in the dictionary.
172 .It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
173 "unsigned int capacity"
174 Ensure that the dictionary has a total capacity of
175 .Fa capacity ,
176 including objects already stored in the dictionary.
177 Returns
178 .Dv true
179 if the capacity of the dictionary is greater or equal to
180 .Fa capacity
181 or if the expansion of the dictionary's capacity was successful
182 and
183 .Dv false
184 otherwise.
185 If the supplied object isn't a dictionary,
186 .Dv false
187 is returned.
188 .It Fn prop_dictionary_iterator "prop_dictionary_t dict"
189 Create an iterator for the dictionary.
190 The dictionary is retained by the iterator.
191 A dictionary iterator returns the key symbols used to look up objects stored
192 in the dictionary; to get the object itself, a dictionary lookup using this
193 key symbol must be performed.
194 Storing to or removing from the dictionary invalidates any active iterators for
195 the dictionary.
196 Returns
197 .Dv NULL
198 on failure.
199 .It Fn prop_dictionary_all_keys "prop_dictionary_t dict"
200 Return an array of all of the dictionary key symbols
201 .Pq prop_dictionary_keysym_t
202 in the dictionary.
203 This provides a way to iterate over the items in the dictionary while
204 retaining the ability to mutate the dictionary; instead of iterating
205 over the dictionary itself, iterate over the array of keys.
206 The caller is responsible for releasing the array.
207 Returns
208 .Dv NULL
209 on failure.
210 .It Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
211 Make
212 .Fa dict
213 immutable.
214 .\".It Fn prop_dictionary_mutable "prop_dictionary_t dict"
215 .\"Returns
216 .\".Dv true
217 .\"if the dictionary is mutable.
218 .It Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
219 Return the object stored in the dictionary with the key
220 .Fa key .
221 If no object is stored with the specified key,
222 .Dv NULL
223 is returned.
224 .It Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
225 "prop_object_t obj"
226 Store a reference to the object
227 .Fa obj
228 with the key
229 .Fa key .
230 The object will be retained by the dictionary.
231 If the key already exists in the dictionary, the object associated with
232 that key will be released and replaced with the new object.
233 Returns
234 .Dv true
235 if storing the object was successful and
236 .Dv false
237 otherwise.
238 .It Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
239 Remove the reference to the object stored in the dictionary with the key
240 .Fa key .
241 The object will be released.
242 .It Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
243 "prop_dictionary_keysym_t sym"
244 Like
245 .Fn prop_dictionary_get ,
246 but the lookup is performed using a key symbol returned by a dictionary
247 iterator.
248 The results are undefined if the iterator used to obtain the key symbol
249 is not associated with
250 .Fa dict .
251 .It Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
252 "prop_dictionary_keysym_t sym" "prop_object_t obj"
253 Like
254 .Fn prop_dictionary_set ,
255 but the lookup of the object to replace is performed using a key symbol
256 returned by a dictionary iterator.
257 The results are undefined if the iterator used to obtain the key symbol
258 is not associated with
259 .Fa dict .
260 .It Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
261 "prop_dictionary_keysym_t sym"
262 Like
263 .Fn prop_dictionary_remove ,
264 but the lookup of the object to remove is performed using a key symbol
265 returned by a dictionary iterator.
266 The results are undefined if the iterator used to obtain the key symbol
267 is not associated with
268 .Fa dict .
269 .It Fn prop_dictionary_equals "prop_dictionary_t dict1" \
270 "prop_dictionary_t dict2"
271 Returns
272 .Dv true
273 if the two dictionaries are equivalent.
274 Note: Objects contained in the dictionary are compared by value, not by
275 reference.
276 .It Fn prop_dictionary_keysym_cstring_nocopy "prop_dictionary_keysym_t keysym"
277 Returns an immutable reference to the dictionary key symbol's string value.
278 .It Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
279 "prop_dictionary_keysym_t keysym2"
280 Returns
281 .Dv true
282 if the two dictionary key symbols are equivalent.
283 .It Fn prop_dictionary_externalize "prop_dictionary_t dict"
284 Externalizes a dictionary, returning a NUL-terminated buffer containing
285 the XML representation of the dictionary.
286 The caller is responsible for freeing the returned buffer.
287 If converting to the external representation fails for any reason,
288 .Dv NULL
289 is returned.
290 .Pp
291 In user space, the buffer is allocated using
292 .Xr malloc 3 .
293 In the kernel, the buffer is allocated using
294 .Xr kmalloc 9
295 using the malloc type
296 .Dv M_TEMP .
297 .It Fn prop_dictionary_internalize "const char *xml"
298 Parse the XML representation of a property list in the NUL-terminated
299 buffer
300 .Fa xml
301 and return the corresponding dictionary.
302 Returns
303 .Dv NULL
304 if parsing fails for any reason.
305 .It Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
306 "const char *path"
307 Externalizes a dictionary and writes it to the file specified by
308 .Fa path .
309 The file is saved with the mode
310 .Dv 0666
311 as modified by the process's file creation mask
312 .Pq see Xr umask 2
313 and is written atomically.
314 Returns
315 .Dv false
316 if externalizing or writing the dictionary fails for any reason.
317 .It Fn prop_dictionary_internalize_from_file "const char *path"
318 Reads the XML property list contained in the file specified by
319 .Fa path ,
320 internalizes it, and returns the corresponding dictionary.
321 Returns
322 .Dv NULL
323 on failure.
324 .It Fn prop_dictionary_externalize_to_pref "prop_dictionary_t dict" \
325 "struct plistref *pref"
326 Externalizes a dictionary and packs it into the plistref specified by
327 .Fa pref .
328 Returns
329 .Dv false
330 if externalizing the dictionary fails for any reason.
331 .It Fn prop_dictionary_internalize_from_pref "const struct plistref *pref" \
332 "prop_dictionary_t *dictp"
333 Reads the plistref specified by
334 .Fa pref ,
335 internalizes it, and returns the corresponding dictionary.
336 Returns
337 .Dv false
338 if internalizing or writing the dictionary fails for any reason.
339 .El
340 .Sh SEE ALSO
341 .Xr prop_array 3 ,
342 .Xr prop_bool 3 ,
343 .Xr prop_data 3 ,
344 .Xr prop_dictionary_util 3 ,
345 .Xr prop_number 3 ,
346 .Xr prop_object 3 ,
347 .Xr prop_string 3 ,
348 .Xr proplib 3
349 .Sh HISTORY
350 The
351 .Nm proplib
352 property container object library first appeared in
353 .Nx 4.0 .