1 '\" te
2 .\" Copyright (c) 2005, 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_ASSOCIATE 3POOL "April 9, 2016"
7 .SH NAME
8 pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info,
9 pool_query_pool_resources \- resource pool manipulation functions
10 .SH SYNOPSIS
11 .LP
12 .nf
13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
14 #include <pool.h>
15
16 \fBint\fR \fBpool_associate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fB pool_t *\fR\fIpool\fR,
17 \fBpool_resource_t *\fR\fIresource\fR);
18 .fi
19
20 .LP
21 .nf
22 \fBpool_t *\fR\fBpool_create\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR);
23 .fi
24
25 .LP
26 .nf
27 \fBint\fR \fBpool_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR);
28 .fi
29
30 .LP
31 .nf
32 \fBint\fR \fBpool_dissociate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
33 \fBpool_resource_t *\fR\fIresource\fR);
34 .fi
35
36 .LP
37 .nf
38 \fBconst char *\fR\fBpool_info\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
39 \fBint\fR \fIflags\fR);
40 .fi
41
42 .LP
43 .nf
44 \fBpool_resource_t **\fR\fBpool_query_pool_resources\fR(\fBpool_conf_t *\fR\fIconf\fR,
45 \fBpool_t *\fR\fIpool\fR, \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIproperties\fR);
46 .fi
47
48 .SH DESCRIPTION
49 .LP
50 These functions provide mechanisms for constructing and modifying pools entries
51 within a target pools configuration. The \fIconf\fR argument for each function
52 refers to the target configuration to which the operation applies.
53 .sp
54 .LP
55 The \fBpool_associate()\fR function associates the specified resource with
56 \fIpool\fR. A resource can be associated with multiple pools at the same time.
57 Any resource of this type that was formerly associated with this pool is no
58 longer associated with the pool. The new association replaces the earlier one.
59 .sp
60 .LP
61 The \fBpool_create()\fR function creates a new pool with the supplied name with
62 its default properties initialized, and associated with the default resource of
63 each type.
64 .sp
65 .LP
66 The \fBpool_destroy function()\fR destroys the given pool association.
67 Associated resources are not modified.
68 .sp
69 .LP
70 The \fBpool_dissociate()\fR function removes the association between the given
71 resource and pool. On successful completion, the pool is associated with the
72 default resource of the same type.
73 .sp
74 .LP
75 The \fBpool_info()\fR function returns a string describing the given pool. The
76 string is allocated with \fBmalloc\fR(3C). The caller is responsible for freeing
77 the returned string. If the \fIflags\fR option is non-zero, the string returned
78 also describes the associated resources of the pool.
79 .sp
80 .LP
81 The \fBpool_query_pool_resources()\fR function returns a null-terminated array
82 of resources currently associated with the pool that match the given list of
83 properties. The return value must be freed by the caller. The \fInelem\fR
84 argument is set to be the length of the array returned.
85 .SH RETURN VALUES
86 .LP
87 Upon successful completion, \fBpool_create()\fR returns a new initialized pool.
88 Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the
89 pool-specific error value.
90 .sp
91 .LP
92 Upon successful completion, \fBpool_associate()\fR, \fBpool_destroy()\fR, and
93 \fBpool_dissociate()\fR return 0. Otherwise, they return -1 and
94 \fBpool_error()\fR returns the pool-specific error value.
95 .sp
96 .LP
97 Upon successful completion, \fBpool_info()\fR returns a string describing the
98 given pool. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the
99 pool-specific error value.
100 .sp
101 .LP
102 Upon successful completion, \fBpool_query_pool_resources()\fR returns a
103 null-terminated array of resources. Otherwise it returns \fINULL\fR and
104 \fBpool_error()\fR returns the pool-specific error value.
105 .SH ERRORS
106 .LP
107 The \fBpool_create()\fR function will fail if:
108 .sp
109 .ne 2
110 .na
111 \fB\fBPOE_BADPARAM\fR\fR
112 .ad
113 .RS 20n
114 The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is
115 already in use.
116 .RE
117
118 .sp
119 .ne 2
120 .na
121 \fB\fBPOE_SYSTEM\fR\fR
122 .ad
123 .RS 20n
124 A system error has occurred. Check the system error code for more details.
125 .RE
126
203
204 .sp
205 .ne 2
206 .na
207 \fB\fBPOE_SYSTEM\fR\fR
208 .ad
209 .RS 20n
210 A system error has occurred. Check the system error code for more details.
211 .RE
212
213 .sp
214 .LP
215 The \fBpool_info()\fR function will fail if:
216 .sp
217 .ne 2
218 .na
219 \fB\fBPOE_BADPARAM\fR\fR
220 .ad
221 .RS 20n
222 The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR
223 paramter is neither 0 or 1.
224 .RE
225
226 .sp
227 .ne 2
228 .na
229 \fB\fBPOE_INVALID_CONF\fR\fR
230 .ad
231 .RS 20n
232 The configuration is invalid.
233 .RE
234
235 .sp
236 .ne 2
237 .na
238 \fB\fBPOE_SYSTEM\fR\fR
239 .ad
240 .RS 20n
241 A system error has occurred. Check the system error code for more details.
242 .RE
243
255
256 .sp
257 .ne 2
258 .na
259 \fB\fBPOE_INVALID_CONF\fR\fR
260 .ad
261 .RS 20n
262 The configuration is invalid.
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB\fBPOE_SYSTEM\fR\fR
269 .ad
270 .RS 20n
271 A system error has occurred. Check the system error code for more details.
272 .RE
273
274 .SH USAGE
275 .LP
276 Pool names are unique across pools in a given configuration file. It is an
277 error to attempt to create a pool with a name that is currently used by another
278 pool within the same configuration.
279 .SH ATTRIBUTES
280 .LP
281 See \fBattributes\fR(5) for descriptions of the following attributes:
282 .sp
283
284 .sp
285 .TS
286 box;
287 c | c
288 l | l .
289 ATTRIBUTE TYPE ATTRIBUTE VALUE
290 _
291 CSI Enabled
292 _
293 Interface Stability Unstable
294 _
295 MT-Level Safe
296 .TE
297
298 .SH SEE ALSO
299 .LP
300 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)
|
1 '\" te
2 .\" Copyright (c) 2005, 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_ASSOCIATE 3POOL "January 15, 2020"
7 .SH NAME
8 pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info,
9 pool_query_pool_resources \- resource pool manipulation functions
10 .SH SYNOPSIS
11 .nf
12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
13 #include <pool.h>
14
15 \fBint\fR \fBpool_associate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fB pool_t *\fR\fIpool\fR,
16 \fBpool_resource_t *\fR\fIresource\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBpool_t *\fR\fBpool_create\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBint\fR \fBpool_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR);
27 .fi
28
29 .LP
30 .nf
31 \fBint\fR \fBpool_dissociate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
32 \fBpool_resource_t *\fR\fIresource\fR);
33 .fi
34
35 .LP
36 .nf
37 \fBconst char *\fR\fBpool_info\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR,
38 \fBint\fR \fIflags\fR);
39 .fi
40
41 .LP
42 .nf
43 \fBpool_resource_t **\fR\fBpool_query_pool_resources\fR(\fBpool_conf_t *\fR\fIconf\fR,
44 \fBpool_t *\fR\fIpool\fR, \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIproperties\fR);
45 .fi
46
47 .SH DESCRIPTION
48 These functions provide mechanisms for constructing and modifying pools entries
49 within a target pools configuration. The \fIconf\fR argument for each function
50 refers to the target configuration to which the operation applies.
51 .sp
52 .LP
53 The \fBpool_associate()\fR function associates the specified resource with
54 \fIpool\fR. A resource can be associated with multiple pools at the same time.
55 Any resource of this type that was formerly associated with this pool is no
56 longer associated with the pool. The new association replaces the earlier one.
57 .sp
58 .LP
59 The \fBpool_create()\fR function creates a new pool with the supplied name with
60 its default properties initialized, and associated with the default resource of
61 each type.
62 .sp
63 .LP
64 The \fBpool_destroy function()\fR destroys the given pool association.
65 Associated resources are not modified.
66 .sp
67 .LP
68 The \fBpool_dissociate()\fR function removes the association between the given
69 resource and pool. On successful completion, the pool is associated with the
70 default resource of the same type.
71 .sp
72 .LP
73 The \fBpool_info()\fR function returns a string describing the given pool. The
74 string is allocated with \fBmalloc\fR(3C). The caller is responsible for freeing
75 the returned string. If the \fIflags\fR option is non-zero, the string returned
76 also describes the associated resources of the pool.
77 .sp
78 .LP
79 The \fBpool_query_pool_resources()\fR function returns a null-terminated array
80 of resources currently associated with the pool that match the given list of
81 properties. The return value must be freed by the caller. The \fInelem\fR
82 argument is set to be the length of the array returned.
83 .SH RETURN VALUES
84 Upon successful completion, \fBpool_create()\fR returns a new initialized pool.
85 Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the
86 pool-specific error value.
87 .sp
88 .LP
89 Upon successful completion, \fBpool_associate()\fR, \fBpool_destroy()\fR, and
90 \fBpool_dissociate()\fR return 0. Otherwise, they return -1 and
91 \fBpool_error()\fR returns the pool-specific error value.
92 .sp
93 .LP
94 Upon successful completion, \fBpool_info()\fR returns a string describing the
95 given pool. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the
96 pool-specific error value.
97 .sp
98 .LP
99 Upon successful completion, \fBpool_query_pool_resources()\fR returns a
100 null-terminated array of resources. Otherwise it returns \fINULL\fR and
101 \fBpool_error()\fR returns the pool-specific error value.
102 .SH ERRORS
103 The \fBpool_create()\fR function will fail if:
104 .sp
105 .ne 2
106 .na
107 \fB\fBPOE_BADPARAM\fR\fR
108 .ad
109 .RS 20n
110 The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is
111 already in use.
112 .RE
113
114 .sp
115 .ne 2
116 .na
117 \fB\fBPOE_SYSTEM\fR\fR
118 .ad
119 .RS 20n
120 A system error has occurred. Check the system error code for more details.
121 .RE
122
199
200 .sp
201 .ne 2
202 .na
203 \fB\fBPOE_SYSTEM\fR\fR
204 .ad
205 .RS 20n
206 A system error has occurred. Check the system error code for more details.
207 .RE
208
209 .sp
210 .LP
211 The \fBpool_info()\fR function will fail if:
212 .sp
213 .ne 2
214 .na
215 \fB\fBPOE_BADPARAM\fR\fR
216 .ad
217 .RS 20n
218 The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR
219 parameter is neither 0 or 1.
220 .RE
221
222 .sp
223 .ne 2
224 .na
225 \fB\fBPOE_INVALID_CONF\fR\fR
226 .ad
227 .RS 20n
228 The configuration is invalid.
229 .RE
230
231 .sp
232 .ne 2
233 .na
234 \fB\fBPOE_SYSTEM\fR\fR
235 .ad
236 .RS 20n
237 A system error has occurred. Check the system error code for more details.
238 .RE
239
251
252 .sp
253 .ne 2
254 .na
255 \fB\fBPOE_INVALID_CONF\fR\fR
256 .ad
257 .RS 20n
258 The configuration is invalid.
259 .RE
260
261 .sp
262 .ne 2
263 .na
264 \fB\fBPOE_SYSTEM\fR\fR
265 .ad
266 .RS 20n
267 A system error has occurred. Check the system error code for more details.
268 .RE
269
270 .SH USAGE
271 Pool names are unique across pools in a given configuration file. It is an
272 error to attempt to create a pool with a name that is currently used by another
273 pool within the same configuration.
274 .SH ATTRIBUTES
275 See \fBattributes\fR(5) for descriptions of the following attributes:
276 .sp
277
278 .sp
279 .TS
280 box;
281 c | c
282 l | l .
283 ATTRIBUTE TYPE ATTRIBUTE VALUE
284 _
285 CSI Enabled
286 _
287 Interface Stability Unstable
288 _
289 MT-Level Safe
290 .TE
291
292 .SH SEE ALSO
293 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)
|