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 , 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 libprop/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 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. 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" 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 308.Pq see Xr umask 2 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 . 342