.\"	$NetBSD: ppath_bool.3,v 1.7 2017/10/23 00:59:44 wiz Exp $
.\"
.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by David Young <dyoung@NetBSD.org>.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL David Young BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 13, 2011
.Dt PPATH_BOOL 3
.Os
.Sh NAME
.Nm ppath_bool ,
.\" ,
.Nm ppath_copydel_bool ,
.Nm ppath_copyset_bool ,
.Nm ppath_set_bool ,
.Nm ppath_get_bool ,
.Nm ppath_delete_bool
.Nd boolean property path operations
.Sh LIBRARY
.Lb libppath
.Sh SYNOPSIS
.In ppath/ppath.h
.\"
.Ft int
.Fn ppath_copydel_bool "prop_object_t" "prop_object_t *" "const ppath_t *"
.Ft int
.Fn ppath_copyset_bool "prop_object_t" "prop_object_t *" "const ppath_t *" \
    "bool"
.Ft int
.Fn ppath_set_bool "prop_object_t" "const ppath_t *" "bool"
.Ft int
.Fn ppath_get_bool "prop_object_t" "const ppath_t *" "bool *"
.Ft int
.Fn ppath_delete_bool "prop_object_t" "const ppath_t *"
.Sh DESCRIPTION
The
.Nm
routines read, write, or
delete boolean values in a property list by path.
.Sh FUNCTIONS
.Nm
provides these functions for manipulating boolean values in a property list
by the values' paths:
.Bl -tag -width ppath
.It Fn ppath_copydel_bool "prop_object_t o" "prop_object_t *op" \
    "const ppath_t *p"
Create a copy of the property list
.Fa o
at
.Fa *op .
Delete from the copy the
.Vt prop_bool_t
named by
.Fa p .
.Pp
If
.Fa *op
is
.Dv NULL ,
.Fn ppath_copydel_bool
creates a shallow copy of
.Fa o
at
.Fa *op .
If
.Fa *op
is not
.Dv NULL ,
.Fn ppath_copydel_bool
expects for
.Fa *op
to be an existing shallow copy of
.Fa o .
.Pp
For the purposes of
.Fn ppath_copydel_bool ,
.Fa *op
is a shallow copy of property list
.Fa o
if equal properties at equal paths are shared between the two.
Before
.Fn ppath_copydel_bool
modifies a property shared by
.Fa *op
and
.Fa o ,
it creates a private copy of the property for
.Fa *op .
.It Fn ppath_copyset_bool "prop_object_t o" "prop_object_t *op" \
    "const ppath_t *p" "bool v"
Create a copy of the property list
.Fa o
at
.Fa *op .
In the copy, replace with
.Fa v
the
.Vt prop_bool_t
named by
.Fa p .
.Pp
If
.Fa *op
is
.Dv NULL ,
.Fn ppath_copyset_bool
creates a shallow copy of
.Fa o
at
.Fa *op .
If
.Fa *op
is not
.Dv NULL ,
.Fn ppath_copyset_bool
expects for
.Fa *op
to be an existing shallow copy of
.Fa o .
.Pp
For the purposes of
.Fn ppath_copyset_bool ,
.Fa *op
is a shallow copy of property list
.Fa o
if equal properties at equal paths are shared between the two.
Before
.Fn ppath_copydel_bool
modifies a property shared by
.Fa *op
and
.Fa o ,
it creates a private copy of the property for
.Fa *op .
.It Fn ppath_set_bool "prop_object_t o" "const ppath_t *p" "bool v"
Replace with
.Fa v
the
.Vt prop_bool_t
in
.Fa o
named by
.Fa p .
.It Fn ppath_get_bool "prop_object_t o" "const ppath_t *p" "bool *vp"
Retrieve the
.Vt prop_bool_t
named by
.Fa p
from
.Fa o ,
and write it to
.Fa *vp .
.It Fn ppath_delete_bool "prop_object_t o" "const ppath_t *p"
Delete the
.Vt prop_bool_t
named by
.Fa p
from
.Fa o .
.Fn ppath_delete_bool
decreases by one the deleted boolean value's reference count.
.El
.\"
.\" This next request is for sections 2 and 3 function return values only.
.Sh RETURN VALUES
.Nm
routines return 0 on success, and non-zero on error.
.\" The next request is for sections 2 and 3 error and signal handling only.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EFTYPE
A
.Nm
operation returns
.Er EFTYPE
when the object named by the path is not a
.Vt prop_bool_t .
.It Bq Er ENOENT
.Nm
routines return
.Er ENOENT
if the path
.Fa p
does not exist in
.Fa o .
.It Bq Er ENOMEM
.Fn ppath_set_bool ,
and
.Fn ppath_copyset_bool
return
.Er ENOMEM
if there was insufficient memory to complete the operation.
.El
.Sh SEE ALSO
.\" Cross-references should be ordered by section (low to high), then in
.\"     alphabetical order.
.Xr ppath 3 ,
.\" .Xr ppath_data 3 ,
.Xr ppath_object 3 ,
.\" .Xr ppath_string 3 ,
.Xr proplib 3
.Sh HISTORY
The
.Nm
property container path library first appeared in
.Nx 6.0 .
.Sh AUTHORS
.An David Young
.Aq dyoung@pobox.com
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS