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