lib/libprop/prop_array.3

   1 .\"     $NetBSD: prop_array.3,v 1.13 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 October 10, 2009
  31 .Dt PROP_ARRAY 3
  32 .Os
  33 .Sh NAME
  34 .Nm prop_array ,
  35 .Nm prop_array_create ,
  36 .Nm prop_array_create_with_capacity ,
  37 .Nm prop_array_copy ,
  38 .Nm prop_array_copy_mutable ,
  39 .Nm prop_array_capacity ,
  40 .Nm prop_array_count ,
  41 .Nm prop_array_ensure_capacity ,
  42 .Nm prop_array_iterator ,
  43 .Nm prop_array_make_immutable ,
  44 .Nm prop_array_mutable ,
  45 .Nm prop_array_get ,
  46 .Nm prop_array_set ,
  47 .Nm prop_array_add ,
  48 .Nm prop_array_remove ,
  49 .Nm prop_array_externalize ,
  50 .Nm prop_array_internalize ,
  51 .Nm prop_array_externalize_to_file ,
  52 .Nm prop_array_internalize_from_file ,
  53 .Nm prop_array_externalize_to_pref ,
  54 .Nm prop_array_internalize_from_pref ,
  55 .Nm prop_array_equals
  56 .Nd array property collection object
  57 .Sh LIBRARY
  58 .Lb libprop
  59 .Sh SYNOPSIS
  60 .In libprop/proplib.h
  61 .\"
  62 .Ft prop_array_t
  63 .Fn prop_array_create "void"
  64 .Ft prop_array_t
  65 .Fn prop_array_create_with_capacity "unsigned int capacity"
  66 .\"
  67 .Ft prop_array_t
  68 .Fn prop_array_copy "prop_array_t array"
  69 .Ft prop_array_t
  70 .Fn prop_array_copy_mutable "prop_array_t array"
  71 .\"
  72 .Ft unsigned int
  73 .Fn prop_array_capacity "prop_array_t array"
  74 .Ft unsigned int
  75 .Fn prop_array_count "prop_array_t array"
  76 .Ft bool
  77 .Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
  78 .\"
  79 .Ft prop_object_iterator_t
  80 .Fn prop_array_iterator "prop_array_t array"
  81 .\"
  82 .Ft void
  83 .Fn prop_array_make_immutable "prop_array_t array"
  84 .Ft bool
  85 .Fn prop_array_mutable "prop_array_t array"
  86 .\"
  87 .Ft prop_object_t
  88 .Fn prop_array_get "prop_array_t array" "unsigned int index"
  89 .Ft bool
  90 .Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj"
  91 .Ft bool
  92 .Fn prop_array_add "prop_array_t array" "prop_object_t obj"
  93 .Ft void
  94 .Fn prop_array_remove "prop_array_t array" "unsigned int index"
  95 .\"
  96 .Ft char *
  97 .Fn prop_array_externalize "prop_array_t array"
  98 .Ft prop_array_t
  99 .Fn prop_array_internalize "const char *xml"
 100 .\"
 101 .Ft bool
 102 .Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
 103 .Ft prop_array_t
 104 .Fn prop_array_internalize_from_file "const char *path"
 105 .\"
 106 .Ft bool
 107 .Fn prop_array_externalize_to_pref "prop_array_t array" "struct plistref *pref"
 108 .Ft bool
 109 .Fn prop_array_internalize_from_pref "const struct plistref *pref" \
 110     "prop_array_t *arrayp"
 111 .\"
 112 .Ft bool
 113 .Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
 114 .Sh DESCRIPTION
 115 The
 116 .Nm prop_array
 117 family of functions operate on the array property collection object type.
 118 An array is an ordered set; an iterated array will return objects in the
 119 same order with which they were stored.
 120 .Bl -tag -width "xxxxx"
 121 .It Fn prop_array_create "void"
 122 Create an empty array.
 123 The array initially has no capacity.
 124 Returns
 125 .Dv NULL
 126 on failure.
 127 .It Fn prop_array_create_with_capacity "unsigned int capacity"
 128 Create an array with the capacity to store
 129 .Fa capacity
 130 objects.
 131 Returns
 132 .Dv NULL
 133 on failure.
 134 .It Fn prop_array_copy "prop_array_t array"
 135 Copy an array.
 136 The new array has an initial capacity equal to the number of objects stored
 137 in the array being copied.
 138 The new array contains references to the original array's objects, not
 139 copies of those objects
 140 .Pq i.e. a shallow copy is made .
 141 If the original array is immutable, the resulting array is also immutable.
 142 Returns
 143 .Dv NULL
 144 on failure.
 145 .It Fn prop_array_copy_mutable "prop_array_t array"
 146 Like
 147 .Fn prop_array_copy ,
 148 except the resulting array is always mutable.
 149 .It Fn prop_array_capacity "prop_array_t array"
 150 Returns the total capacity of the array, including objects already stored
 151 in the array.
 152 If the supplied object isn't an array, zero is returned.
 153 .It Fn prop_array_count "prop_array_t array"
 154 Returns the number of objects stored in the array.
 155 If the supplied object isn't an array, zero is returned.
 156 .It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
 157 Ensure that the array has a total capacity of
 158 .Fa capacity ,
 159 including objects already stored in the array.
 160 Returns
 161 .Dv true
 162 if the capacity of the array is greater or equal to
 163 .Fa capacity
 164 or if expansion of the array's capacity was successful
 165 and
 166 .Dv false
 167 otherwise.
 168 .It Fn prop_array_iterator "prop_array_t array"
 169 Create an iterator for the array.
 170 The array is retained by the iterator.
 171 An array iterator returns the object references stored in the array.
 172 Storing to or removing from the array invalidates any active iterators for
 173 the array.
 174 Returns
 175 .Dv NULL
 176 on failure.
 177 .It Fn prop_array_make_immutable "prop_array_t array"
 178 Make
 179 .Fa array
 180 immutable.
 181 .It Fn prop_array_mutable "prop_array_t array"
 182 Returns
 183 .Dv true
 184 if the array is mutable.
 185 .It Fn prop_array_get "prop_array_t array" "unsigned int index"
 186 Return the object stored at the array index
 187 .Fa index .
 188 Returns
 189 .Dv NULL
 190 on failure.
 191 .It Fn prop_array_set "prop_array_t array" "unsigned int index" \
 192        "prop_object_t obj"
 193 Store a reference to the object
 194 .Fa obj
 195 at the array index
 196 .Fa index .
 197 This function is not allowed to create holes in the array;
 198 the caller must either be setting the object just beyond the existing
 199 count or replacing an already existing object reference.
 200 The object will be retained by the array.
 201 If an existing object reference is being replaced, that object will be
 202 released.
 203 Returns
 204 .Dv true
 205 if storing the object was successful and
 206 .Dv false
 207 otherwise.
 208 .It Fn prop_array_add "prop_array_t array" "prop_object_t obj"
 209 Add a reference to the object
 210 .Fa obj
 211 to the array, appending to the end and growing the array's capacity if
 212 necessary.
 213 The object will be retained by the array.
 214 Returns
 215 .Dv true
 216 if storing the object was successful and
 217 .Dv false
 218 otherwise.
 219 .Pp
 220 During expansion, array's capacity is augmented by the
 221 .Dv EXPAND_STEP
 222 constant, as defined in
 223 .Pa libprop/prop_array.c
 224 file, e.g.
 225 .Pp
 226 .Dl #define     EXPAND_STEP             16
 227 .It Fn prop_array_remove "prop_array_t array" "unsigned int index"
 228 Remove the reference to the object stored at array index
 229 .Fa index .
 230 The object will be released and the array compacted following
 231 the removal.
 232 .It Fn prop_array_externalize "prop_array_t array"
 233 Externalizes an array, returning a NUL-terminated buffer containing
 234 the XML representation of the array.
 235 The caller is responsible for freeing the returned buffer.
 236 If converting to the external representation fails for any reason,
 237 .Dv NULL
 238 is returned.
 239 .Pp
 240 In user space, the buffer is allocated using
 241 .Xr malloc 3 .
 242 In the kernel, the buffer is allocated using
 243 .Xr kmalloc 9
 244 using the malloc type
 245 .Dv M_TEMP .
 246 .It Fn prop_array_internalize "const char *xml"
 247 Parse the XML representation of a property list in the NUL-terminated
 248 buffer
 249 .Fa xml
 250 and return the corresponding array.
 251 Returns
 252 .Dv NULL
 253 if parsing fails for any reason.
 254 .It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
 255 Externalizes an array and writes it to the file specified by
 256 .Fa path .
 257 The file is saved with the mode
 258 .Dv 0666
 259 as modified by the process's file creation mask
 260 .Pq see Xr umask 2
 261 and is written atomically.
 262 Returns
 263 .Dv false
 264 if externalizing or writing the array fails for any reason.
 265 .It Fn prop_array_internalize_from_file "const char *path"
 266 Reads the XML property list contained in the file specified by
 267 .Fa path ,
 268 internalizes it, and returns the corresponding array.
 269 Returns
 270 .Dv NULL
 271 on failure.
 272 .It Fn prop_array_externalize_to_pref "prop_array_t array" \
 273     "struct plistref *pref"
 274 Externalizes an array and packs it into the plistref specified by
 275 .Fa pref .
 276 Returns
 277 .Dv false
 278 if externalizing the array fails for any reason.
 279 .It Fn prop_array_internalize_from_pref "const struct plistref *pref" \
 280     "prop_array_t *arrayp"
 281 Reads the plistref specified by
 282 .Fa pref ,
 283 internalizes it, and returns the corresponding array.
 284 Returns
 285 .Dv false
 286 if internalizing or writing the array fails for any reason.
 287 .It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
 288 Returns
 289 .Dv true
 290 if the two arrays are equivalent.
 291 If at least one of the supplied objects isn't an array,
 292 .Dv false
 293 is returned.
 294 Note: Objects contained in the array are compared by value, not by reference.
 295 .El
 296 .Sh SEE ALSO
 297 .Xr prop_bool 3 ,
 298 .Xr prop_data 3 ,
 299 .Xr prop_dictionary 3 ,
 300 .Xr prop_number 3 ,
 301 .Xr prop_object 3 ,
 302 .Xr prop_string 3 ,
 303 .Xr proplib 3
 304 .Sh HISTORY
 305 The
 306 .Nm proplib
 307 property container object library first appeared in
 308 .Nx 4.0 .