1 files changed, 306 insertions, 0 deletions
diff --git a/usr/src/man/man3pool/pool_associate.3pool b/usr/src/man/man3pool/pool_associate.3pool
new file mode 100644
index 0000000..4584697
--- /dev/null
+++ b/usr/src/man/man3pool/pool_associate.3pool
@@ -0,0 +1,306 @@
+'\" 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]
+.TH POOL_ASSOCIATE 3POOL "Jul 18, 2005"
+.SH NAME
+pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info,
+pool_query_pool_resources \- resource pool manipulation functions
+.SH SYNOPSIS
+.LP
+.nf
+cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
+#include <pool.h>
+
+\fBint\fR \fBpool_associate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fB pool_t *\fR\fIpool\fR,
+     \fBpool_resource_t *\fR\fIresource\fR);
+.fi
+
+.LP
+.nf
+\fBpool_t *\fR\fBpool_create\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBpool_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBpool_dissociate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
+     \fBpool_resource_t *\fR\fIresource\fR);
+.fi
+
+.LP
+.nf
+\fBconst char *\fR\fBpool_info\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
+     \fBint\fR \fIflags\fR);
+.fi
+
+.LP
+.nf
+\fBpool_resource_t **\fR\fBpool_query_pool_resources\fR(\fBpool_conf_t *\fR\fIconf\fR,
+     \fBpool_t *\fR\fIpool\fR, \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIproperties\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+These functions provide mechanisms for constructing and modifying pools entries
+within a target pools configuration.  The \fIconf\fR argument for each function
+refers to the target configuration to which the operation applies.
+.sp
+.LP
+The \fBpool_associate()\fR function associates the specified resource with
+\fIpool\fR. 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.
+.sp
+.LP
+The \fBpool_create()\fR function creates a new pool with the supplied name with
+its default properties initialized, and associated with the default resource of
+each type.
+.sp
+.LP
+The \fBpool_destroy function()\fR destroys the given pool association.
+Associated resources are not modified.
+.sp
+.LP
+The \fBpool_dissociate()\fR 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.
+.sp
+.LP
+The \fBpool_info()\fR function returns a string describing the given pool. The
+string is allocated with \fBmalloc\fR(3C). The caller is reponsible for freeing
+the returned string. If the \fIflags\fR option is non-zero, the string returned
+also describes the associated resources of the pool.
+.sp
+.LP
+The \fBpool_query_pool_resources()\fR 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 \fInelem\fR
+argument is set to be the length of the array returned.
+.SH RETURN VALUES
+.sp
+.LP
+Upon successful completion, \fBpool_create()\fR returns a new initialized pool.
+Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the
+pool-specific error value.
+.sp
+.LP
+Upon successful completion, \fBpool_associate()\fR, \fBpool_destroy()\fR, and
+\fBpool_dissociate()\fR return 0. Otherwise, they return -1 and
+\fBpool_error()\fR returns the pool-specific error value.
+.sp
+.LP
+Upon successful completion, \fBpool_info()\fR returns a string describing the
+given pool. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the
+pool-specific error value.
+.sp
+.LP
+Upon successful completion, \fBpool_query_pool_resources()\fR returns a
+null-terminated array of resources. Otherwise it returns \fINULL\fR and
+\fBpool_error()\fR returns the pool-specific error value.
+.SH ERRORS
+.sp
+.LP
+The \fBpool_create()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 20n
+The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is
+already in use.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_SYSTEM\fR\fR
+.ad
+.RS 20n
+A system error has occurred. Check the system error code for more details.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_INVALID_CONF\fR\fR
+.ad
+.RS 20n
+The pool element could not be created because the configuration would be
+invalid.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_PUTPROP\fR\fR
+.ad
+.RS 20n
+One of the supplied properties could not be set.
+.RE
+
+.sp
+.LP
+The \fBpool_destroy()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 16n
+The supplied configuration's status is not \fBPOF_VALID\fR.
+.RE
+
+.sp
+.LP
+The \fBpool_associate()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 16n
+The supplied configuration's status is not \fBPOF_VALID\fR or the parameters
+are supplied from a different configuration.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_SYSTEM\fR\fR
+.ad
+.RS 16n
+A system error has occurred. Check the system error code for more details.
+.RE
+
+.sp
+.LP
+The \fBpool_disassociate()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 20n
+The supplied configuration's status is not \fBPOF_VALID\fR or the parameters
+are supplied from a different configuration.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_INVALID_CONF\fR\fR
+.ad
+.RS 20n
+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.)
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_SYSTEM\fR\fR
+.ad
+.RS 20n
+A system error has occurred. Check the system error code for more details.
+.RE
+
+.sp
+.LP
+The \fBpool_info()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 20n
+The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR
+paramter is neither 0 or 1.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_INVALID_CONF\fR\fR
+.ad
+.RS 20n
+The configuration is invalid.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_SYSTEM\fR\fR
+.ad
+.RS 20n
+A system error has occurred. Check the system error code for more details.
+.RE
+
+.sp
+.LP
+The \fBpool_query_pool_resources()\fR function will fail if:
+.sp
+.ne 2
+.na
+\fB\fBPOE_BADPARAM\fR\fR
+.ad
+.RS 20n
+The supplied configuration's status is not \fBPOF_VALID\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_INVALID_CONF\fR\fR
+.ad
+.RS 20n
+The configuration is invalid.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOE_SYSTEM\fR\fR
+.ad
+.RS 20n
+A system error has occurred. Check the system error code for more details.
+.RE
+
+.SH USAGE
+.sp
+.LP
+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.
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+box;
+c | c
+l | l .
+ATTRIBUTE TYPE	ATTRIBUTE VALUE
+_
+CSI	Enabled
+_
+Interface Stability	Unstable
+_
+MT-Level	Safe
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)