src/prop_array.3

   1 .\"     $NetBSD: prop_array.3,v 1.8 2008/04/30 13:10:46 martin 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 August 19, 2006
  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_equals
  54 .Nd array property collection object
  55 .Sh LIBRARY
  56 .Lb libprop
  57 .Sh SYNOPSIS
  58 .In prop/proplib.h
  59 .\"
  60 .Ft prop_array_t
  61 .Fn prop_array_create "void"
  62 .Ft prop_array_t
  63 .Fn prop_array_create_with_capacity "unsigned int capacity"
  64 .\"
  65 .Ft prop_array_t
  66 .Fn prop_array_copy "prop_array_t array"
  67 .Ft prop_array_t
  68 .Fn prop_array_copy_mutable "prop_array_t array"
  69 .\"
  70 .Ft unsigned int
  71 .Fn prop_array_capacity "prop_array_t array"
  72 .Ft unsigned int
  73 .Fn prop_array_count "prop_array_t array"
  74 .Ft bool
  75 .Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
  76 .\"
  77 .Ft prop_object_iterator_t
  78 .Fn prop_array_iterator "prop_array_t array"
  79 .\"
  80 .Ft void
  81 .Fn prop_array_make_immutable "prop_array_t array"
  82 .Ft bool
  83 .Fn prop_array_mutable "prop_array_t array"
  84 .\"
  85 .Ft prop_object_t
  86 .Fn prop_array_get "prop_array_t array" "unsigned int index"
  87 .Ft bool
  88 .Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj"
  89 .Ft bool
  90 .Fn prop_array_add "prop_array_t array" "prop_object_t obj"
  91 .Ft void
  92 .Fn prop_array_remove "prop_array_t array" "unsigned int index"
  93 .\"
  94 .Ft char *
  95 .Fn prop_array_externalize "prop_array_t array"
  96 .Ft prop_array_t
  97 .Fn prop_array_internalize "const char *xml"
  98 .\"
  99 .Ft bool
 100 .Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
 101 .Ft prop_array_t
 102 .Fn prop_array_internalize_from_file "const char *path"
 103 .\"
 104 .Ft bool
 105 .Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
 106 .Sh DESCRIPTION
 107 The
 108 .Nm prop_array
 109 family of functions operate on the array property collection object type.
 110 An array is an ordered set; an iterated array will return objects in the
 111 same order with which they were stored.
 112 .Bl -tag -width "xxxxx"
 113 .It Fn prop_array_create "void"
 114 Create an empty array.
 115 The array initially has no capacity.
 116 Returns
 117 .Dv NULL
 118 on failure.
 119 .It Fn prop_array_create_with_capacity "unsigned int capacity"
 120 Create an array with the capacity to store
 121 .Fa capacity
 122 objects.
 123 Returns
 124 .Dv NULL
 125 on failure.
 126 .It Fn prop_array_copy "prop_array_t array"
 127 Copy an array.
 128 The new array has an initial capacity equal to the number of objects stored
 129 in the array being copied.
 130 The new array contains references to the original array's objects, not
 131 copies of those objects
 132 .Pq i.e. a shallow copy is made .
 133 If the original array is immutable, the resulting array is also immutable.
 134 Returns
 135 .Dv NULL
 136 on failure.
 137 .It Fn prop_array_copy_mutable "prop_array_t array"
 138 Like
 139 .Fn prop_array_copy ,
 140 except the resulting array is always mutable.
 141 .It Fn prop_array_capacity "prop_array_t array"
 142 Returns the total capacity of the array, including objects already stored
 143 in the array.
 144 If the supplied object isn't an array, zero is returned.
 145 .It Fn prop_array_count "prop_array_t array"
 146 Returns the number of objects stored in the array.
 147 If the supplied object isn't an array, zero is returned.
 148 .It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
 149 Ensure that the array has a total capacity of
 150 .Fa capacity ,
 151 including objects already stored in the array.
 152 Returns
 153 .Dv true
 154 if the capacity of the array is greater or equal to
 155 .Fa capacity
 156 or if expansion of the array's capacity was successful
 157 and
 158 .Dv false
 159 otherwise.
 160 .It Fn prop_array_iterator "prop_array_t array"
 161 Create an iterator for the array.
 162 The array is retained by the iterator.
 163 An array iterator returns the object references stored in the array.
 164 Storing to or removing from the array invalidates any active iterators for
 165 the array.
 166 Returns
 167 .Dv NULL
 168 on failure.
 169 .It Fn prop_array_make_immutable "prop_array_t array"
 170 Make
 171 .Fa array
 172 immutable.
 173 .It Fn prop_array_mutable "prop_array_t array"
 174 Returns
 175 .Dv true
 176 if the array is mutable.
 177 .It Fn prop_array_get "prop_array_t array" "unsigned int index"
 178 Return the object stored at the array index
 179 .Fa index .
 180 Returns
 181 .Dv NULL
 182 on failure.
 183 .It Fn prop_array_set "prop_array_t array" "unsigned int index" \
 184        "prop_object_t obj"
 185 Store a reference to the object
 186 .Fa obj
 187 at the array index
 188 .Fa index .
 189 This function is not allowed to create holes in the array;
 190 the caller must either be setting the object just beyond the existing
 191 count or replacing an already existing object reference.
 192 The object will be retained by the array.
 193 If an existing object reference is being replaced, that object will be
 194 released.
 195 Returns
 196 .Dv true
 197 if storing the object was successful and
 198 .Dv false
 199 otherwise.
 200 .It Fn prop_array_add "prop_array_t array" "prop_object_t obj"
 201 Add a reference to the object
 202 .Fa obj
 203 to the array, appending to the end and growing the array's capacity if
 204 necessary.
 205 The object will be retained by the array.
 206 Returns
 207 .Dv true
 208 if storing the object was successful and
 209 .Dv false
 210 otherwise.
 211 .Pp
 212 During expansion, array's capacity is augmented by the
 213 .Dv EXPAND_STEP
 214 constant, as defined in
 215 .Pa libprop/prop_array.c
 216 file, e.g.
 217 .Pp
 218 #define EXPAND_STEP             16
 219 .It Fn prop_array_remove "prop_array_t array" "unsigned int index"
 220 Remove the reference to the object stored at array index
 221 .Fa index .
 222 The object will be released and the array compacted following
 223 the removal.
 224 .It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
 225 Returns
 226 .Dv true
 227 if the two arrays are equivalent.
 228 If at least one of the supplied objects isn't an array,
 229 .Dv false
 230 is returned.
 231 Note: Objects contained in the array are compared by value, not by reference.
 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 malloc 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 3
 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 .El
 273 .Sh SEE ALSO
 274 .Xr prop_bool 3 ,
 275 .Xr prop_data 3 ,
 276 .Xr prop_dictionary 3 ,
 277 .Xr prop_number 3 ,
 278 .Xr prop_object 3 ,
 279 .Xr prop_string 3 ,
 280 .Xr proplib 3
 281 .Sh HISTORY
 282 The
 283 .Nm proplib
 284 property container object library first appeared in
 285 .Nx 4.0 .