1.\" $NetBSD: ppath_object.3,v 1.4 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 August 24, 2011 31.Dt PPATH_OBJECT 3 32.Os 33.Sh NAME 34.Nm ppath_object , 35.\" , 36.Nm ppath_copydel_object , 37.Nm ppath_copyset_object , 38.Nm ppath_set_object , 39.Nm ppath_get_object , 40.Nm ppath_delete_object , 41.\" , 42.Nm ppath_copydel_data , 43.Nm ppath_copyset_data , 44.Nm ppath_set_data , 45.Nm ppath_get_data , 46.Nm ppath_dup_data , 47.Nm ppath_delete_data , 48.\" , 49.Nm ppath_copydel_string , 50.Nm ppath_copyset_string , 51.Nm ppath_set_string , 52.Nm ppath_get_string , 53.Nm ppath_dup_string , 54.Nm ppath_delete_string 55.Nd property object path operations 56.Sh LIBRARY 57.Lb libppath 58.Sh SYNOPSIS 59.In ppath/ppath.h 60.\" 61.Ft int 62.Fn ppath_copydel_object "prop_object_t" "prop_object_t *" "const ppath_t *" 63.Ft int 64.Fn ppath_copyset_object "prop_object_t" "prop_object_t *" "const ppath_t *" \ 65 "prop_object_t" 66.Ft int 67.Fn ppath_set_object "prop_object_t" "const ppath_t *" "prop_object_t" 68.Ft int 69.Fn ppath_get_object "prop_object_t" "const ppath_t *" "prop_object_t *" 70.Ft int 71.Fn ppath_delete_object "prop_object_t" "const ppath_t *" 72.\" 73.Ft int 74.Fn ppath_copydel_data "prop_object_t" "prop_object_t *" "const ppath_t *" 75.Ft int 76.Fn ppath_copyset_data "prop_object_t" "prop_object_t *" "const ppath_t *" \ 77 "const void *" "size_t" 78.Ft int 79.Fn ppath_set_data "prop_object_t" "const ppath_t *" "const void *" "size_t" 80.Ft int 81.Fn ppath_get_data "prop_object_t" "const ppath_t *" "const void **" "size_t *" 82.Ft int 83.Fn ppath_dup_data "prop_object_t" "const ppath_t *" "void **" "size_t *" 84.Ft int 85.Fn ppath_delete_data "prop_object_t" "const ppath_t *" 86.\" 87.Ft int 88.Fn ppath_copydel_string "prop_object_t" "prop_object_t *" "const ppath_t *" 89.Ft int 90.Fn ppath_copyset_string "prop_object_t" "prop_object_t *" "const ppath_t *" \ 91 "const char *" 92.Ft int 93.Fn ppath_set_string "prop_object_t" "const ppath_t *" "const char *" 94.Ft int 95.Fn ppath_get_string "prop_object_t" "const ppath_t *" "const char **" 96.Ft int 97.Fn ppath_dup_string "prop_object_t" "const ppath_t *" "char **" 98.Ft int 99.Fn ppath_delete_string "prop_object_t" "const ppath_t *" 100.Sh DESCRIPTION 101The 102.Nm 103routines read, write, or 104delete objects in a property list by path. 105.Sh FUNCTIONS 106.Nm 107provides these functions for manipulating objects in a property list 108by the objects' paths: 109.Bl -tag -width ppath 110.It Fn ppath_copydel_object "prop_object_t o" "prop_object_t *op" \ 111 "const ppath_t *p" 112Create a copy of the property list 113.Fa o 114at 115.Fa *op . 116Delete from the copy the property named by 117.Fa p . 118.Pp 119If 120.Fa *op 121is 122.Dv NULL , 123.Fn ppath_copydel_object 124creates a shallow copy of 125.Fa o 126at 127.Fa *op . 128If 129.Fa *op 130is not 131.Dv NULL , 132.Fn ppath_copydel_object 133expects for 134.Fa *op 135to be an existing shallow copy of 136.Fa o . 137.Pp 138For the purposes of 139.Fn ppath_copydel_object , 140.Fa *op 141is a shallow copy of property list 142.Fa o 143if equal properties at equal paths are shared between the two. 144Before 145.Fn ppath_copydel_object 146modifies a property shared by 147.Fa *op 148and 149.Fa o , 150it creates a private copy of the property for 151.Fa *op . 152.It Fn ppath_copyset_object "prop_object_t o" "prop_object_t *op" \ 153 "const ppath_t *p" "prop_object_t v" 154Create a copy of the property list 155.Fa o 156at 157.Fa *op . 158In the copy, replace with 159.Fa v 160the property named by 161.Fa p . 162.Pp 163If 164.Fa *op 165is 166.Dv NULL , 167.Fn ppath_copyset_object 168creates a shallow copy of 169.Fa o 170at 171.Fa *op . 172If 173.Fa *op 174is not 175.Dv NULL , 176.Fn ppath_copyset_object 177expects for 178.Fa *op 179to be an existing shallow copy of 180.Fa o . 181.Pp 182For the purposes of 183.Fn ppath_copyset_object , 184.Fa *op 185is a shallow copy of property list 186.Fa o 187if equal properties at equal paths are shared between the two. 188Before 189.Fn ppath_copydel_object 190modifies a property shared by 191.Fa *op 192and 193.Fa o , 194it creates a private copy of the property for 195.Fa *op . 196.It Fn ppath_set_object "prop_object_t o" "const ppath_t *p" "prop_object_t v" 197Replace with 198.Fa v 199the 200.Vt prop_object_t 201in 202.Fa o 203named by 204.Fa p . 205.It Fn ppath_get_object "prop_object_t o" "const ppath_t *p" "prop_object_t *vp" 206Retrieve the 207.Vt prop_object_t 208named by 209.Fa p 210from 211.Fa o , 212and write it to 213.Fa *vp . 214.Fn ppath_get_object 215does 216.Em not 217increase the reference count of the retrieved object. 218.It Fn ppath_delete_object "prop_object_t o" "const ppath_t *p" 219Delete the 220.Vt prop_object_t 221named by 222.Fa p 223from 224.Fa o . 225.Fn ppath_delete_object 226decreases by one the deleted object's reference count. 227.El 228.\" 229.\" This next request is for sections 2 and 3 function return values only. 230.Sh RETURN VALUES 231.Nm 232routines return 0 on success, and non-zero on error. 233.\" The next request is for sections 2 and 3 error and signal handling only. 234.Sh ERRORS 235.Bl -tag -width Er 236.It Bq Er EFTYPE 237The 238.Nm 239call requested a 240.It Bq Er ENOENT 241.Fn ppath_copyset_object , 242.Fn ppath_delete_object , 243.Fn ppath_get_object , 244and 245.Fn ppath_set_object 246return 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_object 254and 255.Fn ppath_copyset_object 256will return 257.Er ENOMEM 258if there was insufficient memory to complete the operation. 259.El 260.Sh SEE ALSO 261.\" Cross-references should be ordered by section (low to high), then in 262.\" alphabetical order. 263.Xr ppath 3 , 264.\" .Xr ppath_data 3 , 265.Xr ppath_number 3 , 266.\" .Xr ppath_string 3 , 267.Xr proplib 3 268.Sh HISTORY 269The 270.Nm 271property container path library first appeared in 272.Nx 6.0 . 273.Sh AUTHORS 274.An David Young 275.Aq dyoung@pobox.com 276.\" .Sh CAVEATS 277.\" .Sh BUGS 278.\" .Sh SECURITY CONSIDERATIONS 279