POOL_ASSOCIATE(3POOL) Pool Configuration Manipulation Library Functions


NAME


pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info,
pool_query_pool_resources - resource pool manipulation functions

SYNOPSIS


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

int pool_associate(pool_conf_t *conf, pool_t *pool,
pool_resource_t *resource);


pool_t *pool_create(pool_conf_t *conf, const char *name);


int pool_destroy(pool_conf_t *conf, pool_t *pool);


int pool_dissociate(pool_conf_t *conf, pool_t *pool,
pool_resource_t *resource);


const char *pool_info(pool_conf_t *conf, pool_t *pool,
int flags);


pool_resource_t **pool_query_pool_resources(pool_conf_t *conf,
pool_t *pool, uint_t *nelem, pool_value_t **properties);


DESCRIPTION


These functions provide mechanisms for constructing and modifying pools
entries within a target pools configuration. The conf argument for each
function refers to the target configuration to which the operation
applies.


The pool_associate() function associates the specified resource with
pool. A resource can be associated with multiple pools at the same time.
Any resource of this type that was formerly associated with this pool is
no longer associated with the pool. The new association replaces the
earlier one.


The pool_create() function creates a new pool with the supplied name with
its default properties initialized, and associated with the default
resource of each type.


The pool_destroy function() destroys the given pool association.
Associated resources are not modified.


The pool_dissociate() function removes the association between the given
resource and pool. On successful completion, the pool is associated with
the default resource of the same type.


The pool_info() function returns a string describing the given pool. The
string is allocated with malloc(3C). The caller is responsible for
freeing the returned string. If the flags option is non-zero, the string
returned also describes the associated resources of the pool.


The pool_query_pool_resources() function returns a null-terminated array
of resources currently associated with the pool that match the given list
of properties. The return value must be freed by the caller. The nelem
argument is set to be the length of the array returned.

RETURN VALUES


Upon successful completion, pool_create() returns a new initialized pool.
Otherwise it returns NULL and pool_error(3POOL) returns the pool-specific
error value.


Upon successful completion, pool_associate(), pool_destroy(), and
pool_dissociate() return 0. Otherwise, they return -1 and pool_error()
returns the pool-specific error value.


Upon successful completion, pool_info() returns a string describing the
given pool. Otherwise it returns NULL and pool_error() returns the pool-
specific error value.


Upon successful completion, pool_query_pool_resources() returns a null-
terminated array of resources. Otherwise it returns NULL and pool_error()
returns the pool-specific error value.

ERRORS


The pool_create() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID
or name is already in use.


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


POE_INVALID_CONF
The pool element could not be created because the
configuration would be invalid.


POE_PUTPROP
One of the supplied properties could not be set.


The pool_destroy() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID.


The pool_associate() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID or
the parameters are supplied from a different
configuration.


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


The pool_disassociate() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID
or the parameters are supplied from a different
configuration.


POE_INVALID_CONF
No resources could be located for the supplied
configuration or the supplied configuration is not
valid (for example, more than one default for a
resource type was found.)


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


The pool_info() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID
or the flags paramter is neither 0 or 1.


POE_INVALID_CONF
The configuration is invalid.


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


The pool_query_pool_resources() function will fail if:

POE_BADPARAM
The supplied configuration's status is not POF_VALID.


POE_INVALID_CONF
The configuration is invalid.


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


USAGE


Pool names are unique across pools in a given configuration file. It is
an error to attempt to create a pool with a name that is currently used
by another pool within the same configuration.

ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|CSI | Enabled |
+--------------------+-----------------+
|Interface Stability | Unstable |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


libpool(3LIB), pool_error(3POOL), attributes(5)


April 9, 2016 POOL_ASSOCIATE(3POOL)