propdb_create, propdb_destroy, prop_set, prop_get, prop_delete,
prop_copy, prop_objs, prop_list - generic kernel properties
#include <sys/properties.h>
typedef void *propdb_t;
typedef int64_t opaque_t;
propdb_t
propdb_create(const char *name);
void
propdb_destroy(propdb_t db);
int
prop_set(propdb_t db, opaque_t object, const char *name, void *val,
size_t len, int type, int wait);
size_t
prop_get(propdb_t db, opaque_t object, const char *name, void *val,
size_t len, int *type);
int
prop_delete(propdb_t db, opaque_t object, const char *name);
int
prop_copy(propdb_t db, opaque_t source, opaque_t dest, int wait);
size_t
prop_objs(propdb_t db, opaque_t *objects, size_t len);
size_t
prop_list(propdb_t db, opaque_t object, char *names, size_t len);
The NetBSD property management routines allow kernel subsystems to associate
(name, value) pairs with arbitrary keys in a generalized manner.
A database is a container for a set of properties. It is created with
propdb_create() and discarded with propdb_destroy(). Kernel subsystems
should create their own databases to prevent possible namespace conflicts.
A property is a tuple that consists of an opaque identifier (often a
pointer to a kernel data structure), string, and an arbitrary amount of
data. This association is established by prop_set(), retrieved by
prop_get(), and destroyed by prop_delete().
A system call interface makes use of the existing sysctl interface, and
is provided primarily for diagnostic purposes.
Several types are defined in ~ <sys/properties.h>.
propdb_t
The probdb_t type is used to contain a handle for a property database.
opaque_t
The opaque_t type is a 64-bit scalar type used to store arbitrary object
identifiers.
The propdb_create 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:
PROP_INT Property is an integer type.
PROP_STRING Property is a string.
PROP_AGGREGATE Property is an aggregation of different types.
Which can be further modified:
PROP_ARRAY Property is an array of values.
PROP_CONST Property value has static storage and is maintained
outside the database.
PROP_ELSZ (size) Encode element size into the type field. This
is primarily used to describe the size of individual
elements of an array.
propdb_t propdb_create(const char *name)
Allocate and initialize a kernel database object, and associate
name with the database. name may later be used to access this
database from userland throught the userland database query
interface. This operation may block. Returns NULL on failure.
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.
int prop_set(propdb_t db, opaque_t object, const char *name, void *val,
size_t len, int type, int wait)
Create a property name associated with object inside database db,
with a len byte value copied from location val. The database
must already have been initialized with propdb_create(). object
is treated as an opaque value. If len is 0 then no data is
copied. This can be used to create properties which convey
information by their presence or absence. The 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 PROP_CONST is specified in the
type field, no storage is allocated for the value, and when the
property is queried it will copy len bytes directly from the
location specified by val, so that data cannot be freed or the
kernel may panic. If wait is zero then prop_set() will not sleep
for resource shortage. Returns 0 on success, or an error value.
size_t prop_get(propdb_t db, opaque_t object, const char *name, void
*val, size_t len, int *type)
Retrieve a property called name associated with object. name is
a pointer to a string. The property that matches both object and
name will be selected, and the data and type information associated
with that property will be returned in the buffers pointed
to by val and type as appropriate.
Returns -1 if the property cannot be found, otherwise it returns
the length of the value data, and copies up to len bytes of the
property data to the location pointed to by val. If type is not
NULL, the type information associated with that property is
stored in the location it points to.
int prop_delete(propdb_t db, opaque_t object, const char *name)
Remove a property from a database. If a NULL is supplied for
name, prop_delete() will remove all properties associated with
object. It returns the number of properties deleted.
int prop_copy(propdb_t db, opaque_t source, opaque_t dest, int wait)
Copy all properties associated with source to dest structure. If
wait is zero then prop_copy() will not sleep for resource shortage.
Returns 0 on success or an error value. The state of properties
is undefined if the operation fails.
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
objects up to len bytes. It returns the amount of memory needed
to store the entire list.
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
object objedt identifier, and copies up to len bytes of NUL terminated
property names into the buffer pointed to by 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.
The NetBSD property management system first appeared in NetBSD 1.6.
The NetBSD property management system was developed by Eduardo Horvath
<[email protected]>.
BSD October 3, 2001 BSD
[ Back ] |
