usr/src/man/man3pool/pool_resource_create.3pool

   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)