| blob | 257b3c1df9cfd5bbad16f55df3099093b8967b6c |
1 .\" $NetBSD: prop_dictionary.3,v 1.14 2009/10/10 18:06:54 bad 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_equals ,
57 .Nm prop_dictionary_keysym_cstring_nocopy ,
58 .Nm prop_dictionary_keysym_equals
59 .Nd dictionary property collection object
60 .Sh LIBRARY
61 .Lb libprop
62 .Sh SYNOPSIS
63 .In prop/proplib.h
64 .\"
65 .Ft prop_dictionary_t
66 .Fn prop_dictionary_create "void"
67 .Ft prop_dictionary_t
68 .Fn prop_dictionary_create_with_capacity "unsigned int capacity"
69 .\"
70 .Ft prop_dictionary_t
71 .Fn prop_dictionary_copy "prop_dictionary_t dict"
72 .Ft prop_dictionary_t
73 .Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
74 .\"
75 .Ft unsigned int
76 .Fn prop_dictionary_count "prop_dictionary_t dict"
77 .Ft bool
78 .Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
79 "unsigned int capacity"
80 .\"
81 .Ft prop_object_iterator_t
82 .Fn prop_dictionary_iterator "prop_dictionary_t dict"
83 .Ft prop_array_t
84 .Fn prop_dictionary_all_keys "prop_dictionary_t dict"
85 .\"
86 .Ft void
87 .Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
88 .Ft bool
89 .Fn prop_dictionary_mutable "prop_dictionary_t dict"
90 .\"
91 .Ft prop_object_t
92 .Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
93 .Ft bool
94 .Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
95 "prop_object_t obj"
96 .Ft void
97 .Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
98 .\"
99 .Ft prop_object_t
100 .Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
101 "prop_dictionary_keysym_t keysym"
102 .Ft bool
103 .Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
104 "prop_dictionary_keysym_t keysym" "prop_object_t obj"
105 .Ft void
106 .Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
107 "prop_dictionary_keysym_t keysym"
108 .\"
109 .Ft bool
110 .Fn prop_dictionary_equals "prop_dictionary_t dict1" "prop_dictionary_t dict2"
111 .\"
112 .Ft const char *
113 .Fn prop_dictionary_keysym_cstring_nocopy "prop_dictionary_keysym_t sym"
114 .\"
115 .Ft bool
116 .Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
117 "prop_dictionary_keysym_t keysym2"
118 .\"
119 .Ft char *
120 .Fn prop_dictionary_externalize "prop_dictionary_t dict"
121 .Ft prop_dictionary_t
122 .Fn prop_dictionary_internalize "const char *xml"
123 .\"
124 .Ft bool
125 .Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
126 "const char *path"
127 .Ft prop_dictionary_t
128 .Fn prop_dictionary_internalize_from_file "const char *path"
129 .\"
130 .Ft bool
131 .Fn prop_dictionary_externalize_to_pref "prop_dictionary_t dict" \
132 "struct plistref *pref"
133 .\"
134 .Sh DESCRIPTION
135 The
136 .Nm prop_dictionary
137 family of functions operate on the dictionary property collection object type.
138 A dictionary is an unordered set of objects stored as key-value pairs.
139 .Bl -tag -width "xxxxx"
140 .It Fn prop_dictionary_create "void"
141 Create an empty dictionary.
142 The dictionary initially has no capacity.
143 Returns
144 .Dv NULL
145 on failure.
146 .It Fn prop_dictionary_create_with_capacity "unsigned int capacity"
147 Create a dictionary with the capacity to store
148 .Fa capacity
149 objects.
150 Returns
151 .Dv NULL
152 on failure.
153 .It Fn prop_dictionary_copy "prop_dictionary_t dict"
154 Copy a dictionary.
155 The new dictionary has an initial capacity equal to the number of objects
156 stored in the dictionary being copied.
157 The new dictionary contains references to the original dictionary's objects,
158 not copies of those objects
159 .Pq i.e. a shallow copy is made .
160 If the original dictionary is immutable, the resulting dictionary is also
161 immutable.
162 .It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
163 Like
164 .Fn prop_dictionary_copy ,
165 except the resulting dictionary is always mutable.
166 .It Fn prop_dictionary_count "prop_dictionary_t dict"
167 Returns the number of objects stored in the dictionary.
168 .It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
169 "unsigned int capacity"
170 Ensure that the dictionary has a total capacity of
171 .Fa capacity ,
172 including objects already stored in the dictionary.
173 Returns
174 .Dv true
175 if the capacity of the dictionary is greater or equal to
176 .Fa capacity
177 or if the expansion of the dictionary's capacity was successful
178 and
179 .Dv false
180 otherwise.
181 If the supplied object isn't a dictionary,
182 .Dv false
183 is returned.
184 .It Fn prop_dictionary_iterator "prop_dictionary_t dict"
185 Create an iterator for the dictionary.
186 The dictionary is retained by the iterator.
187 A dictionary iterator returns the key symbols used to look up objects stored
188 in the dictionary; to get the object itself, a dictionary lookup using this
189 key symbol must be performed.
190 Storing to or removing from the dictionary invalidates any active iterators for
191 the dictionary.
192 Returns
193 .Dv NULL
194 on failure.
195 .It Fn prop_dictionary_all_keys "prop_dictionary_t dict"
196 Return an array of all of the dictionary key symbols
197 .Pq prop_dictionary_keysym_t
198 in the dictionary.
199 This provides a way to iterate over the items in the dictionary while
200 retaining the ability to mutate the dictionary; instead of iterating
201 over the dictionary itself, iterate over the array of keys.
202 The caller is responsible for releasing the array.
203 Returns
204 .Dv NULL
205 on failure.
206 .It Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
207 Make
208 .Fa dict
209 immutable.
210 .It Fn prop_dictionary_mutable "prop_dictionary_t dict"
211 Returns
212 .Dv true
213 if the dictionary is mutable.
214 .It Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
215 Return the object stored in the dictionary with the key
216 .Fa key .
217 If no object is stored with the specified key,
218 .Dv NULL
219 is returned.
220 .It Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
221 "prop_object_t obj"
222 Store a reference to the object
223 .Fa obj
224 with the key
225 .Fa key .
226 The object will be retained by the dictionary.
227 If the key already exists in the dictionary, the object associated with
228 that key will be released and replaced with the new object.
229 Returns
230 .Dv true
231 if storing the object was successful and
232 .Dv false
233 otherwise.
234 .It Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
235 Remove the reference to the object stored in the dictionary with the key
236 .Fa key .
237 The object will be released.
238 .It Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
239 "prop_dictionary_keysym_t sym"
240 Like
241 .Fn prop_dictionary_get ,
242 but the lookup is performed using a key symbol returned by a dictionary
243 iterator.
244 The results are undefined if the iterator used to obtain the key symbol
245 is not associated with
246 .Fa dict .
247 .It Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
248 "prop_dictionary_keysym_t sym" "prop_object_t obj"
249 Like
250 .Fn prop_dictionary_set ,
251 but the lookup of the object to replace is performed using a key symbol
252 returned by a dictionary iterator.
253 The results are undefined if the iterator used to obtain the key symbol
254 is not associated with
255 .Fa dict .
256 .It Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
257 "prop_dictionary_keysym_t sym"
258 Like
259 .Fn prop_dictionary_remove ,
260 but the lookup of the object to remove is performed using a key symbol
261 returned by a dictionary iterator.
262 The results are undefined if the iterator used to obtain the key symbol
263 is not associated with
264 .Fa dict .
265 .It Fn prop_dictionary_equals "prop_dictionary_t dict1" \
266 "prop_dictionary_t dict2"
267 Returns
268 .Dv true
269 if the two dictionaries are equivalent.
270 Note: Objects contained in the dictionary are compared by value, not by
271 reference.
272 .It Fn prop_dictionary_keysym_cstring_nocopy "prop_dictionary_keysym_t keysym"
273 Returns an immutable reference to the dictionary key symbol's string value.
274 .It Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
275 "prop_dictionary_keysym_t keysym2"
276 Returns
277 .Dv true
278 if the two dictionary key symbols are equivalent.
279 .It Fn prop_dictionary_externalize "prop_dictionary_t dict"
280 Externalizes a dictionary, returning a NUL-terminated buffer containing
281 the XML representation of the dictionary.
282 The caller is responsible for freeing the returned buffer.
283 If converting to the external representation fails for any reason,
284 .Dv NULL
285 is returned.
286 .Pp
287 In user space, the buffer is allocated using
288 .Xr malloc 3 .
289 In the kernel, the buffer is allocated using
290 .Xr malloc 9
291 using the malloc type
292 .Dv M_TEMP .
293 .It Fn prop_dictionary_internalize "const char *xml"
294 Parse the XML representation of a property list in the NUL-terminated
295 buffer
296 .Fa xml
297 and return the corresponding dictionary.
298 Returns
299 .Dv NULL
300 if parsing fails for any reason.
301 .It Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
302 "const char *path"
303 Externalizes a dictionary and writes it to the file specified by
304 .Fa path .
305 The file is saved with the mode
306 .Dv 0666
307 as modified by the process's file creation mask
308 .Pq see Xr umask 3
309 and is written atomically.
310 Returns
311 .Dv false
312 if externalizing or writing the dictionary fails for any reason.
313 .It Fn prop_dictionary_internalize_from_file "const char *path"
314 Reads the XML property list contained in the file specified by
315 .Fa path ,
316 internalizes it, and returns the corresponding array.
317 Returns
318 .Dv NULL
319 on failure.
320 .It Fn prop_dictionary_externalize_to_pref "prop_dictionary_t dict" \
321 "struct plistref *pref"
322 Externalizes a dictionary and packs it into the plistref specified by
323 .Fa pref .
324 Returns
325 .Dv false
326 if externalizing the dictionary fails for any reason.
327 .El
328 .Sh SEE ALSO
329 .Xr prop_array 3 ,
330 .Xr prop_bool 3 ,
331 .Xr prop_data 3 ,
332 .Xr prop_dictionary_util 3 ,
333 .Xr prop_number 3 ,
334 .Xr prop_object 3 ,
335 .Xr prop_string 3 ,
336 .Xr proplib 3
337 .Sh HISTORY
338 The
339 .Nm proplib
340 property container object library first appeared in
341 .Nx 4.0 .