prop_dictionary.3: Comment out non-existant function.
[dragonfly.git] / lib / libprop / prop_dictionary.3
CommitLineData
349fb218
AH
1.\" $NetBSD: prop_dictionary.3,v 1.15 2009/12/05 10:17:17 wiz 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 ,
4bba5a94 44.\".Nm prop_dictionary_mutable ,
349fb218
AH
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"
4bba5a94
SW
88.\".Ft bool
89.\".Fn prop_dictionary_mutable "prop_dictionary_t dict"
349fb218
AH
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
135The
136.Nm prop_dictionary
137family of functions operate on the dictionary property collection object type.
138A dictionary is an unordered set of objects stored as key-value pairs.
139.Bl -tag -width "xxxxx"
140.It Fn prop_dictionary_create "void"
141Create an empty dictionary.
142The dictionary initially has no capacity.
143Returns
144.Dv NULL
145on failure.
146.It Fn prop_dictionary_create_with_capacity "unsigned int capacity"
147Create a dictionary with the capacity to store
148.Fa capacity
149objects.
150Returns
151.Dv NULL
152on failure.
153.It Fn prop_dictionary_copy "prop_dictionary_t dict"
154Copy a dictionary.
155The new dictionary has an initial capacity equal to the number of objects
156stored in the dictionary being copied.
157The new dictionary contains references to the original dictionary's objects,
158not copies of those objects
159.Pq i.e. a shallow copy is made .
160If the original dictionary is immutable, the resulting dictionary is also
161immutable.
162.It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
163Like
164.Fn prop_dictionary_copy ,
165except the resulting dictionary is always mutable.
166.It Fn prop_dictionary_count "prop_dictionary_t dict"
167Returns the number of objects stored in the dictionary.
168.It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
169 "unsigned int capacity"
170Ensure that the dictionary has a total capacity of
171.Fa capacity ,
172including objects already stored in the dictionary.
173Returns
174.Dv true
175if the capacity of the dictionary is greater or equal to
176.Fa capacity
177or if the expansion of the dictionary's capacity was successful
178and
179.Dv false
180otherwise.
181If the supplied object isn't a dictionary,
182.Dv false
183is returned.
184.It Fn prop_dictionary_iterator "prop_dictionary_t dict"
185Create an iterator for the dictionary.
186The dictionary is retained by the iterator.
187A dictionary iterator returns the key symbols used to look up objects stored
188in the dictionary; to get the object itself, a dictionary lookup using this
189key symbol must be performed.
190Storing to or removing from the dictionary invalidates any active iterators for
191the dictionary.
192Returns
193.Dv NULL
194on failure.
195.It Fn prop_dictionary_all_keys "prop_dictionary_t dict"
196Return an array of all of the dictionary key symbols
197.Pq prop_dictionary_keysym_t
198in the dictionary.
199This provides a way to iterate over the items in the dictionary while
200retaining the ability to mutate the dictionary; instead of iterating
201over the dictionary itself, iterate over the array of keys.
202The caller is responsible for releasing the array.
203Returns
204.Dv NULL
205on failure.
206.It Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
207Make
208.Fa dict
209immutable.
4bba5a94
SW
210.\".It Fn prop_dictionary_mutable "prop_dictionary_t dict"
211.\"Returns
212.\".Dv true
213.\"if the dictionary is mutable.
349fb218
AH
214.It Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
215Return the object stored in the dictionary with the key
216.Fa key .
217If no object is stored with the specified key,
218.Dv NULL
219is returned.
220.It Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
221 "prop_object_t obj"
222Store a reference to the object
223.Fa obj
224with the key
225.Fa key .
226The object will be retained by the dictionary.
227If the key already exists in the dictionary, the object associated with
228that key will be released and replaced with the new object.
229Returns
230.Dv true
231if storing the object was successful and
232.Dv false
233otherwise.
234.It Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
235Remove the reference to the object stored in the dictionary with the key
236.Fa key .
237The object will be released.
238.It Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
239 "prop_dictionary_keysym_t sym"
240Like
241.Fn prop_dictionary_get ,
242but the lookup is performed using a key symbol returned by a dictionary
243iterator.
244The results are undefined if the iterator used to obtain the key symbol
245is 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"
249Like
250.Fn prop_dictionary_set ,
251but the lookup of the object to replace is performed using a key symbol
252returned by a dictionary iterator.
253The results are undefined if the iterator used to obtain the key symbol
254is not associated with
255.Fa dict .
256.It Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
257 "prop_dictionary_keysym_t sym"
258Like
259.Fn prop_dictionary_remove ,
260but the lookup of the object to remove is performed using a key symbol
261returned by a dictionary iterator.
262The results are undefined if the iterator used to obtain the key symbol
263is not associated with
264.Fa dict .
265.It Fn prop_dictionary_equals "prop_dictionary_t dict1" \
266 "prop_dictionary_t dict2"
267Returns
268.Dv true
269if the two dictionaries are equivalent.
270Note: Objects contained in the dictionary are compared by value, not by
271reference.
272.It Fn prop_dictionary_keysym_cstring_nocopy "prop_dictionary_keysym_t keysym"
273Returns 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"
276Returns
277.Dv true
278if the two dictionary key symbols are equivalent.
279.It Fn prop_dictionary_externalize "prop_dictionary_t dict"
280Externalizes a dictionary, returning a NUL-terminated buffer containing
281the XML representation of the dictionary.
282The caller is responsible for freeing the returned buffer.
283If converting to the external representation fails for any reason,
284.Dv NULL
285is returned.
286.Pp
287In user space, the buffer is allocated using
288.Xr malloc 3 .
289In the kernel, the buffer is allocated using
290.Xr malloc 9
291using the malloc type
292.Dv M_TEMP .
293.It Fn prop_dictionary_internalize "const char *xml"
294Parse the XML representation of a property list in the NUL-terminated
295buffer
296.Fa xml
297and return the corresponding dictionary.
298Returns
299.Dv NULL
300if parsing fails for any reason.
301.It Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
302 "const char *path"
303Externalizes a dictionary and writes it to the file specified by
304.Fa path .
305The file is saved with the mode
306.Dv 0666
307as modified by the process's file creation mask
0e6f0214 308.Pq see Xr umask 2
349fb218
AH
309and is written atomically.
310Returns
311.Dv false
312if externalizing or writing the dictionary fails for any reason.
313.It Fn prop_dictionary_internalize_from_file "const char *path"
314Reads the XML property list contained in the file specified by
315.Fa path ,
316internalizes it, and returns the corresponding array.
317Returns
318.Dv NULL
319on failure.
320.It Fn prop_dictionary_externalize_to_pref "prop_dictionary_t dict" \
321 "struct plistref *pref"
322Externalizes a dictionary and packs it into the plistref specified by
323.Fa pref .
324Returns
325.Dv false
326if 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
338The
339.Nm proplib
340property container object library first appeared in
341.Nx 4.0 .