.\" $NetBSD: properties.9,v 1.2 2001/10/04 19:39:41 wiz 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.
.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
.Sh FUNCTIONS
.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
.Sh HISTORY
The
.Nx
property management system first appeared in
.Nx 1.6 .
.Sh AUTHORS
The
.Nx
property management system was developed by
.An Eduardo Horvath Aq eeh@netbsd.org .