lib/libprop/prop_array.3

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