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 August 24, 2011 .Dt PPATH_OBJECT 3 .Os .Sh NAME .Nm ppath_object , ,
.Nm ppath_copydel_object , .Nm ppath_copyset_object , .Nm ppath_set_object , .Nm ppath_get_object , .Nm ppath_delete_object , ,
.Nm ppath_copydel_data , .Nm ppath_copyset_data , .Nm ppath_set_data , .Nm ppath_get_data , .Nm ppath_dup_data , .Nm ppath_delete_data , ,
.Nm ppath_copydel_string , .Nm ppath_copyset_string , .Nm ppath_set_string , .Nm ppath_get_string , .Nm ppath_dup_string , .Nm ppath_delete_string .Nd property object path operations .Sh LIBRARY .Lb libppath .Sh SYNOPSIS n ppath/ppath.h
.Ft int .Fn ppath_copydel_object "prop_object_t" "prop_object_t *" "const ppath_t *" .Ft int .Fn ppath_copyset_object "prop_object_t" "prop_object_t *" "const ppath_t *" \ "prop_object_t" .Ft int .Fn ppath_set_object "prop_object_t" "const ppath_t *" "prop_object_t" .Ft int .Fn ppath_get_object "prop_object_t" "const ppath_t *" "prop_object_t *" .Ft int .Fn ppath_delete_object "prop_object_t" "const ppath_t *"
.Ft int .Fn ppath_copydel_data "prop_object_t" "prop_object_t *" "const ppath_t *" .Ft int .Fn ppath_copyset_data "prop_object_t" "prop_object_t *" "const ppath_t *" \ "const void *" "size_t" .Ft int .Fn ppath_set_data "prop_object_t" "const ppath_t *" "const void *" "size_t" .Ft int .Fn ppath_get_data "prop_object_t" "const ppath_t *" "const void **" "size_t *" .Ft int .Fn ppath_dup_data "prop_object_t" "const ppath_t *" "void **" "size_t *" .Ft int .Fn ppath_delete_data "prop_object_t" "const ppath_t *"
.Ft int .Fn ppath_copydel_string "prop_object_t" "prop_object_t *" "const ppath_t *" .Ft int .Fn ppath_copyset_string "prop_object_t" "prop_object_t *" "const ppath_t *" \ "const char *" .Ft int .Fn ppath_set_string "prop_object_t" "const ppath_t *" "const char *" .Ft int .Fn ppath_get_string "prop_object_t" "const ppath_t *" "const char **" .Ft int .Fn ppath_dup_string "prop_object_t" "const ppath_t *" "char **" .Ft int .Fn ppath_delete_string "prop_object_t" "const ppath_t *" .Sh DESCRIPTION The .Nm routines read, write, or delete objects in a property list by path. .Sh FUNCTIONS .Nm provides these functions for manipulating objects in a property list by the objects' paths: l -tag -width ppath t Fn ppath_copydel_object "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 property named by .Fa p .
p If .Fa *op is .Dv NULL , .Fn ppath_copydel_object creates a shallow copy of .Fa o at .Fa *op . If .Fa *op is not .Dv NULL , .Fn ppath_copydel_object expects for .Fa *op to be an existing shallow copy of .Fa o .
p For the purposes of .Fn ppath_copydel_object , .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_object modifies a property shared by .Fa *op and .Fa o , it creates a private copy of the property for .Fa *op . t Fn ppath_copyset_object "prop_object_t o" "prop_object_t *op" \ "const ppath_t *p" "prop_object_t v" Create a copy of the property list .Fa o at .Fa *op . In the copy, replace with .Fa v the property named by .Fa p .
p If .Fa *op is .Dv NULL , .Fn ppath_copyset_object creates a shallow copy of .Fa o at .Fa *op . If .Fa *op is not .Dv NULL , .Fn ppath_copyset_object expects for .Fa *op to be an existing shallow copy of .Fa o .
p
For the purposes of
.Fn ppath_copyset_object ,
.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_object
modifies a property shared by
.Fa *op
and
.Fa o ,
it creates a private copy of the property for
.Fa *op .
t Fn ppath_set_object "prop_object_t o" "const ppath_t *p" "prop_object_t v" Replace with
.Fa v
the
.Vt prop_object_t
in
.Fa o
named by
.Fa p .
t Fn ppath_get_object "prop_object_t o" "const ppath_t *p" "prop_object_t *vp" Retrieve the
.Vt prop_object_t
named by
.Fa p
from
.Fa o ,
and write it to
.Fa *vp .
.Fn ppath_get_object
does
.Em not
increase the reference count of the retrieved object.
t Fn ppath_delete_object "prop_object_t o" "const ppath_t *p" Delete the
.Vt prop_object_t
named by
.Fa p
from
.Fa o .
.Fn ppath_delete_object
decreases by one the deleted object'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 The
.Nm
call requested a
t Bq Er ENOENT .Fn ppath_copyset_object ,
.Fn ppath_delete_object ,
.Fn ppath_get_object ,
and
.Fn ppath_set_object
return
.Er ENOENT
if the path
.Fa p
does not exist in
.Fa o .
t Bq Er ENOMEM .Fn ppath_set_object
and
.Fn ppath_copyset_object
will 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_number 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
Indexes created Sun Sep 21 20:09:37 GMT 2025