share/man/man3pool/pool_associate.3pool

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