nsg_init(3)nsg_init(3)NAMEnsg_init - Look up or create a NUMA Scheduling Group (libnuma library)
SYNOPSIS
#include <numa.h>
nsgid_t nsg_init(
key_t key,
ulong_t flags );
PARAMETERS
Specifies the key that identifies the NUMA Scheduling Group (NSG). This
value may be one of the following: An arbitrary binary value other than
zero If the NSG_GETBYPID flag is set, the process ID of a member
process of the requested NSG Specifies lookup or creation flags. The
following options are defined for the flags argument: Creates the NSG
and return its identifier. If NSG_CREATE and NSG_EXCL are both speci‐
fied, an error will be returned if the NSG identified by key already
exists. If set, then the key parameter is the process ID (pid_t) of a
process that is currently a member of the requested NSG. Otherwise, key
is an arbitrary binary value that identifies the requested NSG.
If the NSG identified by key does not already exist, an error
will be returned unless the NSG_CREATE flag is specified. If the
NSG_GETBYPID flag is set and the process identified by the value
of key does not exist, an error is returned.
If both the NSG_CREATE and the NSG_GETBYPID flags are set, and
the process identified by the value of key exists but is not
currently a member of an NSG, a new NSG will be created using
the value of key (the process's ID) and the process will be
attached to the new NSG. This establishes the “home RAD” of the
process as the home RAD for the NSG. A child process will not
inherit the NSG of the parent and, therefore, can be assigned to
any eligible RAD on the system. This flag is valid only if both
NSG_CREATE and NSG_GETBYPID are also specified. The NSG will be
marked for automatic deletion when the nsg_perm.nattach member
of the associated nsgid_ds structure transitions from nonzero to
zero.
DESCRIPTION
The nsg_init() function looks up and possibly creates the NSG identi‐
fied by the key parameter. The flags parameter supplies options for
the lookup or create operation.
After creating a new NSG, the nsg_init() function initializes an asso‐
ciated nsgid_ds structure as follows: The nsg_perm.cuid and
nsg_perm.uid members are set equal to the effective user ID of the
calling process. The nsg_perm.cgid and nsg_perm.gid members are set
equal to the effective group ID of the calling process. The low order
nine bits of nsg_perm.mode are set equal to the low order nine bits of
flags. The nsg_perm.nattach member is set to zero (or 1 if NSG_GET‐
BYPID is specified in flags).
The nsg_perm.mode permissions control operations on NSGs as follows:
Write permission is required to destroy the NSG or to set the owner IDs
and permissions. Read permission is required to query the NSG status
or membership roster. Execute permission is required to attach pro‐
cesses or threads to an NSG.
RETURN VALUES
Success. Failure. In this case, errno is set to indicate the error.
ERRORS
If the nsg_init() function fails, it sets errno to one of the following
values for the specified condition: An NSG already exists for the spec‐
ified key, but the caller does not have access based on the NSG's cur‐
rent permissions. An NSG already exists for the specified key, but
NSG_CREATE and NSG_EXCL flags were specified. No NSG exists for the
specified key, and the NSG_CREATE flag was not specified. No space
exists for the new NSG specified by NSG_CREATE. The NSG_GETBYPID flag
was set and the process identified by key was not found. One or more
illegal values for flags was set.
SEE ALSO
Functions: nsg_attach_pid(3), nsg_attach_thread(3), numa_intro(3)
Files: numa_types(4)nsg_init(3)