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