281 lines
6.5 KiB
Groff
281 lines
6.5 KiB
Groff
.\" $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@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
|
|
.In 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:
|
|
.Bl -tag -width ppath
|
|
.It Fn ppath_copydel_int64 "prop_object_t o" "prop_object_t *op" \
|
|
"const ppath_t *p"
|
|
.It 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 .
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
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 .
|
|
.It Fn ppath_copyset_int64 "prop_object_t o" "prop_object_t *op" \
|
|
"const ppath_t *p" "int64_t v"
|
|
.It 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 .
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
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 .
|
|
.It Fn ppath_set_int64 "prop_object_t o" "const ppath_t *p" "int64_t v"
|
|
.It 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 .
|
|
.It Fn ppath_get_int64 "prop_object_t o" "const ppath_t *p" "int64_t *vp"
|
|
.It 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 .
|
|
.It Fn ppath_delete_int64 "prop_object_t o" "const ppath_t *p"
|
|
.It 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
|
|
.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_number_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_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@pobox.com
|
|
.\" .Sh CAVEATS
|
|
.\" .Sh BUGS
|
|
.\" .Sh SECURITY CONSIDERATIONS
|