Home | History | Annotate | Line # | Download | only in libppath 
 $NetBSD: ppath_number.3,v 1.5 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 (at] 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_NUMBER 3
.Os
.Sh NAME
.Nm ppath_number ,
 ,
.Nm ppath_copydel_int64 ,
.Nm ppath_copyset_int64 ,
.Nm ppath_set_int64 ,
.Nm ppath_get_int64 ,
.Nm ppath_delete_int64 ,
 ,
.Nm ppath_copydel_uint64 ,
.Nm ppath_copyset_uint64 ,
.Nm ppath_set_uint64 ,
.Nm ppath_get_uint64 ,
.Nm ppath_delete_uint64
.Nd integer property path operations
.Sh LIBRARY
.Lb libppath
.Sh SYNOPSIS
n ppath/ppath.h 
.Ft int
.Fn ppath_copydel_int64 "prop_object_t" "prop_object_t *" "const ppath_t *"
.Ft int
.Fn ppath_copyset_int64 "prop_object_t" "prop_object_t *" "const ppath_t *" \
 "int64_t"
.Ft int
.Fn ppath_set_int64 "prop_object_t" "const ppath_t *" "int64_t"
.Ft int
.Fn ppath_get_int64 "prop_object_t" "const ppath_t *" "int64_t *"
.Ft int
.Fn ppath_delete_int64 "prop_object_t" "const ppath_t *"

.Ft int
.Fn ppath_copydel_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *"
.Ft int
.Fn ppath_copyset_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *" \
 "uint64_t"
.Ft int
.Fn ppath_set_uint64 "prop_object_t" "const ppath_t *" "uint64_t"
.Ft int
.Fn ppath_get_uint64 "prop_object_t" "const ppath_t *" "uint64_t *"
.Ft int
.Fn ppath_delete_uint64 "prop_object_t" "const ppath_t *"
.Sh DESCRIPTION
The
.Nm
routines read, write, or
delete integers in a property list by path.
.Sh FUNCTIONS
.Nm
provides these functions for manipulating integers in a property list
by the integers' paths:
l -tag -width ppath t Fn ppath_copydel_int64 "prop_object_t o" "prop_object_t *op" \  "const ppath_t *p"
t Fn ppath_copydel_uint64 "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_number_t
named by
.Fa p .

p
If
.Fa *op
is
.Dv NULL ,
.Fn ppath_copydel_int64
and
.Fn ppath_copydel_uint64
create a shallow copy of
.Fa o
at
.Fa *op .
If
.Fa *op
is not
.Dv NULL ,
.Fn ppath_copydel_int64
and
.Fn ppath_copydel_uint64
expect for
.Fa *op
to be an existing shallow copy of
.Fa o .

p
For the purposes of
.Fn ppath_copydel_int64
and
.Fn ppath_copydel_uint64 ,
.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_int64
and
.Fn ppath_copydel_uint64
modify a property shared by
.Fa *op
and
.Fa o ,
they create a private copy of the property for
.Fa *op .
t Fn ppath_copyset_int64 "prop_object_t o" "prop_object_t *op" \  "const ppath_t *p" "int64_t v"
t Fn ppath_copyset_uint64 "prop_object_t o" "prop_object_t *op" \  "const ppath_t *p" "uint64_t v"
Create a copy of the property list
.Fa o
at
.Fa *op .
In the copy, replace with
.Fa v
the
.Vt prop_number_t
named by
.Fa p .

p
If
.Fa *op
is
.Dv NULL ,
.Fn ppath_copyset_int64
and
.Fn ppath_copyset_uint64
create a shallow copy of
.Fa o
at
.Fa *op .
If
.Fa *op
is not
.Dv NULL ,
.Fn ppath_copyset_int64
and
.Fn ppath_copyset_uint64
expect for
.Fa *op
to be an existing shallow copy of
.Fa o .

p
For the purposes of
.Fn ppath_copyset_int64
and
.Fn ppath_copyset_uint64 ,
.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_int64
and
.Fn ppath_copydel_uint64
modify a property shared by
.Fa *op
and
.Fa o ,
they create a private copy of the property for
.Fa *op .
t Fn ppath_set_int64 "prop_object_t o" "const ppath_t *p" "int64_t v" t Fn ppath_set_uint64 "prop_object_t o" "const ppath_t *" "uint64_t v" Replace with
.Fa v
the
.Vt prop_number_t
in
.Fa o
named by
.Fa p .
t Fn ppath_get_int64 "prop_object_t o" "const ppath_t *p" "int64_t *vp" t Fn ppath_get_uint64 "prop_object_t o" "const ppath_t *p" "uint64_t *vp" Retrieve the
.Vt prop_number_t
named by
.Fa p
from
.Fa o ,
and write it to
.Fa *vp .
t Fn ppath_delete_int64 "prop_object_t o" "const ppath_t *p" t Fn ppath_delete_uint64 "prop_object_t o" "const ppath_t *p" Delete the
.Vt prop_number_t
named by
.Fa p
from
.Fa o .
.Fn ppath_delete_int64
and
.Fn ppath_delete_uint64
decrease by one the deleted number'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
l -tag -width Er t Bq Er EFTYPE A
.Nm
operation returns
.Er EFTYPE
when the object named by the path is not a
.Vt prop_number_t .
t Bq Er ENOENT .Nm
routines return
.Er ENOENT
if the path
.Fa p
does not exist in
.Fa o .
t Bq Er ENOMEM .Fn ppath_set_int64 ,
.Fn ppath_set_uint64 ,
.Fn ppath_copyset_int64 ,
and
.Fn ppath_copyset_uint64
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 (at] pobox.com
 .Sh CAVEATS
 .Sh BUGS
 .Sh SECURITY CONSIDERATIONS