[src/trunk]: src Add generic properties.

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

details:   https://anonhg.NetBSD.org/src/rev/26eee1bbe2a0
branches:  trunk
changeset: 515782:26eee1bbe2a0
user:      eeh <eeh%NetBSD.org@localhost>
date:      Thu Oct 04 18:56:06 2001 +0000

description:
Add generic properties.

diffstat:

 share/man/man9/properties.9 |  296 +++++++++++++
 sys/kern/subr_prop.c        |  966 ++++++++++++++++++++++++++++++++++++++++++++
 sys/sys/properties.h        |  118 +++++
 3 files changed, 1380 insertions(+), 0 deletions(-)

diffs (truncated from 1392 to 300 lines):

diff -r f01d3244f784 -r 26eee1bbe2a0 share/man/man9/properties.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/properties.9       Thu Oct 04 18:56:06 2001 +0000
@@ -0,0 +1,296 @@
+.\" $NetBSD: properties.9,v 1.1 2001/10/04 18:56:43 eeh Exp $
+.\"
+.\" Copyright (c) 2001 Eduardo Horvath
+.\" All rights reserved.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"          This product includes software developed for the
+.\"          NetBSD Project.  See http://www.netbsd.org/ for
+.\"          information about NetBSD.
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 THE AUTHOR 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 October 3, 2001
+.Dt PROPERTIES 9
+.Os
+.Sh NAME
+.Nm propdb_create ,
+.Nm propdb_destroy ,
+.Nm prop_set ,
+.Nm prop_get ,
+.Nm prop_delete ,
+.Nm prop_copy ,
+.Nm prop_objs ,
+.Nm prop_list
+.Nd generic kernel properties
+.Sh SYNOPSIS
+.Fd #include <sys/properties.h>
+.Pp
+.Va typedef void *propdb_t
+.Pp
+.Va typedef int64_t opaque_t
+.Ft propdb_t
+.Fn propdb_create "const char *name"
+.Ft void
+.Fn propdb_destroy "propdb_t db"
+.Ft int
+.Fn prop_set "propdb_t db" "opaque_t object" "const char *name" "void *val" \
+"size_t len" "int type" "int wait"
+.Ft size_t
+.Fn prop_get "propdb_t db" "opaque_t object" "const char *name" "void *val" \
+"size_t len" "int *type"
+.Ft int
+.Fn prop_delete "propdb_t db" "opaque_t object" "const char *name"
+.Ft int
+.Fn prop_copy "propdb_t db" "opaque_t source" "opaque_t dest" "int wait"
+.Ft size_t
+.Fn prop_objs "propdb_t db" "opaque_t *objects" "size_t len"
+.Ft size_t
+.Fn prop_list "propdb_t db" "opaque_t object" "char *names" "size_t len"
+.Sh DESCRIPTION
+The
+.Nx
+property management routines allow kernel subsystems to associate
+.Po name, value
+.Pc pairs with arbitrary keys in a generalized manner.
+.Pp
+A database is a container for a set of properties.  It is created with
+.Fn propdb_create
+and discarded with 
+.Fn propdb_destroy .
+Kernel subsystems should create their own databases to prevent possible
+namespace conflicts.
+.Pp
+A property is a tuple that consists of an opaque identifier 
+.Po often a pointer to a kernel data structure
+.Pc , string, and an arbitrary amount of data.  This
+association is established by 
+.Fn prop_set , 
+retrieved by 
+.Fn prop_get , 
+and destroyed by
+.Fn prop_delete .
+.Pp
+A system call interface makes use of the existing 
+.Ic sysctl
+interface, and is provided
+primarily for diagnostic purposes.
+.Pp
+.Sh TYPES
+Several types are defined in 
+.Pa Aq sys/properties.h .
+.Pp 
+.Bl -ohang -compact
+.It Fa propdb_t
+.Pp 
+The 
+.Fa probdb_t
+type is used to contain a handle for a property database.
+.Pp
+.It Fa opaque_t
+.Pp 
+The 
+.Fa opaque_t
+type is a 64-bit scalar type used to store arbitrary object identifiers.
+.Pp
+The
+.Nm
+makes no type distinctions, but it does associate a type datum with each 
+property.  Users of the interface can use that field to help determine what
+information is stored in the value field of the property.  There are three
+base types:
+.El
+.Pp
+.Bl -tag -width "PROP_ELSZ(type)" -compact -offset indent
+.It PROP_INT
+Property is an integer type.
+.It PROP_STRING
+Property is a string.
+.It PROP_AGGREGATE
+Property is an aggregation of different types.
+.El
+.Pp
+Which can be further modified:
+.Pp
+.Bl -tag -width "PROP_ELSZ(type)" -compact -offset indent
+.It PROP_ARRAY
+Property is an array of values.
+.It PROP_CONST
+Property value has static storage and is maintained outside the database.
+.It PROP_ELSZ
+.Pq Fa size
+Encode element size into the type field.  This is primarily used to describe
+the size of individual elements of an array.
+.El
+.Pp
+.Sh FUNCTIONS
+.Pp
+.Bl -tag -width indent
+.It Fn "propdb_t propdb_create" "const char *name"
+.Pp
+Allocate and initialize a kernel database object, and associate 
+.Fa name
+with the database.  
+.Fa name 
+may later be used to access this database from userland throught the 
+userland database query interface.  This operation may block.
+Returns 
+.Li NULL 
+on failure.
+.Pp
+.It Fn "void propdb_destroy" "propdb_t db"
+Destroy and deallocate a kernel database and all data within.  This
+routine deallocates all properties contained within the database.
+.Pp
+.It Fn "int prop_set" "propdb_t db" "opaque_t object" "const char *name" \
+"void *val" "size_t len" "int type" "int wait"
+Create a property 
+.Fa name
+associated with 
+.Fa object 
+inside database 
+.Fa db , 
+with a
+.Fa len
+byte value copied from location 
+.Fa val .  
+The database must already have been initialized with 
+.Fn propdb_create .  
+.Fa object
+is treated as an opaque value.  If
+.Fa len
+is 
+.Li 0
+then no data is copied.  This can be used to create properties which
+convey information by their presence or absence.  The 
+.Fa type 
+field is used to identify what the format of the object is.  This value 
+is usually only used to help programs dump property values into human 
+readable formats.  However, if 
+.Li PROP_CONST 
+is specified in the 
+.Fa type
+field, no storage is allocated for the value, and when the property is 
+queried it will copy 
+.Fa len 
+bytes directly from the location specified by 
+.Fa val , 
+so that data cannot be freed or the kernel may panic.  If 
+.Fa wait
+is zero then 
+.Fn prop_set
+will not sleep for resource shortage.  Returns 
+.Li 0 
+on success, or an error value.
+.Pp
+.It Fn "size_t prop_get" "propdb_t db" "opaque_t object" "const char *name" \
+"void *val" "size_t len" "int *type"
+Retrieve a property called 
+.Fa name
+associated with 
+.Fa object .  
+.Fa name 
+is a pointer to a string.  The property that matches both 
+.Fa object
+and 
+.Fa name 
+will be selected, and the data and type information associated with that 
+property will be returned in the buffers pointed to by 
+.Fa val
+and 
+.Fa type 
+as appropriate.
+.Pp
+Returns 
+.Li -1 
+if the property cannot be found, otherwise it returns the length of the 
+value data, and copies up to 
+.Fa len 
+bytes of the property data to the location pointed to by 
+.Fa val .  
+If 
+.Fa type
+is not 
+.Li NULL ,
+the type information associated with that property is stored in the location 
+it points to.
+.Pp
+.It Fn "int prop_delete" "propdb_t db" "opaque_t object" "const char *name"
+Remove a property from a database.  If a 
+.Li NULL 
+is supplied for 
+.Fa name ,
+.Fn prop_delete 
+will remove all properties associated with 
+.Fa object .  
+It returns the number of properties deleted.
+.Pp
+.It Fn "int prop_copy" "propdb_t db" "opaque_t source" "opaque_t dest" \
+"int wait"
+Copy all properties associated with 
+.Fa source
+to 
+.Fa dest
+structure.  If 
+.Fa wait
+is zero then 
+.Fn prop_copy 
+will not sleep for resource shortage.  Returns 
+.Li 0 
+on success or an error value.  The state of properties is undefined if the
+operation fails.
+.It Fn "size_t prop_objs" "propdb_t db" "opaque_t *objects" "size_t len"
+Get a list of objects identifiers from a database.  An array of object
+idientifiers will be copied into the buffer pointed to by 
+.Fa objects 
+up to 
+.Fa len
+bytes.  It returns the amount of memory needed to store the entire list.
+.Pp
+.It Fn "size_t prop_list" "propdb_t db" "opaque_t object" "char *names" \
+"size_t len"
+Get a list of an object's properties from the database.  It queries the
+database to locate all properties associated with 
+.Pa object
+objedt identifier, and copies up to 
+.Pa len 
+bytes of 
+.Li NUL 
+terminated property names into the buffer pointed to by 
+.Pa names .  
+Partial strings are not copied, and another NUL character to indicate the
+termination of the list.  It returns the size needed to hold the
+entire list.
+.El
+.Pp
+.Sh AUTHORS
+The
+.Nx
+property management system was developed by Eduardo Horvath <eeh%netbsd.org@localhost>
+.Sh SEE ALSO
+.Sh HISTORY
+The
+.Nx
+property management system first appeared in
+.Nx 1.6 .