[src/trunk]: src Add sources, Makefiles, and manual pages for ppath(3), a

[dyoung <dyoung%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/bbaa8390cd5d
branches:  trunk
changeset: 768706:bbaa8390cd5d
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Thu Aug 25 14:55:36 2011 +0000

description:
Add sources, Makefiles, and manual pages for ppath(3), a
property-container path library that is usable from both userland and
the kernel.

TBD: hook this into the build, update set lists, and add automated
tests.

diffstat:

 common/lib/libppath/Makefile.inc       |    5 +
 common/lib/libppath/ppath.3            |  444 +++++++++++++++
 common/lib/libppath/ppath.c            |  924 +++++++++++++++++++++++++++++++++
 common/lib/libppath/ppath_bool.3       |  236 ++++++++
 common/lib/libppath/ppath_extant.c     |   48 +
 common/lib/libppath/ppath_kmem_alloc.c |   48 +
 common/lib/libppath/ppath_malloc.c     |   50 +
 common/lib/libppath/ppath_number.3     |  281 ++++++++++
 common/lib/libppath/ppath_object.3     |  279 +++++++++
 lib/libppath/Makefile                  |   68 ++
 lib/libppath/ppath_malloc.c            |   50 +
 lib/libppath/shlib_version             |    4 +
 12 files changed, 2437 insertions(+), 0 deletions(-)

diffs (truncated from 2485 to 300 lines):

diff -r f2c44821b876 -r bbaa8390cd5d common/lib/libppath/Makefile.inc
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/common/lib/libppath/Makefile.inc  Thu Aug 25 14:55:36 2011 +0000
@@ -0,0 +1,5 @@
+#      $NetBSD: Makefile.inc,v 1.1 2011/08/25 14:55:36 dyoung Exp $
+
+.PATH: ${.PARSEDIR}
+
+SRCS+= ppath.c ppath_extant.c
diff -r f2c44821b876 -r bbaa8390cd5d common/lib/libppath/ppath.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/common/lib/libppath/ppath.3       Thu Aug 25 14:55:36 2011 +0000
@@ -0,0 +1,444 @@
+.\"    $NetBSD: ppath.3,v 1.1 2011/08/25 14:55:36 dyoung Exp $
+.\"    $Id: ppath.3,v 1.1 2011/08/25 14:55:36 dyoung 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@localhost>.
+.\"
+.\" 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 3
+.Os
+.Sh NAME
+.Nm ppath ,
+.Nm ppath_idx ,
+.Nm ppath_key ,
+.\" ,
+.Nm ppath_component_retain ,
+.Nm ppath_component_release ,
+.\" ,
+.Nm ppath_create ,
+.Nm ppath_length ,
+.Nm ppath_component_idx ,
+.Nm ppath_component_key ,
+.Nm ppath_pop ,
+.Nm ppath_push ,
+.Nm ppath_component_at ,
+.Nm ppath_subpath ,
+.Nm ppath_push_idx ,
+.Nm ppath_push_key ,
+.Nm ppath_replace_idx ,
+.Nm ppath_replace_key ,
+.\" ,
+.Nm ppath_copy ,
+.Nm ppath_retain ,
+.Nm ppath_release ,
+.\" ,
+.Nm ppath_lookup ,
+.\" ,
+.Nd property container path library
+.Sh LIBRARY
+.Lb libppath
+.Sh SYNOPSIS
+.In ppath/ppath.h
+.\"
+.Ft "ppath_component_t *"
+.Fn ppath_idx "unsigned int index"
+.Ft "ppath_component_t *"
+.Fn ppath_key "const char *key"
+.\"
+.Ft "ppath_component_t *"
+.Fn ppath_component_retain "ppath_component_t *pc"
+.Ft void
+.Fn ppath_component_release "ppath_component_t *pc"
+.\"
+.Ft "ppath_t *"
+.Fn ppath_create "void"
+.Ft "unsigned int"
+.Fn ppath_length "const ppath_t *p"
+.Ft int
+.Fn ppath_component_idx "const ppath_component_t *"
+.Ft const char *
+.Fn ppath_component_key "const ppath_component_t *"
+.Ft "ppath_t *"
+.Fn ppath_pop "ppath_t *" "ppath_component_t **"
+.Ft ppath_t *
+.Fn ppath_push "ppath_t *" "ppath_component_t *"
+.Ft ppath_component_t *
+.Fn ppath_component_at "const ppath_t *" "unsigned int"
+.Ft ppath_t *
+.Fn ppath_subpath "const ppath_t *" "unsigned int" "unsigned int"
+.Ft ppath_t *
+.Fn ppath_push_idx "ppath_t *" "unsigned int"
+.Ft ppath_t *
+.Fn ppath_push_key "ppath_t *" "const char *"
+.Ft ppath_t *
+.Fn ppath_replace_idx "ppath_t *" "unsigned int"
+.Ft ppath_t *
+.Fn ppath_replace_key "ppath_t *" "const char *"
+.\"
+.Ft ppath_t *
+.Fn ppath_copy "const ppath_t *"
+.Ft ppath_t *
+.Fn ppath_retain "ppath_t *"
+.Ft void
+.Fn ppath_release "ppath_t *"
+.\"
+.Ft prop_object_t
+.Fn ppath_lookup "prop_object_t" "const ppath_t *"
+.\"
+.Sh DESCRIPTION
+The
+.Nm
+library provides functions to read, write, or delete objects in a
+property list.
+A property-list
+.Dq path
+names the object in a property list to read, write, or delete.
+.Pp
+A property-list path is an ordered array of zero or more array
+indices and dictionary keys that names at most one
+.Vt prop_object_t
+in a property list.
+The abstract function
+.Fn E
+evaluates
+a property-list path against a 
+.Vt prop_object_t ,
+.Va o ,
+to yield a
+.Vt prop_object_t
+result according to the following recursive definition, where
+.Fa empty
+indicates the empty
+.Pq zero-length
+path and the operator
+.Dq |
+indicates the concatenation of the path on the left-hand side with
+the key or index on the right-hand side:
+.Bl -tag -width "E(o, p | index)"
+.It Fn E "o" "empty"
+Evaluates to
+.Fa o .
+.It Fn E "o" "p | index"
+If
+.Fn E "o" "p"
+evaluates to a
+.Vt prop_array_t ,
+then
+.Fn E "o" "p | index"
+evaluates to the
+.Fa index 'th
+element of that array.
+Otherwise, an error occurs.
+.It Fn E "o" "p | key"
+If
+.Fn E "o" "p"
+evaluates to a
+.Vt prop_dictionary_t ,
+then
+.Fn E "o" "p | key"
+evaluates to the dictionary value stored under
+.Fa key .
+Otherwise, an error occurs.
+.El
+.Pp
+The programmer may think of property-list paths as working similarly
+to paths in a file system, where property arrays and dictionaries
+correspond to directories, and all other property types correspond
+to files.
+.Pp
+.Sh DATA TYPES
+.Nm
+provides two opaque types:
+.Bl -tag -width ppath_component
+.It Vt ppath_component_t
+A property-list path component: a single key or index.
+.Nm
+counts references to a 
+.Vt ppath_component_t
+and reclaims its storage when there are no more references.
+.It Vt ppath_t
+An array of zero or more property-list path components.
+.Nm
+counts references to a 
+.Vt ppath_t
+and reclaims its storage when there are no more references.
+.El
+.Sh FUNCTIONS
+.Nm
+provides these functions for manipulating property-list paths
+and their components:
+.Bl -tag -width ppath
+.It Fn ppath_idx "unsigned int index"
+Allocate a new
+.Vt ppath_component_t
+for the given array index and return it.
+Its reference count is initially one.
+.Pp
+If there is not sufficient memory to complete the request, return
+.Dv NULL .
+.It Fn ppath_key "const char *key"
+Allocate a new
+.Vt ppath_component_t
+for the given dictionary key and return it.
+Its reference count is initially one.
+.Pp
+If there is not sufficient memory to complete the request, return
+.Dv NULL .
+.\"
+.It Fn ppath_component_retain "ppath_component_t *pc"
+Increase the reference count on
+.Fa pc
+by one.
+.It Fn ppath_component_release "ppath_component_t *pc"
+Decrease the reference count on
+.Fa pc
+by one.
+If the reference count reaches zero, reclaim the storage
+for
+.Fa pc .
+.\"
+.It Fn ppath_create "void"
+Create a new property-list path and return it.
+Its reference count is initially one.
+The path's length is initially zero.
+.Pp
+If there is not sufficient memory to complete the request, return
+.Dv NULL .
+.It Fn ppath_length "const ppath_t *p"
+Return the number of components in path
+.Fa p .
+.It Fn ppath_component_idx "const ppath_component_t *pc"
+Return the array index represented by the component
+.Fa pc ,
+or \-1 if
+.Fa pc
+does not represent an array index.
+.It Fn ppath_component_key "const ppath_component_t *pc"
+Return the dictionary key represented by the component
+.Fa pc ,
+or
+.Dv NULL
+if
+.Fa pc
+does not represent a dictionary key.
+.It Fn ppath_pop "ppath_t *p" "ppath_component_t **pcp"
+If
+.Fa p
+is the empty path or
+.Dv NULL ,
+return
+.Dv NULL.
+Otherwise, remove the last component from
+.Fa p
+and return
+.Fa p ,
+and if
+.Fa pcp 
+is not
+.Dv NULL ,
+write the removed component to
+.Fa "*pcp" .
+.It Fn ppath_push "ppath_t *p" "ppath_component_t *pc"
+If
+either
+.Fa p
+is
+.Dv NULL
+or no more components can be added to
+.Fa p ,
+return
+.Dv NULL .
+Otherwise, append
+.Fa pc
+to the end of the component array
+.Fa p
+and return
+.Fa p .
+.It Fn ppath_component_at "const ppath_t *p" "unsigned int i"
+If
+either
+.Fa p
+is
+.Dv NULL
+or there is no