1 '\" te
2 .\" Copyright (c) 2007, 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_GET_BINDING 3POOL "Mar 27, 2007"
7 .SH NAME
8 pool_get_binding, pool_set_binding, pool_get_resource_binding \- set and query
9 process to resource pool bindings
10 .SH SYNOPSIS
11 .LP
12 .nf
13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
14 #include <pool.h>
15
16 \fBchar *\fR\fBpool_get_binding\fR(\fBpid_t\fR \fIpid\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBpool_set_binding\fR(\fBconst char *\fR\fIpool\fR, \fBidtype_t\fR \fIidtype\fR,
22 \fBid_t\fR \fIid\fR);
23 .fi
24
25 .LP
26 .nf
27 \fBchar *\fR\fBpool_get_resource_binding\fR(\fBconst char *\fR\fItype\fR, \fBpid_t\fR \fIpid\fR);
28 .fi
29
30 .SH DESCRIPTION
31 .sp
32 .LP
33 The \fBpool_get_binding()\fR function returns the name of the pool on the
34 running system that contains the set of resources to which the given process is
35 bound. If no such pool exists on the system or the search returns more than one
36 pool (since the set of resources is referred to by more than one pool),
37 \fINULL\fR is returned and the pool error value is set to
38 \fBPOE_INVALID_SEARCH\fR.
39 .sp
40 .LP
41 It is possible that one of the resources to which the given process is bound is
42 not associated with a pool. This could occur if a processor set was created
43 with one of the \fBpset_()\fR functions and the process was then bound to that
44 set. It could also occur if the process was bound to a resource set not
45 currently associated with a pool, since resources can exist that are not
46 associated with a pool.
47 .sp
48 .LP
49 The \fBpool_set_binding()\fR function binds the processes matching \fIidtype\fR
50 and \fIid\fR to the resources associated with \fIpool\fR on the running system.
51 This function requires the privilege required by the underlying resource types
52 referenced by the pool; generally, this requirement is equivalent to requiring
53 superuser privilege.
54 .sp
55 .LP
56 The \fIidtype\fR parameter can be of the following types:
57 .sp
58 .ne 2
59 .na
60 \fB\fBP_PID\fR\fR
61 .ad
62 .RS 12n
63 The \fIid\fR parameter is a pid.
64 .RE
65
66 .sp
67 .ne 2
68 .na
69 \fB\fBP_TASKID\fR\fR
70 .ad
71 .RS 12n
72 The \fIid\fR parameter is a taskid.
73 .RE
74
75 .sp
76 .ne 2
77 .na
78 \fB\fBP_PROJID\fR\fR
79 .ad
80 .RS 12n
81 The \fIid\fR parameter is a project ID. All currently running processes
82 belonging to the given project will be bound to the pool's resources.
83 .RE
84
85 .sp
86 .LP
87 The \fBpool_get_resource_binding()\fR function returns the name of the resource
88 of the supplied type to which the supplied process is bound.
89 .sp
90 .LP
91 The application must explicity free the memory allocated for the return values
92 for \fBpool_get_binding()\fR and \fBpool_get_resource_binding()\fR.
93 .SH RETURN VALUES
94 .sp
95 .LP
96 Upon successful completion, \fBpool_get_binding()\fR returns the name of the
97 pool to which the process is bound. Otherwise it returns \fINULL\fR and
98 \fBpool_error\fR(3POOL) returns the pool-specific error value.
99 .sp
100 .LP
101 Upon successful completion, \fBpool_set_binding()\fR returns \fBPO_SUCCESS\fR.
102 Otherwise, it returns \fBPO_FAIL\fR and \fBpool_error()\fR returns the
103 pool-specific error value.
104 .sp
105 .LP
106 Upon successful completion, \fBpool_get_resource_binding()\fR returns the name
107 of the resource of the specified type to which the process is bound. Otherwise
108 it returns \fINULL\fR and \fBpool_error()\fR returns the pool-specific error
109 value.
110 .SH ERRORS
111 .sp
112 .LP
113 The \fBpool_get_binding()\fR function will fail if:
114 .sp
115 .ne 2
116 .na
117 \fB\fBPOE_INVALID_CONF\fR\fR
118 .ad
119 .RS 22n
120 The configuration is invalid.
121 .RE
122
123 .sp
124 .ne 2
125 .na
126 \fB\fBPOE_INVALID_SEARCH\fR\fR
127 .ad
128 .RS 22n
129 It is not possible to determine the binding for this target due to the
130 overlapping nature of the pools configured for this system, or the pool could
131 not be located.
132 .RE
184
185 .sp
186 .ne 2
187 .na
188 \fB\fBPOE_INVALID_SEARCH\fR\fR
189 .ad
190 .RS 22n
191 The target is not bound to a resource of the specified type.
192 .RE
193
194 .sp
195 .ne 2
196 .na
197 \fB\fBPOE_SYSTEM\fR\fR
198 .ad
199 .RS 22n
200 A system error has occurred. Check the system error code for more details.
201 .RE
202
203 .SH EXAMPLES
204 .LP
205 \fBExample 1 \fRBind the current process to the pool named "target".
206 .sp
207 .in +2
208 .nf
209 #include <sys/types.h>
210 #include <pool.h>
211 #include <unistd.h>
212
213 \&...
214
215 id_t pid = getpid();
216
217 \&...
218
219 if (pool_set_binding("target", P_PID, pid) == PO_FAIL) \{
220 (void) fprintf(stderr, "pool binding failed (\\%d)\\B{}n",
221 pool_error());
222 \}
223 .fi
224 .in -2
225
226 .SH ATTRIBUTES
227 .sp
228 .LP
229 See \fBattributes\fR(5) for descriptions of the following attributes:
230 .sp
231
232 .sp
233 .TS
234 box;
235 c | c
236 l | l .
237 ATTRIBUTE TYPE ATTRIBUTE VALUE
238 _
239 CSI Enabled
240 _
241 Interface Stability Unstable
242 _
243 MT-Level Safe
244 .TE
245
246 .SH SEE ALSO
247 .sp
248 .LP
249 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)
|
1 '\" te
2 .\" Copyright (c) 2007, 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_GET_BINDING 3POOL "January 18, 2020"
7 .SH NAME
8 pool_get_binding, pool_set_binding, pool_get_resource_binding \- set and query
9 process to resource pool bindings
10 .SH SYNOPSIS
11 .nf
12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
13 #include <pool.h>
14
15 \fBchar *\fR\fBpool_get_binding\fR(\fBpid_t\fR \fIpid\fR);
16 .fi
17
18 .LP
19 .nf
20 \fBint\fR \fBpool_set_binding\fR(\fBconst char *\fR\fIpool\fR, \fBidtype_t\fR \fIidtype\fR,
21 \fBid_t\fR \fIid\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBchar *\fR\fBpool_get_resource_binding\fR(\fBconst char *\fR\fItype\fR, \fBpid_t\fR \fIpid\fR);
27 .fi
28
29 .SH DESCRIPTION
30 The \fBpool_get_binding()\fR function returns the name of the pool on the
31 running system that contains the set of resources to which the given process is
32 bound. If no such pool exists on the system or the search returns more than one
33 pool (since the set of resources is referred to by more than one pool),
34 \fINULL\fR is returned and the pool error value is set to
35 \fBPOE_INVALID_SEARCH\fR.
36 .sp
37 .LP
38 It is possible that one of the resources to which the given process is bound is
39 not associated with a pool. This could occur if a processor set was created
40 with one of the \fBpset_()\fR functions and the process was then bound to that
41 set. It could also occur if the process was bound to a resource set not
42 currently associated with a pool, since resources can exist that are not
43 associated with a pool.
44 .sp
45 .LP
46 The \fBpool_set_binding()\fR function binds the processes matching \fIidtype\fR
47 and \fIid\fR to the resources associated with \fIpool\fR on the running system.
48 This function requires the privilege required by the underlying resource types
49 referenced by the pool; generally, this requirement is equivalent to requiring
50 superuser privilege.
51 .sp
52 .LP
53 The \fIidtype\fR parameter can be one of the following types:
54 .sp
55 .ne 2
56 .na
57 \fB\fBP_PID\fR\fR
58 .ad
59 .RS 12n
60 The \fIid\fR parameter is a pid.
61 .RE
62
63 .sp
64 .ne 2
65 .na
66 \fB\fBP_TASKID\fR\fR
67 .ad
68 .RS 12n
69 The \fIid\fR parameter is a taskid.
70 .RE
71
72 .sp
73 .ne 2
74 .na
75 \fB\fBP_PROJID\fR\fR
76 .ad
77 .RS 12n
78 The \fIid\fR parameter is a project ID. All currently running processes
79 belonging to the given project will be bound to the pool's resources.
80 .RE
81
82 .sp
83 .LP
84 The \fBpool_get_resource_binding()\fR function returns the name of the resource
85 of the supplied type to which the supplied process is bound.
86 .sp
87 .LP
88 The application must explicitly free the memory allocated for the return values
89 for \fBpool_get_binding()\fR and \fBpool_get_resource_binding()\fR.
90 .SH RETURN VALUES
91 Upon successful completion, \fBpool_get_binding()\fR returns the name of the
92 pool to which the process is bound. Otherwise it returns \fINULL\fR and
93 \fBpool_error\fR(3POOL) returns the pool-specific error value.
94 .sp
95 .LP
96 Upon successful completion, \fBpool_set_binding()\fR returns \fBPO_SUCCESS\fR.
97 Otherwise, it returns \fBPO_FAIL\fR and \fBpool_error()\fR returns the
98 pool-specific error value.
99 .sp
100 .LP
101 Upon successful completion, \fBpool_get_resource_binding()\fR returns the name
102 of the resource of the specified type to which the process is bound. Otherwise
103 it returns \fINULL\fR and \fBpool_error()\fR returns the pool-specific error
104 value.
105 .SH ERRORS
106 The \fBpool_get_binding()\fR function will fail if:
107 .sp
108 .ne 2
109 .na
110 \fB\fBPOE_INVALID_CONF\fR\fR
111 .ad
112 .RS 22n
113 The configuration is invalid.
114 .RE
115
116 .sp
117 .ne 2
118 .na
119 \fB\fBPOE_INVALID_SEARCH\fR\fR
120 .ad
121 .RS 22n
122 It is not possible to determine the binding for this target due to the
123 overlapping nature of the pools configured for this system, or the pool could
124 not be located.
125 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fBPOE_INVALID_SEARCH\fR\fR
182 .ad
183 .RS 22n
184 The target is not bound to a resource of the specified type.
185 .RE
186
187 .sp
188 .ne 2
189 .na
190 \fB\fBPOE_SYSTEM\fR\fR
191 .ad
192 .RS 22n
193 A system error has occurred. Check the system error code for more details.
194 .RE
195
196 .SH EXAMPLES
197 \fBExample 1 \fRBind the current process to the pool named "target".
198 .sp
199 .in +2
200 .nf
201 #include <sys/types.h>
202 #include <pool.h>
203 #include <unistd.h>
204
205 \&...
206
207 id_t pid = getpid();
208
209 \&...
210
211 if (pool_set_binding("target", P_PID, pid) == PO_FAIL) \{
212 (void) fprintf(stderr, "pool binding failed (%d)\\n",
213 pool_error());
214 \}
215 .fi
216 .in -2
217
218 .SH ATTRIBUTES
219 See \fBattributes\fR(5) for descriptions of the following attributes:
220 .sp
221
222 .sp
223 .TS
224 box;
225 c | c
226 l | l .
227 ATTRIBUTE TYPE ATTRIBUTE VALUE
228 _
229 CSI Enabled
230 _
231 Interface Stability Unstable
232 _
233 MT-Level Safe
234 .TE
235
236 .SH SEE ALSO
237 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)
|