1 '\" te
   2 .\" Copyright (c) 2003, 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_RESOURCE_CREATE 3POOL "April 9, 2016"
   7 .SH NAME
   8 pool_resource_create, pool_resource_destroy, pool_resource_info,
   9 pool_query_resource_components, pool_resource_transfer, pool_resource_xtransfer
  10 \- resource pool resource manipulation functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <pool.h>
  16 
  17 \fBpool_resource_t *\fR\fBpool_resource_create\fR(\fBpool_conf_t *\fR\fIconf\fR,
  18      \fBconst char *\fR\fItype\fR, \fBconst char *\fR\fIname\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBpool_resource_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR,
  24      \fBpool_resource_t *\fR\fIresource\fR);
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBconst char *\fR\fBpool_resource_info\fR(\fBpool_conf_t *\fR\fIconf\fR
  30      \fBpool_resource_t *\fR\fIresource\fR, \fBint\fR \fIflags\fR);
  31 .fi
  32 
  33 .LP
  34 .nf
  35 \fBpool_component_t **\fR\fBpool_query_resource_components\fR(
  36      \fBpool_conf_t *\fR\fIconf\fR, \fBpool_resource_t *\fR\fIresource\fR,
  37      \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIprops\fR);
  38 .fi
  39 
  40 .LP
  41 .nf
  42 \fBint\fR \fBpool_resource_transfer\fR(\fBpool_conf_t *\fR\fIconf\fR,
  43      \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR,
  44      \fBuint64_t\fR \fIsize\fR);
  45 .fi
  46 
  47 .LP
  48 .nf
  49 \fBint\fR \fBpool_resource_xtransfer\fR(\fBpool_conf_t *\fR\fIconf\fR,
  50      \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR,
  51      \fBpool_component_t **\fR\fIcomponents\fR);
  52 .fi
  53 
  54 .SH DESCRIPTION
  55 .LP
  56 The \fBpool_resource_create()\fR function creates and returns a new resource of
  57 the given \fIname\fR and \fItype\fR in the provided configuration. If there is
  58 already a resource of the given name, the operation will fail.
  59 .sp
  60 .LP
  61 The \fBpool_resource_destroy()\fR function removes the specified \fIresource\fR
  62 from its configuration file.
  63 .sp
  64 .LP
  65 The \fBpool_resource_info()\fR function returns a string describing the given
  66 \fIresource\fR. The string is allocated with \fBmalloc\fR(3C). The caller is
  67 responsible for freeing the returned string. If the \fIflags\fR argument is
  68 non-zero, the string returned also describes the components (if any) contained
  69 in the resource.
  70 .sp
  71 .LP
  72 The \fBpool_query_resource_components()\fR function returns a null-terminated
  73 array of the components (if any) that comprise the given resource.
  74 .sp
  75 .LP
  76 The \fBpool_resource_transfer()\fR function transfers \fIsize\fR basic units
  77 from the \fIsource\fR resource to the \fItarget\fR. Both resources must be of
  78 the same type for the operation to succeed. Transferring component resources,
  79 such as processors, is always performed as series of
  80 \fBpool_resource_xtransfer()\fR operations, since discrete resources must be
  81 identified for transfer.
  82 .sp
  83 .LP
  84 The \fBpool_resource_xtransfer()\fR function transfers the specific
  85 \fIcomponents\fR from the \fIsource\fR resource to the \fItarget\fR. Both
  86 resources must be of the same type, and of a type that contains components
  87 (such as processor sets). The \fIcomponents\fR argument is a null-terminated
  88 list of \fBpool_component_t\fR.
  89 .sp
  90 .LP
  91 The \fIconf\fR argument for each function refers to the target configuration to
  92 which the operation applies.
  93 .SH RETURN VALUES
  94 .LP
  95 Upon successful completion, \fBpool_resource_create()\fR returns a new
  96 \fBpool_resource_t\fR with default properties initialized. Otherwise,
  97 \fINULL\fR is returned and \fBpool_error\fR(3POOL) returns the pool-specific
  98 error value.
  99 .sp
 100 .LP
 101 Upon successful completion, \fBpool_resource_destroy()\fR returns 0. Otherwise,
 102 -1 is returned and \fBpool_error()\fR returns the pool-specific error value.
 103 .sp
 104 .LP
 105 Upon successful completion, \fBpool_resource_info()\fR returns a string
 106 describing the given resource (and optionally its components). Otherwise,
 107 \fINULL\fR is returned and \fBpool_error()\fR returns the pool-specific error
 108 value.
 109 .sp
 110 .LP
 111  Upon successful completion, \fBpool_query_resource_components()\fR returns a
 112 null-terminated array of \fBpool_component_t *\fR that match the provided
 113 null-terminated property list and are contained in the given resource.
 114 Otherwise, \fINULL\fR is returned and \fBpool_error()\fR returns the
 115 pool-specific error value.
 116 .sp
 117 .LP
 118  Upon successful completion, \fBpool_resource_transfer()\fR and
 119 \fBpool_resource_xtransfer()\fR return 0. Otherwise -1 is returned and
 120 \fBpool_error()\fR returns the pool-specific error value.
 121 .SH ERRORS
 122 .LP
 123 The \fBpool_resource_create()\fR function will fail if:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBPOE_BADPARAM\fR\fR
 128 .ad
 129 .RS 20n
 130 The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is in
 131 use for this resource type.
 132 .RE
 133 
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBPOE_INVALID_CONF\fR\fR
 138 .ad
 139 .RS 20n
 140 The resource element could not be created because the configuration would be
 141 invalid.
 142 .RE
 143 
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBPOE_PUTPROP\fR\fR
 148 .ad
 149 .RS 20n
 150 One of the supplied properties could not be set.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBPOE_SYSTEM\fR\fR
 157 .ad
 158 .RS 20n
 159  A system error has occurred. Check the system error code for more details.
 160 .RE
 161 
 162 .sp
 163 .LP
 164 The \fBpool_resource_destroy()\fR function will fail if:
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBPOE_BADPARAM\fR\fR
 169 .ad
 170 .RS 16n
 171 The supplied configuration's status is not \fBPOF_VALID\fR.
 172 .RE
 173 
 174 .sp
 175 .LP
 176 The \fBpool_resource_info()\fR function will fail if:
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBPOE_BADPARAM\fR\fR
 181 .ad
 182 .RS 20n
 183 The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR
 184 paramter is neither 0 nor 1.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBPOE_INVALID_CONF\fR\fR
 191 .ad
 192 .RS 20n
 193 The configuration is invalid.
 194 .RE
 195 
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBPOE_SYSTEM\fR\fR
 200 .ad
 201 .RS 20n
 202 A system error has occurred. Check the system error code for more details.
 203 .RE
 204 
 205 .sp
 206 .LP
 207 The \fBpool_query_resource_components()\fR function will fail if:
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBPOE_BADPARAM\fR\fR
 212 .ad
 213 .RS 20n
 214 The supplied configuration's status is not \fBPOF_VALID\fR.
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBPOE_INVALID_CONF\fR\fR
 221 .ad
 222 .RS 20n
 223 The configuration is invalid.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBPOE_SYSTEM\fR\fR
 230 .ad
 231 .RS 20n
 232 A system error has occurred. Check the system error code for more details.
 233 .RE
 234 
 235 .sp
 236 .LP
 237 The \fBpool_resource_transfer()\fR function will fail if:
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBPOE_BADPARAM\fR\fR
 242 .ad
 243 .RS 16n
 244 The supplied configuration's status is not \fBPOF_VALID\fR, the two resources
 245 are not of the same type, or the transfer would cause either of the resources
 246 to exceed their \fBmin\fR and \fBmax\fR properties.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBPOE_SYSTEM\fR\fR
 253 .ad
 254 .RS 16n
 255 A system error has occurred. Check the system error code for more details.
 256 .RE
 257 
 258 .sp
 259 .LP
 260 The \fBpool_resource_xtransfer()\fR function will fail if:
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBPOE_BADPARAM\fR\fR
 265 .ad
 266 .RS 20n
 267 The supplied configuration's status is not \fBPOF_VALID\fR, the two resources
 268 are not of the same type, or the supplied resources do not belong to the
 269 source.
 270 .RE
 271 
 272 .sp
 273 .ne 2
 274 .na
 275 \fB\fBPOE_INVALID_CONF\fR\fR
 276 .ad
 277 .RS 20n
 278 The transfer operation failed and the configuration may be invalid.
 279 .RE
 280 
 281 .sp
 282 .ne 2
 283 .na
 284 \fB\fBPOE_SYSTEM\fR\fR
 285 .ad
 286 .RS 20n
 287 A system error has occurred. Check the system error code for more details.
 288 .RE
 289 
 290 .SH EXAMPLES
 291 .LP
 292 \fBExample 1 \fRCreate a new resource of type \fBpset\fR named \fBfoo\fR.
 293 .sp
 294 .in +2
 295 .nf
 296 #include <pool.h>
 297 #include <stdio.h>
 298 
 299 \&...
 300 
 301 pool_conf_t *conf;
 302 pool_resource_t *resource;
 303 \&...
 304 
 305 if ((resource = pool_resource_create(conf, "pset",
 306     "foo")) == NULL) {
 307     (void) fprintf(stderr, "Cannot create resource\\B{}n");
 308     ...
 309 }
 310 .fi
 311 .in -2
 312 
 313 .SH ATTRIBUTES
 314 .LP
 315 See \fBattributes\fR(5) for descriptions of the following attributes:
 316 .sp
 317 
 318 .sp
 319 .TS
 320 box;
 321 c | c
 322 l | l .
 323 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 324 _
 325 CSI     Enabled
 326 _
 327 Interface Stability     Unstable
 328 _
 329 MT-Level        Safe
 330 .TE
 331 
 332 .SH SEE ALSO
 333 .LP
 334 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)