priv_add(3)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 argu‐
ment:
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' privi‐
lege 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 privi‐
lege 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 priv‐
ilege set.
These two functions
return the privilege set specified by the priv_type argu‐
ment 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 privi‐
lege 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 privi‐
lege 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 respectively. 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 opera‐
tion.
The privilege to be set in the effective set is not present in
the
permitted set. Attempt to add or remove privi‐
leges 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 \n");
exit(1);
}
printf("\nThe effective set of the process is %s\n",
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
privilege 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 ALSOpriv_set_to_str(3), priv_str_to_set(3), privileges(5).
priv_add(3)