te
Copyright (c) 2003, 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_get_property, pool_put_property, pool_rm_property, pool_walk_properties - resource pool element property manipulation

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

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

POC_INT

POC_DOUBLE

POC_BOOL

POC_STRING

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) reporst 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.

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.

The pool_get_property() function will fail if:

POE_BADPARAM

POE_SYSTEM

The pool_put_property() function will fail if:

POE_BADPARAM

POE_SYSTEM

POE_PUTPROP

POE_INVALID_CONF

The pool_rm_property() function will fail if:

POE_BADPARAM

POE_SYSTEM

POE_PUTPROP

The pool_walk_properties() function will fail if:

POE_BADPARAM

POE_SYSTEM

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)