NAME    [Toc]    [Back]

       nsg_init - Look up or create a NUMA Scheduling Group (libnuma
 library)

SYNOPSIS    [Toc]    [Back]

       #include <numa.h>

       nsgid_t nsg_init(
               key_t key,
               ulong_t flags );

PARAMETERS    [Toc]    [Back]

       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 specified, 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    [Toc]    [Back]

       The nsg_init() function looks up and possibly creates  the
       NSG  identified 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  associated  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_GETBYPID 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 processes
 or threads to an NSG.

RETURN VALUES    [Toc]    [Back]

       Success.  Failure. In this case, errno is set to  indicate
       the error.

ERRORS    [Toc]    [Back]

       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 specified key, but the caller does
       not have access based on the  NSG's  current  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    [Toc]    [Back]

       Functions:     nsg_attach_pid(3),    nsg_attach_thread(3),
       numa_intro(3)

       Files: numa_types(4)



                                                      nsg_init(3)