PROPERTIES(9)

NAME
propdb_create, propdb_destroy, prop_set, prop_get, prop_delete, prop_copy, prop_objs, prop_list - generic kernel properties

SYNOPSIS
#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);

DESCRIPTION
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.

TYPES
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.

FUNCTIONS

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 through 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 object identifiers from a database. An array of object identifiers 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, 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.

HISTORY
The NetBSD property management system first appeared in NetBSD 1.6.

AUTHORS
The NetBSD property management system was developed by Eduardo Horvath <eeh@NetBSD.org>.