1.\" $NetBSD: prop_array.3,v 1.6 2007/11/06 11:41:35 mjf 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. 123.It Fn prop_array_create_with_capacity "unsigned int capacity" 124Create an array with the capacity to store 125.Fa capacity 126objects. 127.It Fn prop_array_copy "prop_array_t array" 128Copy an array. 129The new array has an initial capacity equal to the number of objects stored 130in the array being copied. 131The new array contains references to the original array's objects, not 132copies of those objects 133.Pq i.e. a shallow copy is made . 134If the original array is immutable, the resulting array is also immutable. 135.It Fn prop_array_copy_mutable "prop_array_t array" 136Like 137.Fn prop_array_copy , 138except the resulting array is always mutable. 139.It Fn prop_array_capacity "prop_array_t array" 140Returns the total capacity of the array, including objects already stored 141in the array. 142.It Fn prop_array_count "prop_array_t array" 143Returns the number of objects stored in the array. 144.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 145Ensure that the array has a total capacity of 146.Fa capacity , 147including objects already stored in the array. 148Returns 149.Dv true 150if the capacity of the array is greater or equal to 151.Fa capacity 152or if expansion of the array's capacity was successful 153and 154.Dv false 155otherwise. 156.It Fn prop_array_iterator "prop_array_t array" 157Create an iterator for the array. 158The array is retained by the iterator. 159An array iterator returns the object references stored in the array. 160Storing to or removing from the array invalidates any active iterators for 161the array. 162.It Fn prop_array_make_immutable "prop_array_t array" 163Make 164.Fa array 165immutable. 166.It Fn prop_array_mutable "prop_array_t array" 167Returns 168.Dv true 169if the array is mutable. 170.It Fn prop_array_get "prop_array_t array" "unsigned int index" 171Return the object stored at the array index 172.Fa index . 173.It Fn prop_array_set "prop_array_t array" "unsigned int index" \ 174 "prop_object_t obj" 175Store a reference to the object 176.Fa obj 177at the array index 178.Fa index . 179This function is not allowed to create holes in the array; 180the caller must either be setting the object just beyond the existing 181count or replacing an already existing object reference. 182The object will be retained by the array. 183If an existing object reference is being replaced, that object will be 184released. 185Returns 186.Dv true 187if storing the object was successful and 188.Dv false 189otherwise. 190.It Fn prop_array_add "prop_array_t array" "prop_object_t obj" 191Add a reference to the object 192.Fa obj 193to the array, appending to the end and growing the array's capacity if 194necessary. 195The object will be retained by the array. 196Returns 197.Dv true 198if storing the object was successful and 199.Dv false 200otherwise. 201.It Fn prop_array_remove "prop_array_t array" "unsigned int index" 202Remove the reference to the object stored at array index 203.Fa index . 204The object will be released and the array compacted following 205the removal. 206.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 207Returns 208.Dv true 209if the two arrays are equivalent. 210Note: Objects contained in the array are compared by value, not by reference. 211.It Fn prop_array_externalize "prop_array_t array" 212Externalizes an array, returning a NUL-terminated buffer containing 213the XML representation of the array. 214The caller is responsible for freeing the returned buffer. 215If converting to the external representation fails for any reason, 216.Dv NULL 217is returned. 218.Pp 219In user space, the buffer is allocated using 220.Xr malloc 3 . 221In the kernel, the buffer is allocated using 222.Xr malloc 9 223using the malloc type 224.Dv M_TEMP . 225.It Fn prop_array_internalize "const char *xml" 226Parse the XML representation of a property list in the NUL-terminated 227buffer 228.Fa xml 229and return the corresponding array. 230Returns 231.Dv NULL 232if parsing fails for any reason. 233.It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" 234Externalizes an array and writes it to the file specified by 235.Fa path . 236The file is saved with the mode 237.Dv 0666 238as modified by the process's file creation mask 239.Pq see Xr umask 3 240and is written atomically. 241Returns 242.Dv false 243if externalizing or writing the array fails for any reason. 244.It Fn prop_array_internalize_from_file "const char *path" 245Reads the XML property list contained in the file specified by 246.Fa path , 247internalizes it, and returns the corresponding array. 248.El 249.Sh SEE ALSO 250.Xr prop_bool 3 , 251.Xr prop_data 3 , 252.Xr prop_dictionary 3 , 253.Xr prop_number 3 , 254.Xr prop_object 3 , 255.Xr prop_string 3 , 256.Xr proplib 3 257.Sh HISTORY 258The 259.Nm proplib 260property container object library first appeared in 261.Nx 4.0 . 262