priv_add(3) Library Functions Manual priv_add(3)
NAME
priv_add: priv_add_effective(), priv_get(), priv_remove(), priv_set_effective(), privset_add_effective(), privset_get(), privset_remove(),
privset_set_effective() - add, set, remove, and retrieve a process' privileges
SYNOPSIS
Parameters
delim Null-terminated string specifying the delimeter string that separates privilege names.
pid Process ID of the target process whose privileges are to be retrieved.
priv_list Sequence of privilege names in ASCII, separated by one more characters from delim parameter.
priv_set Set of privileges in internal format.
priv_type Privilege set to be operated upon.
The following are the valid values for priv_type argument:
Modifies or retrieves privileges from the effective privilege set of the
process.
Modifies or retrieves privileges from the permitted privilege set of the
process. Note that the privileges removed from the permitted set are also removed from the effective and retained
privilege sets.
Modifies or retrieves privileges from the retained privilege set of the
process.
In addition to the above values, the and routines honor the following values for priv_type argument:
Retrieves the effective privileges of the process just before the last
successful exec family call.
Retrieves the permitted privileges of the process just before the last
successful exec family call.
Retrieves the retained privileges of the process just before the last
successful exec family call.
DESCRIPTION
The and functions facilitate the manipulation of the privileges of a process. See privileges(5). The functions beginning with accept an
internal format of the privileges, while functions beginning with accept a string representation of the privileges.
Adds the given privilege(s) to the calling process' effective privilege set.
To add a privilege to the effective privilege set, the privilege should be present in the permitted privilege set of the
calling process.
Removes the given privilege(s) from the calling process' privilege set.
The priv_type argument specifies the privilege set to be modified. Privileges removed from permitted privilege set are also
removed from effective and retained privilege sets of the calling process.
Sets the effective privilege set of the calling process to the
given privilege(s).
Similar to
except that it uses a privilege set type to specify the privileges to add to the calling process' effective privilege set.
These two functions
return the privilege set specified by the priv_type argument of the pid process. If pid is the calling process's privilege
set is returned.
The function returns the privileges as a vector, while the function returns the same as a char string.
The caller must free the memory allocated for the privilege vector or string when it is no longer referenced, by using or as
appropriate.
Similar to
except that it uses a privilege set type to specify the privileges to remove from the calling process' effective privilege
set.
Similar to
except that it uses a privilege set type to specify the privileges to set the calling process' effective privilege set.
RETURN VALUE
Upon successful completion, and return the following values:
Successful completion.
Function failed.
is set to indicate the error.
and return the following values:
pointer Successful completions. Returns a non-null pointer to the privilege vector and privilege string; for and respec-
tively. The caller of is responsible for freeing the resultant privilege vector using The caller of is responsible
for freeing the resultant privilege string using
NULL pointer Function failed. Returns a null pointer and sets to indicate the error.
ERRORS
If any of the following conditions occur, the functions fail and set
Invalid parameter or operation.
The function failed to allocate sufficient memory for its operation.
The privilege to be set in the effective set is not present in the
permitted set. Attempt to add or remove privileges of a different process fails.
pid is not valid.
EXAMPLES
#include <sys/privileges.h>
#include <stdio.h>
#include <stdlib.h>
#define priv_list "basic,policy,limit,!cmptread,!fork"
main()
{
if (priv_set_effective(priv_list, ",") )
{
printf("priv_set failed
");
exit(1);
}
printf("
The effective set of the process is %s
",
priv_set_to_str(privset_get(PRIV_EFFECTIVE, 0), ',', PRIV_STR_SHORT));
}
WARNINGS
Future product updates may introduce new privileges. In order to assure forward compatibility, applications must not remove a basic privi-
lege from their effective, potential, or retained set that they do not recognize.
One way to accomplish this is to use set negation notation: for instance, a process can set its effective set to "" instead of "". This
allows the application to maintain its functionality even when a new basic privilege is introduced.
Another way to accomplish this is to use the interface or to remove only the privileges that the application understands.
DEPENDENCIES
These functions are a part of the library.
SEE ALSO
priv_set_to_str(3), priv_str_to_set(3), privileges(5).
priv_add(3)