1.\" $NetBSD: prop_array_util.3,v 1.13 2024/02/10 18:43:51 andvar Exp $ 2.\" 3.\" Copyright (c) 2006, 2020 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 June 2, 2020 31.Dt PROP_ARRAY_UTIL 3 32.Os 33.Sh NAME 34.Nm prop_array_util , 35.Nm prop_array_get_bool , 36.Nm prop_array_set_bool , 37.Nm prop_array_get_schar , 38.Nm prop_array_get_uchar , 39.Nm prop_array_set_schar , 40.Nm prop_array_set_uchar , 41.Nm prop_array_get_short , 42.Nm prop_array_get_ushort , 43.Nm prop_array_set_short , 44.Nm prop_array_set_ushort , 45.Nm prop_array_get_int , 46.Nm prop_array_get_uint , 47.Nm prop_array_set_int , 48.Nm prop_array_set_uint , 49.Nm prop_array_get_long , 50.Nm prop_array_get_ulong , 51.Nm prop_array_set_long , 52.Nm prop_array_set_ulong , 53.Nm prop_array_get_longlong , 54.Nm prop_array_get_ulonglong , 55.Nm prop_array_set_longlong , 56.Nm prop_array_set_ulonglong , 57.Nm prop_array_get_intptr , 58.Nm prop_array_get_uintptr , 59.Nm prop_array_set_intptr , 60.Nm prop_array_set_uintptr , 61.Nm prop_array_get_int8 , 62.Nm prop_array_get_uint8 , 63.Nm prop_array_set_int8 , 64.Nm prop_array_set_uint8 , 65.Nm prop_array_get_int16 , 66.Nm prop_array_get_uint16 , 67.Nm prop_array_set_int16 , 68.Nm prop_array_set_uint16 , 69.Nm prop_array_get_int32 , 70.Nm prop_array_get_uint32 , 71.Nm prop_array_set_int32 , 72.Nm prop_array_set_uint32 , 73.Nm prop_array_get_int64 , 74.Nm prop_array_get_uint64 , 75.Nm prop_array_set_int64 , 76.Nm prop_array_set_uint64 , 77.Nm prop_array_get_data , 78.Nm prop_array_set_data , 79.Nm prop_array_set_data_nocopy , 80.Nm prop_array_get_string , 81.Nm prop_array_set_string , 82.Nm prop_array_set_string_nocopy , 83.Nm prop_array_add_schar , 84.Nm prop_array_add_uchar , 85.Nm prop_array_add_short , 86.Nm prop_array_add_ushort , 87.Nm prop_array_add_int , 88.Nm prop_array_add_uint , 89.Nm prop_array_add_long , 90.Nm prop_array_add_ulong , 91.Nm prop_array_add_longlong , 92.Nm prop_array_add_ulonglong , 93.Nm prop_array_add_intptr , 94.Nm prop_array_add_uintptr , 95.Nm prop_array_add_int8 , 96.Nm prop_array_add_uint8 , 97.Nm prop_array_add_int16 , 98.Nm prop_array_add_uint16 , 99.Nm prop_array_add_int32 , 100.Nm prop_array_add_uint32 , 101.Nm prop_array_add_int64 , 102.Nm prop_array_add_uint64 , 103.Nm prop_array_add_data , 104.Nm prop_array_add_data_nocopy , 105.Nm prop_array_add_string , 106.Nm prop_array_add_string_nocopy , 107.Nm prop_array_add_and_rel 108.Nd array property collection object utility functions 109.Sh LIBRARY 110.Lb libprop 111.Sh SYNOPSIS 112.In prop/proplib.h 113.\" 114.Ft bool 115.Fn prop_array_get_bool "prop_array_t array" "unsigned int indx" \ 116 "bool *valp" 117.Ft bool 118.Fn prop_array_set_bool "prop_array_t array" "unsigned int indx" \ 119 "bool val" 120.\" 121.Ft bool 122.Fn prop_array_get_schar "prop_array_t array" "unsigned int indx" \ 123 "signed char *valp" 124.Ft bool 125.Fn prop_array_get_uchar "prop_array_t array" "unsigned int indx" \ 126 "unsigned char *valp" 127.Ft bool 128.Fn prop_array_set_schar "prop_array_t array" "unsigned int indx" \ 129 "signed char val" 130.Ft bool 131.Fn prop_array_set_uchar "prop_array_t array" "unsigned int indx" \ 132 "unsigned char val" 133.\" 134.Ft bool 135.Fn prop_array_get_short "prop_array_t array" "unsigned int indx" \ 136 "short *valp" 137.Ft bool 138.Fn prop_array_get_ushort "prop_array_t array" "unsigned int indx" \ 139 "unsigned short *valp" 140.Ft bool 141.Fn prop_array_set_short "prop_array_t array" "unsigned int indx" \ 142 "short val" 143.Ft bool 144.Fn prop_array_set_ushort "prop_array_t array" "unsigned int indx" \ 145 "unsigned short val" 146.\" 147.Ft bool 148.Fn prop_array_get_int "prop_array_t array" "unsigned int indx" \ 149 "int *valp" 150.Ft bool 151.Fn prop_array_get_uint "prop_array_t array" "unsigned int indx" \ 152 "unsigned int *valp" 153.Ft bool 154.Fn prop_array_set_int "prop_array_t array" "unsigned int indx" \ 155 "int val" 156.Ft bool 157.Fn prop_array_set_uint "prop_array_t array" "unsigned int indx" \ 158 "unsigned int val" 159.\" 160.Ft bool 161.Fn prop_array_get_long "prop_array_t array" "unsigned int indx" \ 162 "long *valp" 163.Ft bool 164.Fn prop_array_get_ulong "prop_array_t array" "unsigned int indx" \ 165 "unsigned long *valp" 166.Ft bool 167.Fn prop_array_set_long "prop_array_t array" "unsigned int indx" \ 168 "long val" 169.Ft bool 170.Fn prop_array_set_ulong "prop_array_t array" "unsigned int indx" \ 171 "unsigned long val" 172.\" 173.Ft bool 174.Fn prop_array_get_longlong "prop_array_t array" "unsigned int indx" \ 175 "long long *valp" 176.Ft bool 177.Fn prop_array_get_ulonglong "prop_array_t array" "unsigned int indx" \ 178 "unsigned long long *valp" 179.Ft bool 180.Fn prop_array_set_longlong "prop_array_t array" "unsigned int indx" \ 181 "long long val" 182.Ft bool 183.Fn prop_array_set_ulonglong "prop_array_t array" "unsigned int indx" \ 184 "unsigned long long val" 185.\" 186.Ft bool 187.Fn prop_array_get_intptr "prop_array_t array" "unsigned int indx" \ 188 "intptr_t *valp" 189.Ft bool 190.Fn prop_array_get_uintptr "prop_array_t array" "unsigned int indx" \ 191 "uintptr_t *valp" 192.Ft bool 193.Fn prop_array_set_intptr "prop_array_t array" "unsigned int indx" \ 194 "intptr_t val" 195.Ft bool 196.Fn prop_array_set_uintptr "prop_array_t array" "unsigned int indx" \ 197 "uintptr_t val" 198.\" 199.Ft bool 200.Fn prop_array_get_int8 "prop_array_t array" "unsigned int indx" \ 201 "int8_t *valp" 202.Ft bool 203.Fn prop_array_get_uint8 "prop_array_t array" "unsigned int indx" \ 204 "uint8_t *valp" 205.Ft bool 206.Fn prop_array_set_int8 "prop_array_t array" "unsigned int indx" \ 207 "int8_t val" 208.Ft bool 209.Fn prop_array_set_uint8 "prop_array_t array" "unsigned int indx" \ 210 "uint8_t val" 211.\" 212.Ft bool 213.Fn prop_array_get_int16 "prop_array_t array" "unsigned int indx" \ 214 "int16_t *valp" 215.Ft bool 216.Fn prop_array_get_uint16 "prop_array_t array" "unsigned int indx" \ 217 "uint16_t *valp" 218.Ft bool 219.Fn prop_array_set_int16 "prop_array_t array" "unsigned int indx" \ 220 "int16_t val" 221.Ft bool 222.Fn prop_array_set_uint16 "prop_array_t array" "unsigned int indx" \ 223 "uint16_t val" 224.\" 225.Ft bool 226.Fn prop_array_get_int32 "prop_array_t array" "unsigned int indx" \ 227 "int32_t *valp" 228.Ft bool 229.Fn prop_array_get_uint32 "prop_array_t array" "unsigned int indx" \ 230 "uint32_t *valp" 231.Ft bool 232.Fn prop_array_set_int32 "prop_array_t array" "unsigned int indx" \ 233 "int32_t val" 234.Ft bool 235.Fn prop_array_set_uint32 "prop_array_t array" "unsigned int indx" \ 236 "uint32_t val" 237.\" 238.Ft bool 239.Fn prop_array_get_int64 "prop_array_t array" "unsigned int indx" \ 240 "int64_t *valp" 241.Ft bool 242.Fn prop_array_get_uint64 "prop_array_t array" "unsigned int indx" \ 243 "uint64_t *valp" 244.Ft bool 245.Fn prop_array_set_int64 "prop_array_t array" "unsigned int indx" \ 246 "int64_t val" 247.Ft bool 248.Fn prop_array_set_uint64 "prop_array_t array" "unsigned int indx" \ 249 "uint64_t val" 250.\" 251.Ft bool 252.Fn prop_array_get_data "prop_array_t array" "unsigned int indx" \ 253 "const void **datap" "size_t *sizep" 254.Ft bool 255.Fn prop_array_set_data "prop_array_t array" "unsigned int indx" \ 256 "const void *data" "size_t len" 257.Ft bool 258.Fn prop_array_set_data_nocopy "prop_array_t array" "unsigned int indx" \ 259 "const void *data" "size_t len" 260.\" 261.Ft bool 262.Fn prop_array_get_string "prop_array_t array" "unsigned int indx" \ 263 "const char **strp" 264.Ft bool 265.Fn prop_array_set_string "prop_array_t array" "unsigned int indx" \ 266 "const char *str" 267.Ft bool 268.Fn prop_array_set_string_nocopy "prop_array_t array" "unsigned int indx" \ 269 "const char *str" 270.\" 271.Ft bool 272.Fn prop_array_set_and_rel "prop_array_t array" "unsigned int indx" \ 273 "prop_object_t obj" 274.\" 275.Ft bool 276.Fn prop_array_add_bool "prop_array_t array" "bool val" 277.Ft bool 278.Fn prop_array_add_schar "prop_array_t array" "signed char val" 279.Ft bool 280.Fn prop_array_add_uchar "prop_array_t array" "unsigned char val" 281.Ft bool 282.Fn prop_array_add_short "prop_array_t array" "short val" 283.Ft bool 284.Fn prop_array_add_ushort "prop_array_t array" "unsigned short val" 285.Ft bool 286.Fn prop_array_add_int "prop_array_t array" "int val" 287.Ft bool 288.Fn prop_array_add_uint "prop_array_t array" "unsigned int val" 289.Ft bool 290.Fn prop_array_add_long "prop_array_t array" "long val" 291.Ft bool 292.Fn prop_array_add_ulong "prop_array_t array" "unsigned long val" 293.Ft bool 294.Fn prop_array_add_longlong "prop_array_t array" "long long val" 295.Ft bool 296.Fn prop_array_add_ulonglong "prop_array_t array" "unsigned long long val" 297.Ft bool 298.Fn prop_array_add_intptr "prop_array_t array" "intptr_t val" 299.Ft bool 300.Fn prop_array_add_uintptr "prop_array_t array" "uintptr_t val" 301.Ft bool 302.Fn prop_array_add_int8 "prop_array_t array" "int8_t val" 303.Ft bool 304.Fn prop_array_add_uint8 "prop_array_t array" "uint8_t val" 305.Ft bool 306.Fn prop_array_add_int16 "prop_array_t array" "int16_t val" 307.Ft bool 308.Fn prop_array_add_uint16 "prop_array_t array" "uint16_t val" 309.Ft bool 310.Fn prop_array_add_int32 "prop_array_t array" "int32_t val" 311.Ft bool 312.Fn prop_array_add_uint32 "prop_array_t array" "uint32_t val" 313.Ft bool 314.Fn prop_array_add_int64 "prop_array_t array" "int64_t val" 315.Ft bool 316.Fn prop_array_add_uint64 "prop_array_t array" "uint64_t val" 317.\" 318.Ft bool 319.Fn prop_array_add_data "prop_array_t array" "const void *data" \ 320 "size_t len" 321.Ft bool 322.Fn prop_array_add_data_nocopy "prop_array_t array" "const char *data" \ 323 "size_t len" 324.\" 325.Ft bool 326.Fn prop_array_add_string "prop_array_t array" "const char *str" 327.Ft bool 328.Fn prop_array_add_string_nocopy "prop_array_t array" "const char *str" 329.\" 330.Ft bool 331.Fn prop_array_add_and_rel "prop_array_t array" "prop_object_t obj" 332.Sh DESCRIPTION 333The 334.Nm 335family of functions are provided to make getting and setting values in 336arrays more convenient in some applications. 337.Pp 338The getters check the type of the returned object and, in some cases, also 339ensure that the returned value is within the range implied by the getter's 340value type. 341.Pp 342The setters and adders handle object creation and release for the caller. 343.Pp 344If the 345.Fa sizep 346argument to 347.Fn prop_array_get_data 348is not 349.Dv NULL , 350then it will be set to the size of the returned data. 351.Pp 352The 353.Fn prop_array_get_data , 354.Fn prop_array_set_data_nocopy , 355and 356.Fn prop_array_add_data_nocopy 357do not copy the data that is set or returned. 358See 359.Xr prop_data 3 360for more information. 361.Pp 362The 363.Fn prop_array_get_string , 364.Fn prop_array_set_string_nocopy , 365and 366.Fn prop_array_add_string_nocopy 367do not copy the string that is set or returned. 368See 369.Xr prop_string 3 370for more information. 371The 372.Fn prop_array_set_and_rel 373and 374.Fn prop_array_add_and_rel 375functions add the object to the array and release it. 376The object is always released, even if adding it to the array fails. 377.Sh RETURN VALUES 378The 379.Nm 380getter functions return 381.Dv true 382if the object exists in the array and the value is in-range, or 383.Dv false 384otherwise. 385.Pp 386The 387.Nm 388setter and adder functions return 389.Dv true 390if creating the object and storing it in the array is successful, or 391.Dv false 392otherwise. 393.Sh SEE ALSO 394.Xr prop_array 3 , 395.Xr prop_bool 3 , 396.Xr prop_data 3 , 397.Xr prop_number 3 , 398.Xr prop_string 3 , 399.Xr proplib 3 400.Sh HISTORY 401The 402.Xr proplib 3 403property container object library first appeared in 404.Nx 4.0 . 405