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 107The 108.Nm prop_array 109family of functions operate on the array property collection object type. 110An array is an ordered set; an iterated array will return objects in the 111same order with which they were stored. 112.Bl -tag -width "xxxxx" 113.It Fn prop_array_create "void" 114Create an empty array. 115The array initially has no capacity. 116Returns 117.Dv NULL 118on failure. 119.It Fn prop_array_create_with_capacity "unsigned int capacity" 120Create an array with the capacity to store 121.Fa capacity 122objects. 123Returns 124.Dv NULL 125on failure. 126.It Fn prop_array_copy "prop_array_t array" 127Copy an array. 128The new array has an initial capacity equal to the number of objects stored 129in the array being copied. 130The new array contains references to the original array's objects, not 131copies of those objects 132.Pq i.e. a shallow copy is made . 133If the original array is immutable, the resulting array is also immutable. 134Returns 135.Dv NULL 136on failure. 137.It Fn prop_array_copy_mutable "prop_array_t array" 138Like 139.Fn prop_array_copy , 140except the resulting array is always mutable. 141.It Fn prop_array_capacity "prop_array_t array" 142Returns the total capacity of the array, including objects already stored 143in the array. 144If the supplied object isn't an array, zero is returned. 145.It Fn prop_array_count "prop_array_t array" 146Returns the number of objects stored in the array. 147If the supplied object isn't an array, zero is returned. 148.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 149Ensure that the array has a total capacity of 150.Fa capacity , 151including objects already stored in the array. 152Returns 153.Dv true 154if the capacity of the array is greater or equal to 155.Fa capacity 156or if expansion of the array's capacity was successful 157and 158.Dv false 159otherwise. 160.It Fn prop_array_iterator "prop_array_t array" 161Create an iterator for the array. 162The array is retained by the iterator. 163An array iterator returns the object references stored in the array. 164Storing to or removing from the array invalidates any active iterators for 165the array. 166Returns 167.Dv NULL 168on failure. 169.It Fn prop_array_make_immutable "prop_array_t array" 170Make 171.Fa array 172immutable. 173.It Fn prop_array_mutable "prop_array_t array" 174Returns 175.Dv true 176if the array is mutable. 177.It Fn prop_array_get "prop_array_t array" "unsigned int index" 178Return the object stored at the array index 179.Fa index . 180Returns 181.Dv NULL 182on failure. 183.It Fn prop_array_set "prop_array_t array" "unsigned int index" \ 184 "prop_object_t obj" 185Store a reference to the object 186.Fa obj 187at the array index 188.Fa index . 189This function is not allowed to create holes in the array; 190the caller must either be setting the object just beyond the existing 191count or replacing an already existing object reference. 192The object will be retained by the array. 193If an existing object reference is being replaced, that object will be 194released. 195Returns 196.Dv true 197if storing the object was successful and 198.Dv false 199otherwise. 200.It Fn prop_array_add "prop_array_t array" "prop_object_t obj" 201Add a reference to the object 202.Fa obj 203to the array, appending to the end and growing the array's capacity if 204necessary. 205The object will be retained by the array. 206Returns 207.Dv true 208if storing the object was successful and 209.Dv false 210otherwise. 211.Pp 212During expansion, array's capacity is augmented by the 213.Dv EXPAND_STEP 214constant, as defined in 215.Pa libprop/prop_array.c 216file, e.g. 217.Pp 218#define EXPAND_STEP 16 219.It Fn prop_array_remove "prop_array_t array" "unsigned int index" 220Remove the reference to the object stored at array index 221.Fa index . 222The object will be released and the array compacted following 223the removal. 224.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 225Returns 226.Dv true 227if the two arrays are equivalent. 228If at least one of the supplied objects isn't an array, 229.Dv false 230is returned. 231Note: Objects contained in the array are compared by value, not by reference. 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 malloc 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 3 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.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 282The 283.Nm proplib 284property container object library first appeared in 285.Nx 4.0 . 286