lib/libprop/prop_dictionary.3

   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
 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 2
 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 .