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