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