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