man/prop_dictionary.3

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