diff options
Diffstat (limited to 'usr/src/man/man3pool/pool_get_binding.3pool')
| -rw-r--r-- | usr/src/man/man3pool/pool_get_binding.3pool | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/usr/src/man/man3pool/pool_get_binding.3pool b/usr/src/man/man3pool/pool_get_binding.3pool new file mode 100644 index 0000000..b1cae5d --- /dev/null +++ b/usr/src/man/man3pool/pool_get_binding.3pool @@ -0,0 +1,249 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH POOL_GET_BINDING 3POOL "Mar 27, 2007" +.SH NAME +pool_get_binding, pool_set_binding, pool_get_resource_binding \- set and query +process to resource pool bindings +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBchar *\fR\fBpool_get_binding\fR(\fBpid_t\fR \fIpid\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_set_binding\fR(\fBconst char *\fR\fIpool\fR, \fBidtype_t\fR \fIidtype\fR, + \fBid_t\fR \fIid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpool_get_resource_binding\fR(\fBconst char *\fR\fItype\fR, \fBpid_t\fR \fIpid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpool_get_binding()\fR function returns the name of the pool on the +running system that contains the set of resources to which the given process is +bound. If no such pool exists on the system or the search returns more than one +pool (since the set of resources is referred to by more than one pool), +\fINULL\fR is returned and the pool error value is set to +\fBPOE_INVALID_SEARCH\fR. +.sp +.LP +It is possible that one of the resources to which the given process is bound is +not associated with a pool. This could occur if a processor set was created +with one of the \fBpset_()\fR functions and the process was then bound to that +set. It could also occur if the process was bound to a resource set not +currently associated with a pool, since resources can exist that are not +associated with a pool. +.sp +.LP +The \fBpool_set_binding()\fR function binds the processes matching \fIidtype\fR +and \fIid\fR to the resources associated with \fIpool\fR on the running system. +This function requires the privilege required by the underlying resource types +referenced by the pool; generally, this requirement is equivalent to requiring +superuser privilege. +.sp +.LP +The \fIidtype\fR parameter can be of the following types: +.sp +.ne 2 +.na +\fB\fBP_PID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a pid. +.RE + +.sp +.ne 2 +.na +\fB\fBP_TASKID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a taskid. +.RE + +.sp +.ne 2 +.na +\fB\fBP_PROJID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a project ID. All currently running processes +belonging to the given project will be bound to the pool's resources. +.RE + +.sp +.LP +The \fBpool_get_resource_binding()\fR function returns the name of the resource +of the supplied type to which the supplied process is bound. +.sp +.LP +The application must explicity free the memory allocated for the return values +for \fBpool_get_binding()\fR and \fBpool_get_resource_binding()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_get_binding()\fR returns the name of the +pool to which the process is bound. Otherwise it returns \fINULL\fR and +\fBpool_error\fR(3POOL) returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_set_binding()\fR returns \fBPO_SUCCESS\fR. +Otherwise, it returns \fBPO_FAIL\fR and \fBpool_error()\fR returns the +pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_get_resource_binding()\fR returns the name +of the resource of the specified type to which the process is bound. Otherwise +it returns \fINULL\fR and \fBpool_error()\fR returns the pool-specific error +value. +.SH ERRORS +.sp +.LP +The \fBpool_get_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +It is not possible to determine the binding for this target due to the +overlapping nature of the pools configured for this system, or the pool could +not be located. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_set_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +The pool could not be found. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_get_resource_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +The target is not bound to a resource of the specified type. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRBind the current process to the pool named "target". +.sp +.in +2 +.nf +#include <sys/types.h> +#include <pool.h> +#include <unistd.h> + +\&... + +id_t pid = getpid(); + +\&... + +if (pool_set_binding("target", P_PID, pid) == PO_FAIL) \{ + (void) fprintf(stderr, "pool binding failed (\\%d)\\B{}n", + pool_error()); +\} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) |