svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
setproject(3project)
Project Database Access Library Functions setproject(3PROJECT)
NAME
setproject - associate a user process with a project
SYNOPSIS
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);
DESCRIPTION
The setproject() function provides a simplified method for the associa‐
tion 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 effec‐
tive and limit set of the target pid respectively. For
project_update_byname(), this requirement applies to every process run‐
ning 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, setpro‐
ject_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 pro‐
cesses 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.
FLAGS
The following flags are supported:
TASK_NORMAL and TASK_FINAL:
These flags behave as documented by settaskid(2). Only setproject()
supports these flags. All tasks created by the remaining functions
are always TASK_NORMAL.
PROJ_FORCE_NEWTASK:
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 func‐
tion only operates on processes already in the target project, and
there is no need to create any new tasks.
PROJ_BIND_DEFAULT_POOL
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 pro‐
cesses would be bound to the default pool if this flag is speci‐
fied. If this flag is not specified, these processes would retain
their existing binding.
PROJECT ATTRIBUTES
Resource controls process, task, and project resource controls can be
specified as project attributes.
For all setproject() functions:
o For process resource controls, any unspecified resource con‐
trols remain unchanged for the process.
o For task resource controls, any unspecified resource con‐
trols are inherited from the current task of the target
process if a new task is created.
o For project resource controls, Any unspecified resource con‐
trols are set to the default values for that project
resource control.
For all project_update() functions, only the project.* resource con‐
trols 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.
rcap.max-rss
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
project.pool
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.
true (default value)
A warning will returned via msg and the target process or pro‐
cesses will be bound to the default pool for the global zone.
false
setproject will fail.
project.mcb.cpus, project.mcb.cores, project.mcb.sockets,
project.mcb.pgs, project.mcb.lgroups, project.mcb.flags
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 spe‐
cific 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.
task.final
The final attribute is used to finalize the task created by setpro‐
ject(). 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
RETURN VALUES
Upon successful completion, setproject() returns 0.
ERRORS
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.
SETPROJ_ERR_TASK
Task creation failed, or problem with setting project attributes
for specific error:
ENOMEM Not enough Memory.
EINVAL Invalid flag, username, pid, or project ID.
ESRCH project with name does not exist.
EPERM user name and pid does not exist.
EAGAIN Pools facility not installed. Unable to read system
information. Try again.
EINTR Signal received, interrupted.
Also see errnos defined for settaskid(2).
SETPROJECT_ERR_POOL
ENOMEM Not enough Memory.
ESRCH pid does not exist.
Error set by libpool(3LIB). See errors described by pool_set_bind‐
ing(3POOL).
SETPROJECT_ERR_MCB
ENOMEM Not enough Memory.
ESRCH pid does not exist.
EINVAL 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.
EPERM 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.
SETPROJ_ERR_RCTL
ENOMEM Not enough Memory.
ESRCH pid does not exist.
See errors defined by setrctl(2).
POSITIVE INTEGER
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 descrip‐
tive using this parameter rather than returning positive integers.
If the failed attribute is an rctl, see the errors defined by
setrctl(2).
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, leav‐
ing 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.
EXAMPLES
Example 1 Set a running process to run in a specified project
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);
}
}
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilitySee below _ MT-LevelMT-Safe
The following gives the interface stability for the setproject() func‐
tions:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) FUNCTIONINTERFACE
STABILITY _ setproject()Committed _ setproject_byname()Volatile _ set‐
project_byname_pid()Volatile _ project_update_byname()Volatile
SEE ALSO
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)
NOTES
The project.mcb.sockets property will be removed in a future release of
Oracle Solaris.
Oracle Solaris 11.4 3 Nov 2021 setproject(3PROJECT)