te
Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info, pool_query_pool_resources - resource pool manipulation functions

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

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

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.

The pool_create() function will fail if:

POE_BADPARAM

POE_SYSTEM

POE_INVALID_CONF

POE_PUTPROP

The pool_destroy() function will fail if:

POE_BADPARAM

The pool_associate() function will fail if:

POE_BADPARAM

POE_SYSTEM

The pool_disassociate() function will fail if:

POE_BADPARAM

POE_INVALID_CONF

POE_SYSTEM

The pool_info() function will fail if:

POE_BADPARAM

POE_INVALID_CONF

POE_SYSTEM

The pool_query_pool_resources() function will fail if:

POE_BADPARAM

POE_INVALID_CONF

POE_SYSTEM

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.

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

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

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