lib/libprop/prop_dictionary.3

   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 .