Tribblix: manual page: pool_get

POOL_GET_PROPERTY(3POOL) Pool Configuration Manipulation Library Functions

NAME

pool_get_property, pool_put_property, pool_rm_property,
pool_walk_properties - resource pool element property manipulation

SYNOPSIS

cc [ flag... ] file... -lpool [ library... ]
#include <pool.h>

pool_value_class_t pool_get_property(pool_conf_t *conf,
const pool_elem_t *elem, const char *name,
pool_value_t *property);

int pool_put_property(pool_conf_t *conf, pool_elem_t *elem,
const char *name, const pool_value_t *value);

int pool_rm_property(pool_conf_t *conf, pool_elem_t *elem,
const char *name);

int pool_walk_properties(pool_conf_t *conf, pool_elem_t *elem,
void *arg, int (*callback)(pool_conf_t *, pool_elem_t *,
const char *, pool_value_t *, void *));

DESCRIPTION

The various pool types are converted to the common pool element type
(pool_elem_t) before property manipulation. A pool_value_t is an
opaque type that contains a property value of one of the following
types:

POC_UINT
unsigned 64-bit integer

POC_INT
signed 64-bit integer

POC_DOUBLE
signed double-precision floating point value

POC_BOOL
boolean value: 0 is false, non-zero is true

POC_STRING
null-terminated string of characters

The conf argument for each function refers to the target
configuration to which the operation applies.

The pool_get_property() function attempts to retrieve the value of
the named property from the element. If the property is not found or
an error occurs, the value POC_INVAL is returned to indicate error.
Otherwise the type of the value retrieved is returned.

The pool_put_property() function attempts to set the named property
on the element to the specified value. Attempting to set a property
that does not currently exist on the element will cause the property
with the given name and value to be created on the element and will
not cause an error. An attempt to overwrite an existing property with
a new property of a different type is an error.

The pool_rm_property() function attempts to remove the named property
from the element. If the property does not exist or is not
removable, -1 is returned and pool_error(3POOL) reports an error of
POE_PUTPROP.

The pool_walk_properties() function invokes callback on all
properties defined for the given element. The callback is called with
the element itself, the name of the property, the value of the
property, and the caller-provided opaque argument.

A number of special properties are reserved for internal use and
cannot be set or removed. Attempting to do so will fail. These
properties are documented on the libpool(3LIB) manual page.

RETURN VALUES

Upon successful completion, pool_get_property() returns the type of
the property. Otherwise it returns POC_INVAL and pool_error() returns
the pool-specific error value.

Upon successful completion, pool_put_property(), pool_rm_property(),
and pool_walk_properties() return 0. Otherwise they return -1 and
pool_error() returns the pool-specific error value.

ERRORS

The pool_get_property() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID,
the supplied conf does not contain the supplied elem,
or the property is restricted and cannot be accessed
by the library.

POE_SYSTEM
A system error has occurred. Check the system error
code for more details.

The pool_put_property() function will fail if:

POE_BADPARAM
The supplied configuration's status is not
POF_VALID, the supplied conf does not contain the
supplied elem, the property name is not in the
correct format, or the property already exists
and the supplied type does not match the existing
type.

POE_SYSTEM
A system error has occurred. Check the system
error code for more details.

POE_PUTPROP
The property name is reserved by libpool and not
available for use.

POE_INVALID_CONF
The configuration is invalid.

The pool_rm_property() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID,
the supplied conf does not contain the supplied elem,
or the property is reserved by libpool and cannot be
removed.

POE_SYSTEM
A system error has occurred. Check the system error
code for more details.

POE_PUTPROP
The property name is reserved by libpool and not
available for use.

The pool_walk_properties() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID.

POE_SYSTEM
A system error has occurred. Check the system error
code for more details.