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
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
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
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)
|
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
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
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
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)
|