1.\" $NetBSD: ppath_number.3,v 1.3 2011/09/13 18:07:22 dyoung Exp $ 2.\" $Id: ppath_number.3,v 1.3 2011/09/13 18:07:22 dyoung Exp $ 3.\" 4.\" Copyright (c) 2011 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by David Young <dyoung@NetBSD.org>. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS 20.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY 23.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 25.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 27.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 28.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 29.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd September 13, 2011 32.Dt PPATH_NUMBER 3 33.Os 34.Sh NAME 35.Nm ppath_number , 36.\" , 37.Nm ppath_copydel_int64 , 38.Nm ppath_copyset_int64 , 39.Nm ppath_set_int64 , 40.Nm ppath_get_int64 , 41.Nm ppath_delete_int64 , 42.\" , 43.Nm ppath_copydel_uint64 , 44.Nm ppath_copyset_uint64 , 45.Nm ppath_set_uint64 , 46.Nm ppath_get_uint64 , 47.Nm ppath_delete_uint64 48.Nd integer property path operations 49.Sh LIBRARY 50.Lb libppath 51.Sh SYNOPSIS 52.In ppath/ppath.h 53.\" 54.Ft int 55.Fn ppath_copydel_int64 "prop_object_t" "prop_object_t *" "const ppath_t *" 56.Ft int 57.Fn ppath_copyset_int64 "prop_object_t" "prop_object_t *" "const ppath_t *" \ 58 "int64_t" 59.Ft int 60.Fn ppath_set_int64 "prop_object_t" "const ppath_t *" "int64_t" 61.Ft int 62.Fn ppath_get_int64 "prop_object_t" "const ppath_t *" "int64_t *" 63.Ft int 64.Fn ppath_delete_int64 "prop_object_t" "const ppath_t *" 65.\" 66.Ft int 67.Fn ppath_copydel_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *" 68.Ft int 69.Fn ppath_copyset_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *" \ 70 "uint64_t" 71.Ft int 72.Fn ppath_set_uint64 "prop_object_t" "const ppath_t *" "uint64_t" 73.Ft int 74.Fn ppath_get_uint64 "prop_object_t" "const ppath_t *" "uint64_t *" 75.Ft int 76.Fn ppath_delete_uint64 "prop_object_t" "const ppath_t *" 77.Sh DESCRIPTION 78The 79.Nm 80routines read, write, or 81delete integers in a property list by path. 82.Sh FUNCTIONS 83.Nm 84provides these functions for manipulating integers in a property list 85by the integers' paths: 86.Bl -tag -width ppath 87.It Fn ppath_copydel_int64 "prop_object_t o" "prop_object_t *op" \ 88 "const ppath_t *p" 89.It Fn ppath_copydel_uint64 "prop_object_t o" "prop_object_t *op" \ 90 "const ppath_t *p" 91Create a copy of the property list 92.Fa o 93at 94.Fa *op . 95Delete from the copy the 96.Vt prop_number_t 97named by 98.Fa p . 99.Pp 100If 101.Fa *op 102is 103.Dv NULL , 104.Fn ppath_copydel_int64 105and 106.Fn ppath_copydel_uint64 107create a shallow copy of 108.Fa o 109at 110.Fa *op . 111If 112.Fa *op 113is not 114.Dv NULL , 115.Fn ppath_copydel_int64 116and 117.Fn ppath_copydel_uint64 118expect for 119.Fa *op 120to be an existing shallow copy of 121.Fa o . 122.Pp 123For the purposes of 124.Fn ppath_copydel_int64 125and 126.Fn ppath_copydel_uint64 , 127.Fa *op 128is a shallow copy of property list 129.Fa o 130if equal properties at equal paths are shared between the two. 131Before 132.Fn ppath_copydel_int64 133and 134.Fn ppath_copydel_uint64 135modify a property shared by 136.Fa *op 137and 138.Fa o , 139they create a private copy of the property for 140.Fa *op . 141.It Fn ppath_copyset_int64 "prop_object_t o" "prop_object_t *op" \ 142 "const ppath_t *p" "int64_t v" 143.It Fn ppath_copyset_uint64 "prop_object_t o" "prop_object_t *op" \ 144 "const ppath_t *p" "uint64_t v" 145Create a copy of the property list 146.Fa o 147at 148.Fa *op . 149In the copy, replace with 150.Fa v 151the 152.Vt prop_number_t 153named by 154.Fa p . 155.Pp 156If 157.Fa *op 158is 159.Dv NULL , 160.Fn ppath_copyset_int64 161and 162.Fn ppath_copyset_uint64 163create a shallow copy of 164.Fa o 165at 166.Fa *op . 167If 168.Fa *op 169is not 170.Dv NULL , 171.Fn ppath_copyset_int64 172and 173.Fn ppath_copyset_uint64 174expect for 175.Fa *op 176to be an existing shallow copy of 177.Fa o . 178.Pp 179For the purposes of 180.Fn ppath_copyset_int64 181and 182.Fn ppath_copyset_uint64 , 183.Fa *op 184is a shallow copy of property list 185.Fa o 186if equal properties at equal paths are shared between the two. 187Before 188.Fn ppath_copydel_int64 189and 190.Fn ppath_copydel_uint64 191modify a property shared by 192.Fa *op 193and 194.Fa o , 195they create a private copy of the property for 196.Fa *op . 197.It Fn ppath_set_int64 "prop_object_t o" "const ppath_t *p" "int64_t v" 198.It Fn ppath_set_uint64 "prop_object_t o" "const ppath_t *" "uint64_t v" 199Replace with 200.Fa v 201the 202.Vt prop_number_t 203in 204.Fa o 205named by 206.Fa p . 207.It Fn ppath_get_int64 "prop_object_t o" "const ppath_t *p" "int64_t *vp" 208.It Fn ppath_get_uint64 "prop_object_t o" "const ppath_t *p" "uint64_t *vp" 209Retrieve the 210.Vt prop_number_t 211named by 212.Fa p 213from 214.Fa o , 215and write it to 216.Fa *vp . 217.It Fn ppath_delete_int64 "prop_object_t o" "const ppath_t *p" 218.It Fn ppath_delete_uint64 "prop_object_t o" "const ppath_t *p" 219Delete the 220.Vt prop_number_t 221named by 222.Fa p 223from 224.Fa o . 225.Fn ppath_delete_int64 226and 227.Fn ppath_delete_uint64 228decrease by one the deleted number's reference count. 229.El 230.\" 231.\" This next request is for sections 2 and 3 function return values only. 232.Sh RETURN VALUES 233.Nm 234routines return 0 on success, and non-zero on error. 235.\" The next request is for sections 2 and 3 error and signal handling only. 236.Sh ERRORS 237.Bl -tag -width Er 238.It Bq Er EFTYPE 239A 240.Nm 241operation returns 242.Er EFTYPE 243when the object named by the path is not a 244.Vt prop_number_t . 245.It Bq Er ENOENT 246.Nm 247routines return 248.Er ENOENT 249if the path 250.Fa p 251does not exist in 252.Fa o . 253.It Bq Er ENOMEM 254.Fn ppath_set_int64 , 255.Fn ppath_set_uint64 , 256.Fn ppath_copyset_int64 , 257and 258.Fn ppath_copyset_uint64 259return 260.Er ENOMEM 261if there was insufficient memory to complete the operation. 262.El 263.Sh SEE ALSO 264.\" Cross-references should be ordered by section (low to high), then in 265.\" alphabetical order. 266.Xr ppath 3 , 267.Xr ppath_data 3 , 268.Xr ppath_object 3 , 269.Xr ppath_string 3 , 270.Xr proplib 3 271.Sh HISTORY 272The 273.Nm 274property container path library first appeared in 275.Nx 6.0 . 276.Sh AUTHORS 277.An David Young 278.Aq dyoung@pobox.com 279.\" .Sh CAVEATS 280.\" .Sh BUGS 281.\" .Sh SECURITY CONSIDERATIONS 282