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