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 18, 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\\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)