cpusetCreate - create a cpuset


SYNOPSIS

       #include <cpuset.h>

       int cpusetCreate(char *qname, cpuset_QueueDef_t *qdef);


DESCRIPTION

       The  cpusetCreate  function  is  used  to  create a cpuset
       queue.  Only processes running root user ID are allowed to
       create cpuset queues.

       The  qname  argument  is the name that will be assigned to
       the new cpuset.  The name of the cpuset must be a three to
       eight  character  string.   Queue  names having one or two
       characters are reserved for use by the system.

       The qdef argument is  a  pointer  to  a  cpuset_QueueDef_t
       structure   (defined   in  <cpuset.h>)  that  defines  the
       attributes of the queue to be created.  The memory for the
       cpuset_QueueDef_t    is   allocated   using   cpusetAlloc­
       QueueDef(3x)  and  it  is   released   using   cpusetFree­
       QueueDef(3x).   The cpuset_QueueDef_t structure is defined
       as follows:

            typedef struct {
                int                flags;
                char               *permfile;
                cpuset_CPUList_t   *cpu;
            } cpuset_QueueDef_t;

       flags is used to specify various control options  for  the
       cpuset  queue.   It  is  formed by OR-ing together zero or
       more of the following values:

        CCPPUUSSEETT_CCPPUU_EEXXCCLLUUSSIIVVEE
               Defines a cpuset to be restricted.   Only  threads
               attached  to  the  cpuset queue (descendents of an
               attached thread inherit the attachement) may  exe­
               cute on the CPUs contained in the cpuset.

        CCPPUUSSEETT_MMEEMMOORRYY_LLOOCCAALL
               Threads  assigned  to  the  cpuset will attempt to
               assign memory only from nodes within  the  cpuset.
               Assignment  of memory from outside the cpuset will
               occur only if no free  memory  is  available  from
               within  the  cpuset.   No restrictions are made on
               memory assignment to threads running  outside  the
               cpuset.

        CCPPUUSSEETT_MMEEMMOORRYY_EEXXCCLLUUSSIIVVEE
               Threads  assigned  to  the  cpuset will attempt to

               Assignment  of memory from outside the cpuset will
               occur only if no free  memory  is  available  from
               within  the  cpuset.   Threads not assigned to the
               cpuset will not use memory from within the  cpuset
               unless  no memory outside the cpuset is available.
               If, at the time a cpuset  is  created,  memory  is
               already  assigned to threads that are already run­
               ning, no attempt will be made to  explicitly  move
               this  memory.   If  page migration is enabled, the
               pages will be migrated  when  the  system  detects
               that most references to the pages are non-local.

        CCPPUUSSEETT_MMEEMMOORRYY_KKEERRNNEELL_AAVVOOIIDD
               The kernel should attempt to avoid allocating mem­
               ory from nodes contained in this cpuset. If kernel
               memory  requests  cannot be satisfied from outside
               this cpuset, this option will be ignored and allo­
               cations  will  occur from within the cpuset. (This
               avoidance currently extends only to keeping buffer
               cache away from the protected nodes.)

        CCPPUUSSEETT_MMEEMMOORRYY_MMAANNDDAATTOORRYY
               The  kernel  will  limit all memory allocations to
               nodes that are contained in this cpuset. If memory
               requests  cannot be satisfied, the allocating pro­
               cess will sleep until  memory  is  available.  The
               process  will  be  killed if no more memory can be
               allocated. See policies below.

        CCPPUUSSEETT_PPOOLLIICCYY_PPAAGGEE
               Requires MEMORY_MANDATORY.  This  is  the  default
               policy if no policy is specified. This policy will
               cause the kernel to page user pages  to  the  swap
               file (see swap(1M)) to free physical memory on the
               nodes contained in this cpuset. If swap  space  is
               exhausted, the process will be killed.

        CCPPUUSSEETT_PPOOLLIICCYY_KKIILLLL
               Requires MEMORY_MANDATORY. The kernel will attempt
               to free as much  space  as  possible  from  kernel
               heaps,  but  will  not page user pages to the swap
               file.  If all physical memory on  the  nodes  con­
               tained  in  this cpuset are exhausted, the process
               will be killed.

       The permfile member is the name of the file  that  defines
       the  access  permissions  for  the cpuset queue.  The file
       permissions of  filename  referenced  by  permfile  define
       access  to  the cpuset.  Every time permissions need to be
       checked, the current permissions of this  file  are  used.
       Thus,  it is possible to change the access to a particular
       cpuset without having to tear it  down  and  recreate  it,
       simply by changing the access permissions.  Read access to

       cpuset, while execute permission allows the user to attach
       a process to the cpuset.

       The cpu member is a pointer to a  cpuset_CPUList_t  struc­
       ture.   The  memory  for the cpuset_CPUList_t structure is
       allocated and released when the  cpuset_QueueDef_t  struc­
       ture   is   allocated   and   released  (see  cpusetAlloc­
       QueueDef(3x)).  The  cpuset_CPUList_t  structure  contains
       the   list   of   CPUs   assigned   to  the  cpuset.   The
       cpuset_CPUList_t  structure  (defind  in  <cpuset.h>)   is
       defined as follows:

            typedef struct {
                int    count;
                int    *list;
            } cpuset_CPUList_t;

       The  count  member defines the number of CPUs contained in
       the list.

       The list member is  pointer  to  the  list  (an  allocated
       array)  of  the CPU IDs.  The memory for the list array is
       allocated and released when the cpuset_CPUList_t structure
       is allocated and released.


EXAMPLES

       This  example  creates a cpuset queue that has access con­
       troled by the file /usr/tmp/mypermfile, contains  CPU  IDs
       4, 8, and 12, is CPU exclusive and memory exclusive:

            cpuset_QueueDef_t *qdef;
            char              *qname = "myqueue";

            /* Alloc queue def for 3 CPU IDs */
            qdef = cpusetAllocQueueDef(3);
            if (!qdef) {
                perror("cpusetAllocQueueDef");
                exit(1);
            }

            /* Define attributes of the cpuset */
            qdef->flags = CPUSET_CPU_EXCLUSIVE
                        | CPUSET_MEMORY_EXCLUSIVE;
            qdef->permfile = "/usr/tmp/mypermfile"
            qdef->cpu->count = 3;
            qdef->cpu->list[0] = 4;
            qdef->cpu->list[1] = 8;
            qdef->cpu->list[2] = 12;

            /* Request that the cpuset be created */
            if (!cpusetCreate(qname, qdef)) {
                perror("cpusetCreate");

            }
            cpusetFreeQueueDef(qdef);


NOTES

       cpusetCreate  is  found in the library "libcpuset.so", and
       will be loaded if the option --llccppuusseett is used  with  cc(1)
       or ld(1).


RESTRICTIONS

       Not  all  of  the above capabilities are implemented.  See
       the RESTRICTIONS secion  in  manual  entry  cpuset(4)  for
       details.


SEE ALSO

       cpuset(1),       cpusetAllocQueueDef(3x),      cpusetFree­
       QueueDef(3x).  cpuset(5).


DIAGNOSTICS

       If successful, cpusetCreate returns a 1.  If  cpusetCreate
       fails, it returns the value 0 and errno is set to indicate
       the error.  The possible values for  errno  include  those
       values set by fopen(3S) and the following:

       ENODEV Request  for  CPU IDs that do not exist on the sys­
              tem.

       EPERM  Request for CPU 0 as part of an exclusive cpuset is
              not permitted.


Man(1) output converted with man2html