setproject - associate a user process with a project
cc [ flag ... ] file... -lproject [ library ... ] #include <project.h>
int setproject(const char *project_byname, const char *user,
uint_t flags);
int setproject_byname(const char *proj_byname, uint_t flags,
char **msgs);
int setproject_byname_pid(const char *proj_byname, pid_t pid,
uint_t flags, char **msgs);
int project_update_byname(const char *project_byname, uint_t flags);
void project_msgs_free(char *msgs);
The setproject() function provides a simplified method for the association of a user process with a project and its various attributes, as stored in the project(5) name service database. These attributes include resource controls, physical memory cap, resource pool binding, and multi-cpu binding (MCB). Unknown and third party attributes are ignored by all setproject() functions.
All setproject() functions require PRIV_PROC_TASKID. Whenever a process joins a project, a new task is created. For more information, see the settaskid(2) man page.
If the project's attributes include project.pool, PRIV_SYS_RES_CONFIG or PRIV_SYS_BIND is also required.
If the target process is not owned by the same user as the calling process, PRIV_PROC_OWNER is also required.
The privilege effective and limit set must be a superset of the effective and limit set of the target pid respectively. For project_update_byname(), this requirement applies to every process running in the target project.
For detailed descriptions of each privilege, see the privileges(7) man page.
All setproject() functions will cause a process to join the target project, and the project's attributes to be applied to the target process. setproject_byname_pid() operates on a target pid. setproject() and setproject_byname() operate on the caller. Note that, setproject_byname_pid() function fails when the caller is a 32-bit process and the target is a 64-bit process.
project_update_byname() operates an all processes currently running in a project. These functions provide a means of updating running processes after modifying a project's attributes.
The setproject() function verifies that user is a valid member of the specified project, as determined by inproj(3PROJECT). If user is a user with UID equal to 0, the setproject() function skips the inproj() check described above and allows the user to join any project.
For backward compatibility, the setproject() function always implies the use of flags: PROJ_FORCE_NEWTASK and PROJ_BIND_DEFAULT
setproject_byname() and setproject_byname_pid() do not have a user parameter. It is the responsibility of the caller to verify that the user of the target process is a member of the target project.
If the msg parameter is not NULL, it will be set to a localized string containing any warning or error messages related to the operation. If the string contains more than one message, they will be delimited by the '\n' character. The last message will not have a '\n' before the terminating '\0'.
The msg parameter may be set on success or failure, and should be freed with project_msgs_free(). If no messages are returned and the msg parameter is non-NULL, it will be set to a NULL pointer. project_msgs_free() also accepts a NULL pointer.
The following flags are supported:
These flags behave as documented by settaskid(2). Only setproject() supports these flags. All tasks created by the remaining functions are always TASK_NORMAL.
Create a new task, even if the target process is already a member of the target project.
This flag is implied when using setproject() for compatibility. The other setproject() functions only create new task when the target process is not already a member of the target project, unless this flag is specified.
This flag is not valid for project_update_byname(), as this function only operates on processes already in the target project, and there is no need to create any new tasks.
If the target project does not have a project.pool attribute, treat as if the target project has the attribute project.pool=pool_default set.
For example, if some of the processes in a project were manually bound to a pool or pset using poolbind(8) or psrset(8), these processes would be bound to the default pool if this flag is specified. If this flag is not specified, these processes would retain their existing binding.
Resource controls process, task, and project resource controls can be specified as project attributes.
For all setproject() functions:
For process resource controls, any unspecified resource controls remain unchanged for the process.
For task resource controls, any unspecified resource controls are inherited from the current task of the target process if a new task is created.
For project resource controls, Any unspecified resource controls are set to the default values for that project resource control.
For all project_update() functions, only the project.* resource controls specified for each project are updated. The project.* and task.* resource controls of running processes and tasks are not updated.
See the USAGE section below for a description of how to specify resource control attributes.
This attribute is used by the rcap service to set a physical memory cap for the project. See rcapd(8).
The format is the number of megabytes or gigabytes.
project.max-rss=500M project.max-rss=1G
This attribute specified a resource pool binding for the project. If no pool binding is specified, the target process or processes remain bound to the pool that they were bound to prior.
The pool should be in the running pools configuration, and listed by the output of the pooladm command.
The format is:
project.pool=mypoolname
If the PROJ_BOUND_DEFAULT_POOL flag is specified, the project is treated as if project.pool is explicit set to pool_default if it does not have a project.pool attribute.
If the resource pools package is not installed, the project.pool attribute is ignored and a warning is written to stderr.
If a project.pool attribute is specified for a project defined inside a non-global zone, it is ignored and a warning is written to stderr.
If in the global zone, and project.pool is set to pool which does not exist the behavior is governed by the vale of pool property system.project-fallback-to-default.
A warning will returned via msg and the target process or processes will be bound to the default pool for the global zone.
setproject will fail.
These properties configure the project to bind to a set of CPUs, cores, sockets, processor groups, or lgroups. Only one of these attributes can be specified for a given project. This attribute uses a multi-CPU binding (MCB) to bind target processes to the specific CPUs.
These attributes take ID list strings as described by the resource-management(7) man page.
The string "none" is also valid, meaning to clear all MCB bindings. For example:
project.mcb.cpus=0-7,16-23 project.mcb.cores=0-7 project.mcb.sockets=0,3 project.mcb.cpus=none
The individual IDs can be CPU, core, or socket IDs as outputted by the psrinfo(8) with the –t option. pg IDs can be those outputted by the pginfo and lgrpinfo commands. Processor Group 0 is invalid.
The project.mcb.flags property can be set to either strong or weak. If not set, strong is implied.
The project.mcb property depends on the project.pool property. At least one of the MCB target cpus must be in the project's pool or all setproject() functions will fail.
Cpus which do not exist, are not in the project's pool, or are not in the on-line or no-intr state will generate warning messages.
If the project.pool property is not set, then it is assumed to be the default pool for the target zone. Any target process bound to other pool psets or psrset or psets will be bound to the default pool of the zone so that the project's MCB binding can be applied successfully.
The final attribute is used to finalize the task created by setproject(). For more information, see the settaskid(2) man page. All further attempts to create new tasks, such as using setproject(), newtask(), and su, will fail.
It has no value and is specified by name only. The format is:
task.final
Upon successful completion, setproject() returns 0.
setproject_byname() and setproject_byname_pid() return the task id of the calling or target process on success.
project_update_byname() returns 0 on success.
The following return values define different errors. Receiving a latter return value implies that operations related to the prior return value succeeded. For example, receiving SETPROJECT_ERR_MCB implies that any task creation and pool binding to be done by the called function has succeeded.
Task creation failed, or problem with setting project attributes for specific error:
Not enough Memory.
Invalid flag, username, pid, or project ID.
project with name does not exist.
user name and pid does not exist.
Pools facility not installed. Unable to read system information. Try again.
Signal received, interrupted.
Also see errnos defined for settaskid(2).
Not enough Memory.
pid does not exist.
Error set by libpool(3LIB). See errors described by pool_set_binding(3POOL).
Not enough Memory.
pid does not exist.
No CPUs in the target list exist, are in the project's pool, and are in the online or no-intr state. If the project does not define a pool, then the default pool of the zone is assumed.
The {PRIV_PROC_OWNER} privilege is not asserted in the effective set of the calling process and its real or effective user ID does not match the real or effective user ID of one of the target process.
Not enough Memory.
pid does not exist.
See errors defined by setrctl(2).
The setproject() function can return a positive integer. In this case, the integer represents the project attribute that caused the failure. The first attribute would return 1, the second attribute 2, etc. All functions that take a msgs parameter return a descriptive using this parameter rather than returning positive integers.
If the failed attribute is an rctl, see the errors defined by setrctl(2).
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
All further attempts to create new tasks, such as using newtask(1) and su(8), will fail.
This example explains the process to set a running process to run in a specified project as defined in project(5). This causes the process with pid 1001 to join project "myproject".
#include <project.h>
int main()
{
(void) setproject_byname_pid("myproject", 1001, 0, NULL);
}
Example 2 Update all processes running in project "myproject"
This example explains the process to update all processes running in project "myproject" to have the attributes currently set in project(5). Print any error or warning messages.
#include <project.h>
int main()
{
(void) project_update_byname("myproject", &msgs);
if (msgs) {
printf("%s\n", msgs);
project_msgs_free(msgs);
}
}
See attributes(7) for descriptions of the following attributes:
|
The following gives the interface stability for the setproject() functions:
|
setrctl(2), settaskid(2), libproject(3LIB), pool_error(3POOL), pool_set_binding(3POOL), inproj(3PROJECT), passwd(5), project(5), attributes(7), privileges(7), resource-management(7), pooladm(8), psrinfo(8)
The project.mcb.sockets property will be removed in a future release of Oracle Solaris.