1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH POOL_ASSOCIATE 3POOL "January 15, 2020"
   7 .SH NAME
   8 pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info,
   9 pool_query_pool_resources \- resource pool manipulation functions
  10 .SH SYNOPSIS
  11 .nf
  12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <pool.h>
  14 
  15 \fBint\fR \fBpool_associate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fB pool_t *\fR\fIpool\fR,
  16      \fBpool_resource_t *\fR\fIresource\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBpool_t *\fR\fBpool_create\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR);
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBint\fR \fBpool_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR);
  27 .fi
  28 
  29 .LP
  30 .nf
  31 \fBint\fR \fBpool_dissociate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
  32      \fBpool_resource_t *\fR\fIresource\fR);
  33 .fi
  34 
  35 .LP
  36 .nf
  37 \fBconst char *\fR\fBpool_info\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
  38      \fBint\fR \fIflags\fR);
  39 .fi
  40 
  41 .LP
  42 .nf
  43 \fBpool_resource_t **\fR\fBpool_query_pool_resources\fR(\fBpool_conf_t *\fR\fIconf\fR,
  44      \fBpool_t *\fR\fIpool\fR, \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIproperties\fR);
  45 .fi
  46 
  47 .SH DESCRIPTION
  48 These functions provide mechanisms for constructing and modifying pools entries
  49 within a target pools configuration.  The \fIconf\fR argument for each function
  50 refers to the target configuration to which the operation applies.
  51 .sp
  52 .LP
  53 The \fBpool_associate()\fR function associates the specified resource with
  54 \fIpool\fR. A resource can be associated with multiple pools at the same time.
  55 Any resource of this type that was formerly associated with this pool is no
  56 longer associated with the pool. The new association replaces the earlier one.
  57 .sp
  58 .LP
  59 The \fBpool_create()\fR function creates a new pool with the supplied name with
  60 its default properties initialized, and associated with the default resource of
  61 each type.
  62 .sp
  63 .LP
  64 The \fBpool_destroy function()\fR destroys the given pool association.
  65 Associated resources are not modified.
  66 .sp
  67 .LP
  68 The \fBpool_dissociate()\fR function removes the association between the given
  69 resource and pool. On successful completion, the pool is associated with the
  70 default resource of the same type.
  71 .sp
  72 .LP
  73 The \fBpool_info()\fR function returns a string describing the given pool. The
  74 string is allocated with \fBmalloc\fR(3C). The caller is responsible for freeing
  75 the returned string. If the \fIflags\fR option is non-zero, the string returned
  76 also describes the associated resources of the pool.
  77 .sp
  78 .LP
  79 The \fBpool_query_pool_resources()\fR function returns a null-terminated array
  80 of resources currently associated with the pool that match the given list of
  81 properties. The return value must be freed by the caller. The \fInelem\fR
  82 argument is set to be the length of the array returned.
  83 .SH RETURN VALUES
  84 Upon successful completion, \fBpool_create()\fR returns a new initialized pool.
  85 Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the
  86 pool-specific error value.
  87 .sp
  88 .LP
  89 Upon successful completion, \fBpool_associate()\fR, \fBpool_destroy()\fR, and
  90 \fBpool_dissociate()\fR return 0. Otherwise, they return -1 and
  91 \fBpool_error()\fR returns the pool-specific error value.
  92 .sp
  93 .LP
  94 Upon successful completion, \fBpool_info()\fR returns a string describing the
  95 given pool. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the
  96 pool-specific error value.
  97 .sp
  98 .LP
  99 Upon successful completion, \fBpool_query_pool_resources()\fR returns a
 100 null-terminated array of resources. Otherwise it returns \fINULL\fR and
 101 \fBpool_error()\fR returns the pool-specific error value.
 102 .SH ERRORS
 103 The \fBpool_create()\fR function will fail if:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBPOE_BADPARAM\fR\fR
 108 .ad
 109 .RS 20n
 110 The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is
 111 already in use.
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBPOE_SYSTEM\fR\fR
 118 .ad
 119 .RS 20n
 120 A system error has occurred. Check the system error code for more details.
 121 .RE
 122 
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBPOE_INVALID_CONF\fR\fR
 127 .ad
 128 .RS 20n
 129 The pool element could not be created because the configuration would be
 130 invalid.
 131 .RE
 132 
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBPOE_PUTPROP\fR\fR
 137 .ad
 138 .RS 20n
 139 One of the supplied properties could not be set.
 140 .RE
 141 
 142 .sp
 143 .LP
 144 The \fBpool_destroy()\fR function will fail if:
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBPOE_BADPARAM\fR\fR
 149 .ad
 150 .RS 16n
 151 The supplied configuration's status is not \fBPOF_VALID\fR.
 152 .RE
 153 
 154 .sp
 155 .LP
 156 The \fBpool_associate()\fR function will fail if:
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBPOE_BADPARAM\fR\fR
 161 .ad
 162 .RS 16n
 163 The supplied configuration's status is not \fBPOF_VALID\fR or the parameters
 164 are supplied from a different configuration.
 165 .RE
 166 
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBPOE_SYSTEM\fR\fR
 171 .ad
 172 .RS 16n
 173 A system error has occurred. Check the system error code for more details.
 174 .RE
 175 
 176 .sp
 177 .LP
 178 The \fBpool_disassociate()\fR function will fail if:
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBPOE_BADPARAM\fR\fR
 183 .ad
 184 .RS 20n
 185 The supplied configuration's status is not \fBPOF_VALID\fR or the parameters
 186 are supplied from a different configuration.
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBPOE_INVALID_CONF\fR\fR
 193 .ad
 194 .RS 20n
 195 No resources could be located for the supplied configuration or the supplied
 196 configuration is not valid (for example, more than one default for a resource
 197 type was found.)
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBPOE_SYSTEM\fR\fR
 204 .ad
 205 .RS 20n
 206 A system error has occurred. Check the system error code for more details.
 207 .RE
 208 
 209 .sp
 210 .LP
 211 The \fBpool_info()\fR function will fail if:
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBPOE_BADPARAM\fR\fR
 216 .ad
 217 .RS 20n
 218 The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR
 219 parameter is neither 0 or 1.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBPOE_INVALID_CONF\fR\fR
 226 .ad
 227 .RS 20n
 228 The configuration is invalid.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBPOE_SYSTEM\fR\fR
 235 .ad
 236 .RS 20n
 237 A system error has occurred. Check the system error code for more details.
 238 .RE
 239 
 240 .sp
 241 .LP
 242 The \fBpool_query_pool_resources()\fR function will fail if:
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fBPOE_BADPARAM\fR\fR
 247 .ad
 248 .RS 20n
 249 The supplied configuration's status is not \fBPOF_VALID\fR.
 250 .RE
 251 
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBPOE_INVALID_CONF\fR\fR
 256 .ad
 257 .RS 20n
 258 The configuration is invalid.
 259 .RE
 260 
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBPOE_SYSTEM\fR\fR
 265 .ad
 266 .RS 20n
 267 A system error has occurred. Check the system error code for more details.
 268 .RE
 269 
 270 .SH USAGE
 271 Pool names are unique across pools in a given configuration file. It is an
 272 error to attempt to create a pool with a name that is currently used by another
 273 pool within the same configuration.
 274 .SH ATTRIBUTES
 275 See \fBattributes\fR(5) for descriptions of the following attributes:
 276 .sp
 277 
 278 .sp
 279 .TS
 280 box;
 281 c | c
 282 l | l .
 283 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 284 _
 285 CSI     Enabled
 286 _
 287 Interface Stability     Unstable
 288 _
 289 MT-Level        Safe
 290 .TE
 291 
 292 .SH SEE ALSO
 293 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)