Tribblix: manual page: pool_get

POOL_GET_BINDING(3POOL) Pool Configuration Manipulation Library Functions

NAME

pool_get_binding, pool_set_binding, pool_get_resource_binding - set
and query process to resource pool bindings

SYNOPSIS

cc [ flag... ] file... -lpool [ library... ]
#include <pool.h>

char *pool_get_binding(pid_t pid);

int pool_set_binding(const char *pool, idtype_t idtype,
id_t id);

char *pool_get_resource_binding(const char *type, pid_t pid);

DESCRIPTION

The pool_get_binding() 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), NULL is returned and the pool error value is
set to POE_INVALID_SEARCH.

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 pset_() 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.

The pool_set_binding() function binds the processes matching idtype
and id to the resources associated with pool 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.

The idtype parameter can be one of the following types:

P_PID
The id parameter is a pid.

P_TASKID
The id parameter is a taskid.

P_PROJID
The id parameter is a project ID. All currently running
processes belonging to the given project will be bound to
the pool's resources.

The pool_get_resource_binding() function returns the name of the
resource of the supplied type to which the supplied process is bound.

The application must explicitly free the memory allocated for the
return values for pool_get_binding() and pool_get_resource_binding().

RETURN VALUES

Upon successful completion, pool_get_binding() returns the name of
the pool to which the process is bound. Otherwise it returns NULL and
pool_error(3POOL) returns the pool-specific error value.

Upon successful completion, pool_set_binding() returns PO_SUCCESS.
Otherwise, it returns PO_FAIL and pool_error() returns the pool-
specific error value.

Upon successful completion, pool_get_resource_binding() returns the
name of the resource of the specified type to which the process is
bound. Otherwise it returns NULL and pool_error() returns the pool-
specific error value.

ERRORS

The pool_get_binding() function will fail if:

POE_INVALID_CONF
The configuration is invalid.

POE_INVALID_SEARCH
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.

POE_SYSTEM
A system error has occurred. Check the system
error code for more details.

The pool_set_binding() function will fail if:

POE_INVALID_SEARCH
The pool could not be found.

POE_INVALID_CONF
The configuration is invalid.

POE_SYSTEM
A system error has occurred. Check the system
error code for more details.

The pool_get_resource_binding() function will fail if:

POE_INVALID_CONF
The configuration is invalid.

POE_INVALID_SEARCH
The target is not bound to a resource of the
specified type.

POE_SYSTEM
A system error has occurred. Check the system
error code for more details.

EXAMPLES

Example 1: Bind the current process to the pool named "target".

#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)\n",
pool_error());

ATTRIBUTES