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