310 lines
8.5 KiB
Groff
310 lines
8.5 KiB
Groff
.\" $NetBSD: properties.9,v 1.9 2003/06/30 12:10:40 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
|
|
.In 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
|
|
.Aq Pa 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 through 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 identifiers 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
|
|
object 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 .
|