1.\" $NetBSD: prop_array.3,v 1.7 2008/01/21 22:15:03 christos 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd August 19, 2006 38.Dt PROP_ARRAY 3 39.Os 40.Sh NAME 41.Nm prop_array , 42.Nm prop_array_create , 43.Nm prop_array_create_with_capacity , 44.Nm prop_array_copy , 45.Nm prop_array_copy_mutable , 46.Nm prop_array_capacity , 47.Nm prop_array_count , 48.Nm prop_array_ensure_capacity , 49.Nm prop_array_iterator , 50.Nm prop_array_make_immutable , 51.Nm prop_array_mutable , 52.Nm prop_array_get , 53.Nm prop_array_set , 54.Nm prop_array_add , 55.Nm prop_array_remove , 56.Nm prop_array_externalize , 57.Nm prop_array_internalize , 58.Nm prop_array_externalize_to_file , 59.Nm prop_array_internalize_from_file , 60.Nm prop_array_equals 61.Nd array property collection object 62.Sh LIBRARY 63.Lb libprop 64.Sh SYNOPSIS 65.In prop/proplib.h 66.\" 67.Ft prop_array_t 68.Fn prop_array_create "void" 69.Ft prop_array_t 70.Fn prop_array_create_with_capacity "unsigned int capacity" 71.\" 72.Ft prop_array_t 73.Fn prop_array_copy "prop_array_t array" 74.Ft prop_array_t 75.Fn prop_array_copy_mutable "prop_array_t array" 76.\" 77.Ft unsigned int 78.Fn prop_array_capacity "prop_array_t array" 79.Ft unsigned int 80.Fn prop_array_count "prop_array_t array" 81.Ft bool 82.Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 83.\" 84.Ft prop_object_iterator_t 85.Fn prop_array_iterator "prop_array_t array" 86.\" 87.Ft void 88.Fn prop_array_make_immutable "prop_array_t array" 89.Ft bool 90.Fn prop_array_mutable "prop_array_t array" 91.\" 92.Ft prop_object_t 93.Fn prop_array_get "prop_array_t array" "unsigned int index" 94.Ft bool 95.Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj" 96.Ft bool 97.Fn prop_array_add "prop_array_t array" "prop_object_t obj" 98.Ft void 99.Fn prop_array_remove "prop_array_t array" "unsigned int index" 100.\" 101.Ft char * 102.Fn prop_array_externalize "prop_array_t array" 103.Ft prop_array_t 104.Fn prop_array_internalize "const char *xml" 105.\" 106.Ft bool 107.Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" 108.Ft prop_array_t 109.Fn prop_array_internalize_from_file "const char *path" 110.\" 111.Ft bool 112.Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 113.Sh DESCRIPTION 114The 115.Nm prop_array 116family of functions operate on the array property collection object type. 117An array is an ordered set; an iterated array will return objects in the 118same order with which they were stored. 119.Bl -tag -width "xxxxx" 120.It Fn prop_array_create "void" 121Create an empty array. 122The array initially has no capacity. 123Returns 124.Dv NULL 125on failure. 126.It Fn prop_array_create_with_capacity "unsigned int capacity" 127Create an array with the capacity to store 128.Fa capacity 129objects. 130Returns 131.Dv NULL 132on failure. 133.It Fn prop_array_copy "prop_array_t array" 134Copy an array. 135The new array has an initial capacity equal to the number of objects stored 136in the array being copied. 137The new array contains references to the original array's objects, not 138copies of those objects 139.Pq i.e. a shallow copy is made . 140If the original array is immutable, the resulting array is also immutable. 141Returns 142.Dv NULL 143on failure. 144.It Fn prop_array_copy_mutable "prop_array_t array" 145Like 146.Fn prop_array_copy , 147except the resulting array is always mutable. 148.It Fn prop_array_capacity "prop_array_t array" 149Returns the total capacity of the array, including objects already stored 150in the array. 151If the supplied object isn't an array, zero is returned. 152.It Fn prop_array_count "prop_array_t array" 153Returns the number of objects stored in the array. 154If the supplied object isn't an array, zero is returned. 155.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 156Ensure that the array has a total capacity of 157.Fa capacity , 158including objects already stored in the array. 159Returns 160.Dv true 161if the capacity of the array is greater or equal to 162.Fa capacity 163or if expansion of the array's capacity was successful 164and 165.Dv false 166otherwise. 167.It Fn prop_array_iterator "prop_array_t array" 168Create an iterator for the array. 169The array is retained by the iterator. 170An array iterator returns the object references stored in the array. 171Storing to or removing from the array invalidates any active iterators for 172the array. 173Returns 174.Dv NULL 175on failure. 176.It Fn prop_array_make_immutable "prop_array_t array" 177Make 178.Fa array 179immutable. 180.It Fn prop_array_mutable "prop_array_t array" 181Returns 182.Dv true 183if the array is mutable. 184.It Fn prop_array_get "prop_array_t array" "unsigned int index" 185Return the object stored at the array index 186.Fa index . 187Returns 188.Dv NULL 189on failure. 190.It Fn prop_array_set "prop_array_t array" "unsigned int index" \ 191 "prop_object_t obj" 192Store a reference to the object 193.Fa obj 194at the array index 195.Fa index . 196This function is not allowed to create holes in the array; 197the caller must either be setting the object just beyond the existing 198count or replacing an already existing object reference. 199The object will be retained by the array. 200If an existing object reference is being replaced, that object will be 201released. 202Returns 203.Dv true 204if storing the object was successful and 205.Dv false 206otherwise. 207.It Fn prop_array_add "prop_array_t array" "prop_object_t obj" 208Add a reference to the object 209.Fa obj 210to the array, appending to the end and growing the array's capacity if 211necessary. 212The object will be retained by the array. 213Returns 214.Dv true 215if storing the object was successful and 216.Dv false 217otherwise. 218.Pp 219During expansion, array's capacity is augmented by the 220.Dv EXPAND_STEP 221constant, as defined in 222.Pa libprop/prop_array.c 223file, e.g. 224.Pp 225#define EXPAND_STEP 16 226.It Fn prop_array_remove "prop_array_t array" "unsigned int index" 227Remove the reference to the object stored at array index 228.Fa index . 229The object will be released and the array compacted following 230the removal. 231.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 232Returns 233.Dv true 234if the two arrays are equivalent. 235If at least one of the supplied objects isn't an array, 236.Dv false 237is returned. 238Note: Objects contained in the array are compared by value, not by reference. 239.It Fn prop_array_externalize "prop_array_t array" 240Externalizes an array, returning a NUL-terminated buffer containing 241the XML representation of the array. 242The caller is responsible for freeing the returned buffer. 243If converting to the external representation fails for any reason, 244.Dv NULL 245is returned. 246.Pp 247In user space, the buffer is allocated using 248.Xr malloc 3 . 249In the kernel, the buffer is allocated using 250.Xr malloc 9 251using the malloc type 252.Dv M_TEMP . 253.It Fn prop_array_internalize "const char *xml" 254Parse the XML representation of a property list in the NUL-terminated 255buffer 256.Fa xml 257and return the corresponding array. 258Returns 259.Dv NULL 260if parsing fails for any reason. 261.It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" 262Externalizes an array and writes it to the file specified by 263.Fa path . 264The file is saved with the mode 265.Dv 0666 266as modified by the process's file creation mask 267.Pq see Xr umask 3 268and is written atomically. 269Returns 270.Dv false 271if externalizing or writing the array fails for any reason. 272.It Fn prop_array_internalize_from_file "const char *path" 273Reads the XML property list contained in the file specified by 274.Fa path , 275internalizes it, and returns the corresponding array. 276Returns 277.Dv NULL 278on failure. 279.El 280.Sh SEE ALSO 281.Xr prop_bool 3 , 282.Xr prop_data 3 , 283.Xr prop_dictionary 3 , 284.Xr prop_number 3 , 285.Xr prop_object 3 , 286.Xr prop_string 3 , 287.Xr proplib 3 288.Sh HISTORY 289The 290.Nm proplib 291property container object library first appeared in 292.Nx 4.0 . 293