Tribblix: manual page: setproject.3project

SETPROJECT(3PROJECT) Project Database Access Library Functions

NAME

setproject - associate a user process with a project

SYNOPSIS

cc [ flag ... ] file... -lproject [ library ... ]
#include <project.h>

int setproject(const char *project_name, const char *user_name,
uint_t flags);

DESCRIPTION

The setproject() function provides a simplified method for the
association of a user process with a project and its various resource
management attributes, as stored in the project(5) name service
database. These attributes include resource control settings,
resource pool membership, and third party attributes (which are
ignored by setproject().)

If user_name is a valid member of the project specified by
project_name, as determined by inproj(3PROJECT), setproject() will
create a new task with settaskid(2) using task flags specified by
flags, use setrctl(2) to associate various resource controls with the
process, task, and project, and bind the calling process to the
appropriate resource pool with pool_set_binding(3POOL). Resource
controls not explicitly specified in the project entry will be
preserved. If user_name is a name of the superuser (user with UID
equal to 0), the setproject() function skips the inproj(3PROJECT)
check described above and allows the superuser to join any project.

The current process will not be bound to a resource pool if the
resource pools facility (see pooladm(8)) is inactive. The
setproject() function will succeed whether or not the project
specified by project_name specifies a project.pool attribute. If the
resource pools facility is active, setproject() will fail if the
project does not specify a project.pool attribute and there is no
designated pool accepting default assignments. The setproject()
function will also fail if there is a specified project.pool
attribute for a nonexistent pool.

RETURN VALUES

Upon successful completion, setproject() returns 0. If any of the
resource control assignments failed but the project assignment, pool
binding, and task creation succeeded, an integer value corresponding
to the offset into the key-value pair list of the failed attribute
assignment is returned. If the project assignment or task creation
was not successful, setproject() returns SETPROJ_ERR_TASK and sets
errno to indicate the error. In the event of a pool binding failure,
setproject() returns SETPROJ_ERR_POOL and sets errno to indicate the
error. Additional error information can be retrieved from
pool_error(3POOL).

ERRORS

The setproject() function will fail during project assignment or task
creation if:

EACCES
The invoking task was created with the TASK_FINAL flag.

EAGAIN
A resource control limiting the number of LWPs or tasks in
the target project or zone has been exceeded.

A resource control on the given project would be exceeded.

EINVAL
The project ID associated with the given project is not
within the range of valid project IDs, invalid flags were
specified, or user_name is NULL.

EPERM
The effective user of the calling process is not superuser.

ESRCH
The specified user is not a valid user of the given
project, user_name is not valid user name, or project_name
is not valid project name.

The setproject() function will fail during pool binding if:

EACCES
No resource pool accepting default bindings exists.

EPERM
The effective user of the calling process is not superuser.

ESRCH
The specified resource pool is unknown

If setproject() returns an offset into the key-value pair list, the
returned error value is associated with setrctl(2) for resource
control attributes.

USAGE

The setproject() function recognizes a name-structured value pair for
the attributes in the project(5) database with the following format:

entity.control=(privilege,value,action,action,...),...

where privilege is one of BASIC or PRIVILEGED, value is a numeric
value with optional units, and action is one of none, deny, and
signal=signum or signal=SIGNAME. For instance, to set a series of
progressively more assertive control values on a project's per-
process CPU time, specify

process.max-cpu-time=(PRIVILEGED,1000s,signal=SIGXRES), \
(PRIVILEGED,1250, signal=SIGTERM),(PRIVILEGED,1500,
signal=SIGKILL)

To prevent a task from exceeding a total of 128 LWPs, specify a
resource control with

task.max-lwps=(PRIVILEGED,128,deny)

Specifying a resource control name with no values causes all resource
control values for that name to be cleared on the given project,
leaving only the system resource control value on the specified
resource control name.

For example, to remove all resource control values on shared memory,
specify:

project.max-shm-memory

The project attribute, project.pool, specifies the pool to which
processes associated with the project entry should be bound. Its
format is:

project.pool=pool_name

where pool_name is a valid resource pool within the active
configuration enabled with pooladm(8).

The final attribute is used to finalize the task created by
setproject(). See settaskid(2).

task.final

All further attempts to create new tasks, such as using newtask(1)
and su(8), will fail.

ATTRIBUTES