Appendix A. Programming Guide for Resource Management
Prev |  | Next

## Appendix A. Programming Guide for Resource Management

This appendix contains information for job limits, the User Limits DataBase (ULDB), and cpusets system programming.

This appendix contains the following sections:

- “Application Programming Interface for Job Limits”

- “Application Programming Interface for the ULDB”

- “Application Programming Interface for the Cpuset System”

## Application Programming Interface for Job Limits

This section describes the data types and function calls used by the library interface to the application programming interface (API) functions.

### Data Types

This section describes the specific data types that are used in the library interface to the API functions.

All limit values are specified by the `rlimit` structure defined for process limits in the `/usr/include/sys/resource.h` system include file:

    typedef unsigned long rlim_t;
       struct rlimit_t {
               rlim_t        rlim_cur;
               rlim_t        rlim_max;
       };

The job ID is defined as a signed 64 bit value. It is treated opaquely by applications. The definition of `jid_t` resides in the `sys/types.h` system include file.

    typedef int64_t jid_t;

| Note: Job limit values (`rlim_t`) are 64-bit in both n32 and n64 binaries. Consequently, n32 binaries can set 64-bit limits. o32 binaries cannot set 64-bit limits because `rlim_t` is 32-bits in o32 binaries. IRIX supports three Application Binary Interfaces (ABIs): o32, n64, and n32 (for more information on ABIs, see the `abi(5)` man page). For more information on `rlimit_*` values, see “Using systune to Display and Set Process Limits” in Chapter 1 and “showlimits” in Chapter 2.

### Function Calls

The API for job limits is defined by a set of functions defined in the `libc.a` library. Each of the functions invokes the `syssgi(2)` system interface to perform the necessary operations. The function prototypes reside in the `/usr/include/sys/resource.h` system include file.

#### `getjlimit` and `setjlimit`

The `getjlimit` function retrieves limits on the consumption of a variety of system resources by a job and the `setjlimit` function sets these limits:

    #include <sys/resource.h>
    int getjlimit(jid_t jid, int resource, struct rlimit *rlp)
    int setjlimit(jid_t jid, int resource, struct rlimit *rlp)

For additional information, see the `getjlimit(2)` man page.

#### `getjusage`

The `getjusage` function retrieves the resource usage values for the specified job ID:

    #include <sys/resource.h>
    int getjusage(jid_t jid, int resource, struct jobrusage *up)

If the jid parameter is zero, usage values for the current job will be returned. If jid is non-zero, it represents the job ID of the job for which usages values are retrieved. The resource parameter specifies the resource for which the usage values are returned. Allowable values are taken from the `JLIMIT_xxx` macros found in the `sys/resource.h` file. For example, the `JLIMIT_CPU` macro is for CPU time. The `up` parameter points to a `rusage` structure in the user program where the usage values will be returned.

For additional information, see the `getjusage(2)` man page.

#### `getjid`

The `getjid` function returns the job ID associated with the current process:

    #include <sys/resource.h>
    jid_t getjid(void);

For additional information, see the `getjid(2)` man page.

#### `killjob`

The `killjob` function sends a signal to all processes of the specified job ID:

    #include <sys/resource.h>
    int killjob(jid_t jid, int signal)

For additional information, see the `killjob(2)` man page.

#### `jlimit_startjob`

The `jlimit_startjob` function creates a new job and sets the job limits to the limit values in the ULDB.

The `jlimit_startjob` function follows:

    #include <sys/resource.h>
    jid_t    jlimit_startjob(char *username, uid_t uid, char *domainname);

For additional information, see the `jlimit_startjob(2)` man page.

#### `makenewjob`

The `makenewjob` function creates a new job container:

    #include <sys/resource.h>
    jid_t makenewjob(uid_t user, jid_t rjid)

For additional information, see the `makenewjob(2)` man page.

#### `setjusage`

The `setjusage` function updates the resource usage values for the specified job ID.

The `setjusage` function follows:

    #include <sys/resource.h>

    int setjusage(jid_t jid, int resource, struct jobrusage *up)

The `setjusage` function updates the resource usage values for the specified job ID. If the `jid` parameter is zero, usage values for the current job are updated. If `jid` is non-zero, it represents the job ID of the job for which usages values are updated. The resource parameter specifies the resource for which the usage values are to be updated. Allowable values are taken from the `JLIMIT_xxx` macros found in the `sys/resource.h` file. For example, the `JLIMIT_CPU` macro is for CPU time. The `up` parameter points to a `jobrusage` structure in the user program where the usage values are stored.

To be able to update resource usage values using `setjusage`, the job must be ignoring the accumulation and enforcement of the limits for the specified resource. It is determined at job creation if it will be ignoring specific resource limits, based upon the values of the following system tunable parameters:

`[jlimit_numproc_ign]` | Ignore the accumulation and enforcement of limits on the number of processes in the job.
`[jlimit_pmem_ign]` | Ignore the accumulation and enforcement of the total aggregate physical memory usage for the job.
`[jlimit_pthread_ign]` | Ignore the accumulation and enforcement of the number of pthreads in the job.
`[jlimit_nofile_ign]` | Ignore the accumulation and enforcement of the number of open files in the job.
`[jlimit_rss_ign]` | Ignore the accumulation and enforcement of the total aggregate resident set size for the job.
`[jlimit_vmem_ign]` | Ignore the accumulation and enforcement of total aggregate virtual memory size for the job.
`[jlimit_data_ign]` | Ignore the accumulation and enforcement of total aggregate data segment size for the job.
`[jlimit_cpu_ign]` | Ignore the accumulation and enforcement of CPU time usage for the job.

The values for these tunable parameters can be changed at run-time. By default, these values are set so that the accumulation and enforcement of resource usage limits are not ignored. Changing these values at run-time will only affect the behavior of jobs created after the parameter was changed. Those jobs that existed prior to the parameter being changed will continue with unchanged concerning the accumulation and enforcement of job limits for resource usage.

For additional information about system tunable parameters, see the `systune(1M)` man page.

The process attempting to use `setjusage` must have the `CAP_PROC_MGT` capability. See the `capability(4)` and `capabilities(4)` man pages for more information on the capability mechanism that provides fine grained control over the privileges of a process.

For additional information, see the `setjusage(2)` man page.

#### `setwaitjobpid`

The `setwaitjobpid` function sets a job to wait for a specified `pid` to call the `waitjob` function.

The `setwaitjobpid` function follows:

    #include <sys/resource.h>
    int setwaitjobpid(jid_t rjid, pid_t wpid)

For additional information, see the `setwaitjobpid(2)` man page.

#### `waitjob`

The `waitjob` function obtains information about a terminated job that has been set with `setwaitjobpid` argument to wait.

The `waitjob` function follows:

    #include <sys/resource.h>
    jid_t waitjob(job_info_t *jobinfo)

For additional information, see the `waitjob(2)` man page.

### Error Messages

For error message information, see the appropriate man pages and “Error Messages” in Chapter 2.

## Application Programming Interface for the ULDB

This section describes the data types and function calls used by the library interface to the ULDB.

### Data Types

This section defines the specific data types that are used by the library interface to the user limits information. All ULDB definitions are in the `/usr/include/uldb.h` include file.

Binary limit values are held as unsigned 64 bit values as follows:

    typedef rlim_t uldb_limit_t;

#### `uldb_namelist_t`

The `uldb_namelist_t` data type is used to contain name lists such as limit names, domain names, and so on. The `namelist` structure contains a count of the items and a pointer to a list of pointers to the names. The `uldb_namelist_t` data type is as follows:

    typedef struct uldb_namelist_s {
          int uldb_nitems,                # number of names in the list
          char **uldb_names               # list of name pointers
       } uldb_namelist_t;

#### `uldb_limitlist_t`

The `uldb_limitlist_t` data type is used to contain a list of binary limit values. The limit list structure contains a count of the items and a pointer to an array of limit values. The `uldb_limitlist_t` data type follows:

    typedef struct uldb_limitlist_s {
          int uldb_nitems,                # number of limit values in the list
          uldb_limit_t *uldb_limits       # list of limit pointers
       } uldb_limitlist_t;

### Function Calls

This section defines the function calls that are used by the library interface to the user limits information.

The functions that retrieve limit values are as follows:

- `uldb_get_limit_values`

- `uldb_get_value_units`

- `uldb_get_limit_names`

- `uldb_get_domain_names`

#### `uldb_get_limit_values`

The `uldb_get_limit_values` function retrieves a set of limit values for a domain or user. If there is no explicit entry for the specified user, the domain defaults are returned. The set of limits requested is provided using the `uldb_namelist_t` structure. The returned limit list pointer references a new `uldb_limitlist_t` structure created by a call to the `malloc` routine that the application is responsible for freeing when the structure is no longer needed. The order of limit values in the returned `uldb_limitlist_t` structure corresponds to the order of limit names in the input `uldb_namelist_t` structure. If the user name is NULL, the list of limits for the domain are retrieved instead of the user limits.

An example of `uldb_get_limit_values` follows:

    #include include/uldb.h
    uldb_limitlist_t *        # returns pointer to limit list or NULL if error
       uldb_get_limit_values (         #
          char *domain_name,           # pointer to domain name
          char *user_name,             # name of user
          uldb_namelist_t *limits);    # namelist containing limit names

#### `uldb_get_value_units`

The `uldb_get_value_units` function returns a limit list structure containing the modifier values or units for the specified list of limits. The accepted modifier values are defined in the `uldb.h` header file. The returned list of names is provided by the `uldb_namelist_t` structure created by a call to the `malloc` function. The application is responsible for freeing this structure when it is no longer needed.

An example of `uldb_get_value_units` follows:

    #include <include/uldb.h>
    uldb_limitlist_t *        # returns pointer to limit list or NULL if error
       uldb_get_value_units (          #
          char *domain_name,           # pointer to domain name
          char *user_name,             # name of user
          uldb_namelist_t *limits);    # namelist containing limit names

#### `uldb_get_limit_names`

The `uldb_get_limit_names` function retrieves the complete list of limit names defined for a domain. The returned list of names is provided by the `uldb_namelist_t` structure created by a call to the `malloc` function. The application is responsible for freeing this structure when it is no longer needed.

An example of `uldb_get_limit_names` follows:

    #include <include/uldb.h>
       uldb_namelist_t *               # returns pointer to name list or NULL if error
       uldb_get_limit_names (
           char *domain_name);         # pointer to domain name

#### `uldb_get_domain_names`

The `uldb_get_domain_names` function retrieves the complete list of domain names defined in the ULDB. The returned list of names is provided the `uldb_namelist_t` structure created by a call to the `malloc` function. The application is responsible for freeing this structure when it is no longer needed.

    #include <include/uldb.h>
    uldb_namelist_t *               # returns pointer to name list or NULL if error
       uldb_get_domain_names (
           void);

The functions that manage memory are as follows:

- `uldb_free_namelist`

- `uldb_free_limit_list`

#### `uldb_free_namelist`

The `uldb_free_namelist` function deletes a `namelist` structure and all its components.

An example of `uldb_free_namelist` follows:

    #include <include/uldb.h>
    void                             # returns 0 if okay, -1 on error
       uldb_free_namelist (            #
          uldb_namelist_t *names);     # pointer to namelist to be freed

#### `uldb_free_limit_list`

The `uldb_free_limit_list` function deletes a limitlist structure and all its components.

An example of `uldb_free_limit_list` follows:

    #include <include/uldb.h>
    void                             # returns 0 if okay, -1 on error
       uldb_free_limit_list (          #
          uldb_limit_list_t *limits);  # pointer to limit list to be freed

#### Error Messages

For error message information, see the `uldb_get_limit_values(3c)` and `jlimit_startjob(3c)` man pages or “Error Messages” in Chapter 2.

## Application Programming Interface for the Cpuset System

The cpuset library provides interfaces that allow a programmer to create and destroy cpusets, retrieve information about existing cpusets, obtain information about the properties associated with existing cpusets, and to attach a process and all of its children to a cpuset.

The cpuset library requires that a permission file be defined for a cpuset that is created. The permissions file may be an empty file, since it is only the file permissions for the file that define access to the cpuset. When permissions need to be checked, the current permissions of the file are used. It is therefore possible to change access to particular cpuset without having to tear it down and recreate it, simply by changing the access permissions. Read access allows a user to retrieve information about a cpuset while execute permission allows the user to attach a process to the cpuset.

The cpuset library is provided as a N32 Dynamic Shared Object (DSO) library. The library file is `libcpuset.so`, and it is normally located in the directory `/lib32`. Users of the library must include the `cpuset.h` header file which is located in `/usr/include`. The function interfaces provided in the cpuset library are declared as optional interfaces to allow for backwards compatibility as new interfaces are added to the library.

| Note: The Cpuset library is only available on IRIX 6.5.8 and later releases.

It is possible to compile and run a program that uses this DSO and its interfaces if they are available, but continues to execute if they are missing. To do this, a replacement library for `libcpuset.so` must be made available. For an example of how to create a replacement library, see the `cpuset(5)` man page. For more information on DSO, see the `DSO(5)` man page.

The function interfaces within the cpuset library include:

Function interface | Description
`cpusetCreate(3x)` | Creates a cpuset
`cpusetAttach(3x)` | Attaches the current process to a cpuset
`cpusetAttachPID(3x)` | Attaches a specific process to a cpuset
`cpusetDetachAll(3x)` | Detaches all threads from a cpuset
`cpusetDetachPID(3x)` | Detaches a specific process from a cpuset
`cpusetDestroy(3x)` | Destroys a cpuset
`cpusetGetCPUCount(3x)` | Obtains the number of CPUs configured on the system
`cpusetGetCPUList(3x)` | Gets the list of all CPUs assigned to a cpuset
`cpusetGetName(3x)` | Gets the name of the cpuset to which a process is attached
`cpusetGetNameList(3x)` | Gets a list of names for all defined cpusets
`cpusetGetPIDList(3x)` | Gets a list of all PIDs attached to a cpuset
`cpusetGetProperties(3x)` | Retrieve various properties associated with a cpuset
`cpusetMove(3x)` | Temporarily moves a process, identified by its PID or ASH, out of specified cpuset
`cpusetMoveMigrate(3x)` | Move a specific process, identified by its PID or ASH, and its associated memory, from one cpuset to another
`cpusetAllocQueueDef(3x)` | Allocates a `cpuset_QueueDef_t` structure
`cpusetFreeQueueDef(3x)` | Releases memory used by a `cpuset_QueueDef_t` structure
`cpusetFreeCPUList(3x)` | Releases memory used by a`cpuset_CPUList_t` structure
`cpusetFreeNameList(3x)` | Releases memory used by a`cpuset_NameList_t` structure
`cpusetFreePIDList(3x)` | Releases memory used by a `cpuset_PIDList_t` structure
`cpusetFreeProperties(3x)` | Release memory used by a `cpuset_Properties_t` structure

### Management functions

This section contains the man pages for the following Cpuset System library functions:

`cpusetCreate(3x)` |  | Creates a cpuset
`cpusetAttach(3x)` |  | Attaches the current process to a cpuset
`cpusetAttachPID(3x)` |  | Attaches a specific process to a cpuset
`cpusetDetachPID(3x)` |  | Detaches a specific process from a cpuset
`cpusetDetachAll(3x)` |  | Detaches all threads from a cpuset
`cpusetDestroy(3x)` |  | Destroys a cpuset
`cpusetMove(3x)` |  | Temporarily moves a process, identified by its PID, JID, or ASH, out of specified cpuset
`cpusetMoveMigrate(3x)` |  | Move a specific process, identified by its PID, JID, or ASH, and its associated memory, from one cpuset to another

`cpusetCreate`(3x)

NAME

`cpusetCreate` - creates 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 IRIX operating system.

The `qdef` argument is a pointer to a `cpuset_QueueDef_t` structure (defined in the `cpuset.h` include file) that defines the attributes of the queue to be created. The memory for `cpuset_QueueDef_t` is allocated using `cpusetAllocQueueDef(3x)` and it is released using `cpusetFreeQueueDef(3x)`. The `cpuset_QueueDef_t` structure is defined as follows:

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

The `flags` member is used to specify various control options for the cpuset queue. It is formed by applying the bitwise Exclusive-OR operator to zero or more of the following values:

`CPUSET_CPU_EXCLUSIVE` | Defines a cpuset to be restricted. Only threads attached to the cpuset queue (descendents of an attached thread inherit the attachment) may execute on the CPUs contained in the cpuset.
`CPUSET_MEMORY_LOCAL` | 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.
`CPUSET_MEMORY_EXCLUSIVE` | 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. 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 running, 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 nonlocal.
`CPUSET_MEMORY_KERNEL_AVOID` | The kernel should attempt to avoid allocating memory from nodes contained in this cpuset. If kernel memory requests cannot be satisfied from outside this cpuset, this option will be ignored and allocations will occur from within the cpuset. (This avoidance currently extends only to keeping buffer cache away from the protected nodes.)
`CPUSET_MEMORY_MANDATORY` | The kernel will limit all memory allocations to nodes that are contained in this cpuset. If memory requests cannot be satisfied, the allocating process will sleep until memory is available. The process will be killed if no more memory can be allocated. See policies below.
`CPUSET_POLICY_PAGE` | 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.
`CPUSET_POLICY_KIL` | 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 contained 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 the `permfile` allows a user to retrieve information about a 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` structure. The memory for the `cpuset_CPUList_t` structure is allocated and released when the `cpuset_QueueDef_t` structure is allocated and released (see `cpusetAllocQueueDef(3x)`). The `cpuset_CPUList_t` structure contains the list of CPUs assigned to the cpuset. The `cpuset_CPUList_t` structure (defined in the `cpuset.h` include file) 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 controlled by the file `/usr/tmp/mypermfile`; contains CPU IDs 4, 8, and 12; and 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");
                       exit(1);
                   }
                   cpusetFreeQueueDef(qdef);

NOTES

The `cpusetCreate` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetAllocQueueDef(3x)`, `cpusetFreeQueueDef(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetCreate` function returns a value of 1. If the `cpusetCreate` function 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)`, `sysmp(2)`, and the following:

`ENODEV` |  | Request for CPU IDs that do not exist on the system.
`EPERM` |  | Request for CPU 0 as part of an exclusive cpuset is not permitted.

`cpusetAttach`(3x)

NAME

`cpusetAttach` - attaches the current process to a cpuset

SYNOPSIS

    #include <cpuset.h>
    int cpusetAttach( char *qname);

DESCRIPTION

The `cpusetAttach` function is used to attach the current process to the cpuset identified by `qname`. Every cpuset queue has a file that defines access permissions to the queue. The execute permissions for that file will determine if a process owned by a specific user can attach a process to the cpuset queue.

The `qname` argument is the name of the cpuset to which the current process should be attached.

EXAMPLES

This example attaches the current process to a cpuset queue named `mpi_set`.

    char *qname = "mpi_set";

                   /* Attach to cpuset, if error - print error & exit */
                   if (!cpusetAttach(qname)) {
                       perror("cpusetAttach");
                       exit(1);
                   }

NOTES

The `cpusetAttach` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetCreate(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetAttach` function returns a value of 1. If the `cpusetAttach` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetAttachPID`(3x)

NAME

`cpusetAttachPID` - attach a specific process to a cpuset

SYNOPSIS

    #include <cpuset.h>

         int cpusetAttachPID(qname, pid);

         char *qname;

         pid_t pid;

DESCRIPTION

The `cpusetAttachPID` function is used to attach a specific process identified by its PID to the cpuset identified by `qname`. Every cpuset queue has a file that defines access permissions to the queue. The execute permissions for that file will determine if a process owned by a specific user can attach a process to the cpuset queue.

The `qname` argument is the name of the cpuset to which the specified process should be attached.

EXAMPLES

This example attaches the current process to a cpuset queue named `mpi_set`.

    char *qname = "mpi_set";

    /* Attach to cpuset, if error - print error & exit */
    if (!cpusetAttachPID(qname, pid)) {
    perror("cpusetAttachPID");
    exit(1);                }

NOTES

`cpusetAttachPID` is found in the library `libcpuset.so`, and will be loaded if the option `-l cpuset` is used with `cc(1)` or `ld(1)`.

SEE ALSO

`cpuset(1)` `cpusetCreate(3x)``cpusetDetachPID(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, `cpusetAttachPID` returns a 1. If `cpusetAttachPID` fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetDetachPID`(3x)

NAME

`cpusetDetachPID` - detach a specific process from a cpuset

SYNOPSIS

    #include <cpuset.h>

         int cpusetDetachPID(qname, pid);

         char *qname;

         pid_t pid;

DESCRIPTION

The `cpusetDetachPID` function is used to detach a specific process identified by its PID to the cpuset identified by `qname`. Every cpuset queue has a file that defines access permissions to the queue. The execute permissions for that file will determine if a process owned by a specific user can detach a process from the cpuset queue.

The `qname` argument is the name of the cpuset to which the specified process should be detached.

EXAMPLES

This example detaches the current process from a cpuset queue named `mpi_set`.

    char *qname = "mpi_set";

    /* Detach from cpuset, if error - print error & exit */
    if (!cpusetDetachPID(qname, pid)) {
    perror("cpusetDetachPID");
    exit(1);                }

NOTES

`cpusetDetachPID` is found in the library `libcpuset.so`, and will be loaded if the option `-l cpuset` is used with `cc(1)` or `ld(1)`.

SEE ALSO

`cpuset(1)` `cpusetCreate(3x)``cpusetAttachPID(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, `cpusetDetachPID` returns a 1. If `cpusetAttachPID` fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetDetachAll`(3x)

NAME

`cpusetDetachAll` - detaches all threads from a cpuset

SYNOPSIS

    #include <cpuset.h>
    int cpusetDetachAll(char *qname);

DESCRIPTION

The `cpusetDetachAll` function is used to detach all threads currently attached to the specified cpuset. Only a process running with root user ID can successfully execute `cpusetDetachAll`.

The `qname` argument is the name of the cpuset that the operation will be performed upon.

EXAMPLES

This example detaches the current process from a cpuset queue named `mpi_set`.

    char *qname = "mpi_set";

                   /* Detach all members of cpuset, if error - print error & exit */
                   if (!cpusetDetachAll(qname)) {
                       perror("cpusetDetachAll");
                       exit(1);
                   }

NOTES

The `cpusetDetachAll` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetAttach(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetDetachAll` function returns a value of 1. If the `cpusetDetachAll` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetDestroy`(3x)

NAME

`cpusetDestroy` - destroys a cpuset

SYNOPSIS

    #include <cpuset.h>
    int cpusetDestroy(char *qname);

DESCRIPTION

The `cpusetDestroy` function is used to destroy the specified cpuset. The `qname` argument is the name of the cpuset that will be destroyed. Only processes running with root user ID are allowed to destroy cpuset queues. A cpuset can only be destroyed if there are no threads currently attached to it.

EXAMPLES

This example destroys the cpuset queue named `mpi_set`.

    char *qname = "mpi_set";

                   /* Destroy, if error - print error & exit */
                   if (!cpusetDestroy(qname)) {
                       perror("cpusetDestroy");
                       exit(1);
                   }

NOTES

The `cpusetDestroy` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetCreate(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetDestroy` function returns a value of 1. If the `cpusetDestroy` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetMove`(3x)

NAME

`cpusetMove` - moves processes, associated with an ID, to another cpuset

SYNOPSIS

    #include <cpuset.h>

    int cpusetMove(char *from_qname, char *to_qname, int idtype, int64_t id);

DESCRIPTION

The `cpusetMove` function is used to temporarily move processes, associated with an ID, identified by `id` from one cpuset to another. This function does not move the memory associated with the processes. This function should be used in conjunction with `cpusetMoveMigrate`.

The `from_qname` argument is the name of the cpuset from which the processes are moved. Using a NULL for this argument, results in having all the processes identified by `id` to be moved into the global cpuset. Global cpuset is a term used to describe all the CPUs that are not in a cpuset.

The `to_qname` argument is the name of the destination cpuset for the specified ID. Using a NULL for this argument, will result in having all the processes identified by `id` to be moved into the global cpuset.

The `idType` argument defines the type of number passed in as `id`. The possible options for `idType` are `CPUSET_PID` (Process ID), `CPUSET_PGID` (Process Group ID), `CPUSET_JID` (Job ID), `CPUSET_SID` (Session ID), or `CPUSET_ASH` (Array Session Handle).

This function requires the processes associated with `id` to be stopped before it can enact the move. A test is made to see if all the processes are stopped. If `id` has processes A, B, and C, and B is stopped, A and C are stopped. Then, after the move, A and C are restarted (but not B).

This function requires root privileges on standard IRIX and CAP_SCHED_MGMT on Trusted IRIX (TRIX).

EXAMPLES

This example moves a process ID from the cpuset queue named `mpi_set` to the cpuset queue named `my_set`.

    char *from_qname = "mpi_set";
    char *to_qname = "my_set";
    int64_t id = 1534;

    /* move from mpi_set to my_set,
    * if error - print error & exit
    */
    if (!cpusetMove(from_qname, to_qname, CPUSET_PID, id)) {
    perror("cpusetMove");
    exit(1);
    }

NOTES

The `cpusetMove` function is found in the library `libcpuset.so`, and will be loaded if the option `-l` `cpuset` is used with `cc(1)` or `ld(1)`.

SEE ALSO

`cpuset(1)`, `cpusetCreate(3x)`, `cpusetMoveMigrate(3x)` and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetMove` function returns a value of 1. If the `cpusetMove` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

`cpusetMoveMigrate`(3x)

NAME

`cpusetMoveMigrate` - moves processes, identified by an ID, and their associated memory, from one cpuset to another

SYNOPSIS

    #include <cpuset.h>
    int cpusetMoveMigrate(char *from_qname, char *to_qname, int idtype,
    int64_t id);

DESCRIPTION

The `cpusetMoveMigrate` function is used to move processes, and their associated memory, identified by `id` from one cpuset to another.

The `from_qname` argument is the name of the cpuset from which the processes are moved. Using a NULL for this argument, results in having all the processes identified by `id` to be moved into the global cpuset. The global cpuset is a term used to describe all the CPUs that are not in a cpuset.

The `to_qname` argument is the name of the destination cpuset for the specified ID. Using a NULL for this argument, results in having all the processes identified by `id` to be moved into the global cpuset.

The `idtype` argument defines the type of number passed in as `id`. The possible options for `idtype` are `CPUSET_PID` (Process ID), `CPUSET_PGID` (Process Group ID), `CPUSET_JID` (Job ID), `CPUSET_SID` (Session ID), or `CPUSET_ASH` (Array Session Handle).

This function requires the processes associated with `id` to be stopped before it can enact the move. A test is made to see if all the processes are stopped. If `id` has processes A, B, and C, and B is stopped, A and C are stopped. Then, after the move, A and C are restarted (but not B).

This function requires root privileges on standard IRIX, and CAP_SCHED_MGMT on Trusted IRIX (TRIX).

EXAMPLES

This example moves a process ID from the cpuset queue named `mpi_set` to the cpuset queue named `my_set`.

    char *from_qname = "mpi_set";
    char *to_qname = "my_set";
    int64_t id = 1534;

    /* move from mpi_set to my_set,
    * if error - print error & exit
    */
    if (!cpusetMoveMigrate(from_qname, to_qname, CPUSET_PID, id)) {
    perror("cpusetMoveMigrate");
    exit(1);
    }

NOTES

The `cpusetMoveMigrate` function is found in the library `libcpuset.so`, and will be loaded if the option `-l` `cpuset` is used with `cc(1)` or `ld(1)`.

SEE ALSO

`cpuset(1)`, `cpusetCreate(3x)`, `cpusetMove(3x)` and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetMoveMigrate` function returns a value of 1. If the `cpusetMoveMigrate` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)`.

### Retrieval Functions

This section contains the man pages for the following Cpuset System library retrieval functions:

`cpusetGetCPUCount(3x)` |  | Obtains the number of CPUs configured on the system
`cpusetGetCPUList(3x)` |  | Gets the list of all CPUs assigned to a cpuset
`cpusetGetName(3x)` |  | Gets the name of the cpuset to which a process is attached
`cpusetGetNameList(3x)` |  | Gets a list of names for all defined cpusets
`cpusetGetPIDList(3x)` |  | Gets a list of all PIDs attached to a cpuset
`cpusetGetProperties(3x)` |  | Retrieve various properties associated with a cpuset
`cpusetAllocQueueDef(3x)` |  | Allocates a `cpuset_QueueDef_t` structure

`cpusetGetCPUCount`(3x)

NAME

`cpusetGetCPUCount` - obtains the number of CPUs configured on the system

SYNOPSIS

    #include <cpuset.h>
    int cpusetGetCPUCount(void);

DESCRIPTION

The `cpusetGetCPUCount` function returns the number of CPUs that are configured on the system.

EXAMPLES

This example obtains the number of CPUs configured on the system and then prints out the result.

    int ncpus;

    if (!(ncpus = cpusetGetCPUCount())) {
    perror("cpusetGetCPUCount");
    exit(1);
    }
    printf("The systems is configured for %d CPUs\n",
            ncpus);

NOTES

The `cpusetGetCPUCount` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)` and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetCPUCount` function returns a value greater than or equal to the value of 1. If the `cpusetGetCPUCount` function fails, it returns the value 0 and `errno` is set to indicate the error. The possible values for `errno` are the same as those used by `sysmp(2)` and the following:

`ERANGE` |  | Number of CPUs configured on the system is not a value greater than or equal to 1.

`cpusetGetCPUList`(3x)

NAME

`cpusetGetCPUList` - gets the list of all CPUs assigned to a cpuset

SYNOPSIS

    #include <cpuset.h>
    cpuset_CPUList_t *cpusetGetCPUList(char *qname);

DESCRIPTION

The `cpusetGetCPUList` function is used to obtain the list of the CPUs assigned to the specified cpuset. Only processes running with a user ID or group ID that has read access permissions on the permissions file can successfully execute this function. The `qname` argument is the name of the specified cpuset.

The function returns a pointer to a structure of type `cpuset_CPUList_t` (defined in the `cpuset.h` include file). The function `cpusetGetCPUList` allocates the memory for the structure and the user is responsible for freeing the memory using the `cpusetFreeCPUList(3x)` function. The `cpuset_CPUList_t` structure looks similar to this:

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

The `count` member is the number of CPU IDs in the list. The `list` member references the memory array that holds the list of CPU IDs. The memory for `list` is allocated when the `cpuset_CPUList_t` structure is allocated and it is released when the `cpuset_CPUList_t` structure is released.

EXAMPLES

This example obtains the list of CPUs assigned to the cpuset `mpi_set` and prints out the CPU ID values.

    char *qname = "mpi_set";
        cpuset_CPUList_t *cpus;

        /* Get the list of CPUs else print error & exit */
        if (!( cpus = cpusetGetCPUList(qname))) {
            perror("cpusetGetCPUList");

            exit(1);
        }
        if (cpus->count == 0) {
            printf("CPUSET[%s] has 0 assigned CPUs\n",
                    qname);
        } else {
            int i;

            printf("CPUSET[%s] assigned CPUs:\n",
                    qname);
            for (i = 0; i < cpuset->count; i++)
                printf("CPU_ID[%d]\n", cpuset->list[i]);
        }
        cpusetFreeCPUList(cpus);

NOTES

The `cpusetGetCPUList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreeCPUList(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetCPUList` function returns a pointer to a`cpuset_CPUList_t` structure. If the `cpusetGetCPUList` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` include those values as set by `sysmp(2)` and `sbrk(2)`.

`cpusetGetName`(3x)

NAME

`cpusetGetName` - gets the name of the cpuset to which a process is attached

SYNOPSIS

    #include <cpuset.h>
    cpuset_NameList_t *cpusetGetName(pid_t pid);

DESCRIPTION

The `cpusetGetName` function is used to obtain the name of the cpuset to which the specified process has been attached. The pid argument specifies the process ID. Currently, the only valid value for pid is 0, which returns the name of the cpuset to which the current process is attached.

The function returns a pointer to a structure of type `cpuset_NameList_t` (defined in the `cpuset.h` include file). The `cpusetGetName` function allocates the memory for the structure and all of its associated data. The user is responsible for freeing the memory using the `cpusetFreeNameList(3x)` function. The `cpuset_NameList_t` structure is defined as follows:

    typedef struct {
                       int    count;
                       char   **list;
                       int   *status;
                   } cpuset_NameList_t;

The `count` member is the number of cpuset names in the list. In the case of `cpusetGetName` function, this member should only contain the values of 0 and 1.

The `list` member references the list of names.

The `status` member is a list of status flags that indicate the status of the corresponding cpuset name in `list`. The following flag values may be used:

`CPUSET_QUEUE_NAME` |  | Indicates that the corresponding name in `list` is the name of a cpuset queue
`CPUSET_CPU_NAME` |  | Indicates that the corresponding name in `list` is the CPU ID for a restricted CPU

The memory for `list` and `status` is allocated when the `cpuset_NameList_t` structure is allocated and it is released when the `cpuset_NameList_t` structure is released.

EXAMPLES

This example obtains the cpuset name or CPU ID to which the current process is attached:

    cpuset_NameList_t *name;

                   /* Get the list of names else print error & exit */
                   if (!(name = cpusetGetName(0))) {
                       perror("cpusetGetName");
                       exit(1);
                   }
                   if (name->count == 0) {
                       printf("Current process not attached\n");
                   } else {
                       if (name->status[0] == CPUSET_CPU_NAME) {
                           printf("Current process attached to"
                                   " CPU_ID[%s]\n",
                                   name->list[0]);
                       } else {
                           printf("Current process attached to"
                                   " CPUSET[%s]\n",
                                   name->list[0]);
                       }
                   }
                   cpusetFreeNameList(name);

NOTES

The `cpusetGetName` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreeNameList(3x)`, `cpusetGetNameList(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetName` function returns a pointer to a `cpuset_NameList_t` structure. If the `cpusetGetName` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` include those values as set by `sysmp(2)`, `sbrk(2)`, and the following:

`EINVAL` |  | Invalid value for pid was supplied. Currently, only 0 is accepted to obtain the cpuset name that the current process is attached to.
`ERANGE` |  | Number of CPUs configured on the system is not a value greater than or equal to 1.

`cpusetGetNameList`(3x)

NAME

`cpusetGetNameList` - gets the list of names for all defined cpusets

SYNOPSIS

    #include <cpuset.h>
    cpuset_NameList_t *cpusetGetNameList(void);

DESCRIPTION

The `cpusetGetNameList` function is used to obtain a list of the names for all the cpusets on the system.

The function returns a pointer to a structure of type `cpuset_NameList_t` (defined in the `cpuset.h` include file). The `cpusetGetNameList` function allocates the memory for the structure and all of its associated data. The user is responsible for freeing the memory using the `cpusetFreeNameList(3x)` function. The `cpuset_NameList_t` structure is defined as follows:

    typedef struct {
                       int    count;
                       char   **list;
                       int   *status;
                   } cpuset_NameList_t;

The `count` member is the number of cpuset names in the list.

The `list` member references the list of names.

The `status` member is a list of status flags that indicate the status of the corresponding cpuset name in `list`. The following flag values may be used:

`CPUSET_QUEUE_NAME` |  | Indicates that the corresponding name in `list` is the name of a cpuset queue.
`CPUSET_CPU_NAME` |  | Indicates that the corresponding name in `list` is the CPU ID for a restricted CPU.

The memory for `list` and`status` is allocated when the `cpuset_NameList_t` structure is allocated and it is released when the c`puset_NameList_t` structure is released.

EXAMPLES

This example obtains the list of names for all cpuset queues configured on the system. The list of cpusets or restricted CPU IDs is then printed.

                   cpuset_NameList_t *names;

                   /* Get the list of names else print error & exit */
                   if (!(names = cpusetGetNameList())) {
                       perror("cpusetGetNameList");
                       exit(1);
                   }
                   if (names->count == 0) {
                       printf("No defined CPUSETs or restricted CPUs\n");
                   } else {
                       int i;

                       printf("CPUSET and restricted CPU names:\n");
                       for (i = 0; i < names->count; i++) {
                           if (names->status[i] == CPUSET_CPU_NAME) {
                               printf("CPU_ID[%s]\n", names->list[i]);
                           } else {
                               printf("CPUSET[%s]\n", names->list[i]);
                           }
                       }
                   }
                   cpusetFreeNameList(names);

NOTES

The `cpusetGetNameList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreeNameList(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetNameList` function returns a pointer to a `cpuset_NameList_t` structure. If the `cpusetGetNameList` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` include those values set by `sysmp(2)` and `sbrk(2)`.

`cpusetGetPIDList`(3x)

NAME

`cpusetGetPIDList` - gets a list of all PIDs attached to a cpuset

SYNOPSIS

    #include <cpuset.h>
    cpuset_PIDList_t *cpusetGetPIDList(char *qname);

DESCRIPTION

The `cpusetGetPIDList` function is used to obtain a list of the PIDs for all processes currently attached to the specified cpuset. Only processes with a user ID or group ID that has read permissions on the permissions file can successfully execute this function.

The `qname` argument is the name of the cpuset to which the current process should be attached.

The function returns a pointer to a structure of type `cpuset_PIDList_t` (defined in the `cpuset.h`) include file. The `cpusetGetPIDList` function allocates the memory for the structure and the user is responsible for freeing the memory using the `cpusetFreePIDList(3x)` function. The `cpuset_PIDList_t` structure looks similar to this:

    typedef struct {
                       int    count;
                       pid_t  *list;
                   } cpuset_PIDList_t;

The `count` member is the number of PID values in the `list`. The `list` member references the memory array that hold the list of PID values. The memory for `list` is allocated when the `cpuset_PIDList_t` structure is allocated and it is released when the `cpuset_PIDList_t` structure is released.

EXAMPLES

This example obtains the list of PIDs attached to the cpuset `mpi_set` and prints out the PID values.

    (char             *qname = "mpi_set";)
    cpuset_PIDList_t *pids;

                   /* Get the list of PIDs else print error & exit */
                   if (!(pids = cpusetGetPIDList(qname))) {
                       perror("cpusetGetPIDList");
                       exit(1);
                   }
                   if (pids->count == 0) {
                       printf("CPUSET[%s] has 0 processes attached\n",
                               qname);
                   } else {
                       int i;
                       printf("CPUSET[%s] attached PIDs:\n",
                                qname);
                       for (i=o; i<pids->count; i++)
                                printf("PID[%d]\n", pids->list[i] );
                   }
                   cpusetFreePIDList(pids);

NOTES

The `cpusetGetPIDList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreePIDList(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetPIDList` function returns a pointer to a `cpuset_PIDList_t` structure. If the `cpusetGetPIDList` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` are the same as the values set by `sysmp(2)` and `sbrk(2)`.

`cpusetGetProperties`(3x)

NAME

`cpusetGetProperties` - retrieves various properties associated with a cpuset

SYNOPSIS

    #include <cpuset.h>
    cpuset_Properties_t * cpusetGetProperties(char *qname);

DESCRIPTION

The `cpusetGetProperties` function is used retrieve various properties identified by `qname` and returns a pointer to a `cpuset_Properties_t` structure. Every cpuset queue has a file that defines access permissions to the queue. The read permissions for that file will determine if a process owned by a specific user can retrieve the properties from the cpuset.

The `qname` argument is the name of the cpuset to which the properties should be retrieved.

EXAMPLES

This example retrieves the properties of a cpuset queue named `mpi_set`.

    char *qname = "mpi_set";
                       cpuset_Properties_t             *csp;

                       /* Get properties, if error - print error & exit */
                       csp=cpusetGetProperties(qname);
                       if (!csp) {
                               perror("cpusetGetProperties");
                               exit(1);
                       }
                       .
                       .
                       .
                       cpusetFreeProperties(csp);

Once a valid pointer is returned, a check against the `extFlags` member of the `cpuset_Properties_t` structure must be made with the flags `CPUSET_ACCESS_ACL`,`CPUSET_DEFAULT_ACL`, and `CPUSET_MAC_LABEL` to see if any valid ACLs or a valid MAC label was returned. The check flags can be found in the `<sys\cpuset.h>` file.

NOTES

The `cpusetGetProperties` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreeProperties(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetGetProperties` function returns a pointer to a `cpuset_Properties_t` structure. If the `cpusetGetProperties` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` include those values set by `sysmp(2)`.

`cpusetAllocQueueDef`(3x)

NAME

`cpusetAllocQueueDef` - allocates a `cpuset_QueueDef_t` structure

SYNOPSIS

    #include <cpuset.h>
    cpuset_QueueDef_t *cpusetAllocQueueDef(int count)

DESCRIPTION

The `cpusetAllocQueueDef` function is used to allocate memory for a `cpuset_QueueDef_t` structure. This memory can then be released using the `cpusetFreeQueueDef(3x)` function.

The `count` argument indicates the number of CPUs that will be assigned to the cpuset definition structure. The `cpuset_QueueDef_t` structure is defined as follows:

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

The `flags` member is used to specify various control options for the cpuset queue. It is formed by applying the bitwise exclusive-OR operator to zero or more of the following values:

`CPUSET_CPU_EXCLUSIVE` | Defines a cpuset to be restricted. Only threads attached to the cpuset queue (descendents of an attached thread inherit the attachement) may execute on the CPUs contained in the cpuset.
`CPUSET_MEMORY_LOCAL` | 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.
`CPUSET_MEMORY_EXCLUSIVE` | 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. 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 running, 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 nonlocal.
`CPUSET_MEMORY_KERNEL_AVOID` | The kernel should attempt to avoid allocating memory from nodes contained in this cpuset. If kernel memory requests cannot be satisfied from outside this cpuset, this option will be ignored and allocations will occur from within the cpuset. (This avoidance currently extends only to keeping buffer cache away from the protected nodes.)
`CPUSET_MEMORY_MANDATORY` | The kernel will limit all memory allocations to nodes that are contained in this cpuset. If memory requests cannot be satisfied, the allocating process will sleep until memory is available. The process will be killed if no more memory can be allocated. See policies below.
`CPUSET_POLICY_PAGE` | 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.
`CPUSET_POLICY_KILL` | 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 contained 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 the `permfile` allows a user to retrieve information about a 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` structure. The memory for the `cpuset_CPUList_t` structure is allocated and released when the `cpuset_QueueDef_t` structure is allocated and released (see `cpusetFreeQueueDef(3x)`). The `cpuset_CPUList_t` structure contains the list of CPUs assigned to the cpuset. The `cpuset_CPUList_t` structure (defind in the `cpuset.h` include file) 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 the 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. The size of the list is determined by the `count` argument passed into the function `cpusetAllocQueueDef`.

EXAMPLES

This example creates a cpuset queue using the `cpusetCreate(3x)` function and provides an example of how the `cpusetAllocQueueDef` function might be used. The cpuset created will have access controlled by the file `/usr/tmp/mypermfile`; it will contain CPU IDs 4, 8, and 12; and it will be 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");
                       exit(1);
                   }
                   cpusetFreeQueueDef(qdef);

NOTES

The `cpusetAllocQueueDef` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetFreeQueueDef(3x)`, and `cpuset(5)`.

DIAGNOSTICS

If successful, the `cpusetAllocQueueDef` function returns a pointer to a `cpuset_QueueDef_t` structure. If the `cpusetAllocQueueDef` function fails, it returns NULL and `errno` is set to indicate the error. The possible values for `errno` values include those returned by `sbrk(2)` and the following:

`EINVAL` |  | Invalid argument was supplied. The user must supply a value greater than or equal to 0.

### Clean-up Functions

This section contains the man pages for Cpuset System library clean-up functions:

`cpusetFreeQueueDef(3x)` | Releases memory used by a `cpuset_QueueDef_t` structure
`cpusetFreeCPUList(3x)` | Releases memory used by a `cpuset_CPUList_t` structure
`cpusetFreeNameList(3x)` | Releases memory used by a `cpuset_NameList_t` structure
`cpusetFreePIDList(3x)` | Releases memory used by a `cpuset_PIDList_t` structure
`cpusetFreeProperties(3x)` | Release memory used by a `cpuset_Properties_t` structure

`cpusetFreeQueueDef`(3x)

NAME

`cpusetFreeQueueDef` - releases memory used by a `cpuset_QueueDef_t` structure

SYNOPSIS

    #include <cpuset.h>
    void cpusetFreeQueueDef(cpuset_QueueDef_t *qdef);

DESCRIPTION

The `cpusetFreeQueueDef` function is used to release memory used by a `cpuset_QueueDef_t` structure. This function releases all memory associated with the `cpuset_QueueDef_t` structure.

The `qdef` argument is the pointer to the `cpuset_QueueDef_t` structure that will have its memory released.

This function should be used to release the memory allocated during a previous call to the `cpusetAllocQueueDef(3x)`) function.

NOTES

The `cpusetFreeQueueDef` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetAllocQueueDef(3x)`, and `cpuset(5)`.

`cpusetFreeCPUList`(3x)

NAME

`cpusetFreeCPUList` - releases memory used by a `cpuset_CPUList_t` structure

SYNOPSIS

    #include <cpuset.h>
    void cpusetFreeCPUList(cpuset_CPUList_t *cpu);

DESCRIPTION

The `cpusetFreeCPUList` function is used to release memory used by a `cpuset_CPUList_t` structure. This function releases all memory associated with the `cpuset_CPUList_t` structure.

The `cpu` argument is the pointer to the `cpuset_CPUList_t` structure that will have its memory released.

This function should be used to release the memory allocated during a previous call to the `cpusetGetCPUList(3x)` function.

NOTES

The `cpusetFreeCPUList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetGetCPUList(3x)`, and `cpuset(5)`.

`cpusetFreeNameList`(3x)

NAME

`cpusetFreeNameList` - releases memory used by a `cpuset_NameList_t` structure

SYNOPSIS

    #include <cpuset.h>
    void cpusetFreeNameList(cpuset_NameList_t *name);

DESCRIPTION

The `cpusetFreeNameList` function is used to release memory used by a `cpuset_NameList_t` structure. This function releases all memory associated with the `cpuset_NameList_t` structure.

The `name` argument is the pointer to the `cpuset_NameList_t` structure that will have its memory released.

This function should be used to release the memory allocated during a previous call to the `cpusetGetNameList(3x)` function or `cpusetGetName(3x)` function.

NOTES

The `cpusetFreeNameList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetGetName(3x)`, `cpusetGetNameList(3x)`, and `cpuset(5)`.

`cpusetFreePIDList`(3x)

NAME

`cpusetFreePIDList` - releases memory used by a `cpuset_PIDList_t` structure

SYNOPSIS

    #include <cpuset.h>
    void cpusetFreePIDList(cpuset_PIDList_t *pid);

DESCRIPTION

The `cpusetFreePIDList` function is used to release memory used by a `cpuset_PIDList_t` structure. This function releases all memory associated with the `cpuset_PIDList_t` structure.

The `pid` argument is the pointer to the `cpuset_PIDList_t` structure that will have its memory released.

This function should be used to release the memory allocated during a previous call to the `cpusetGetPIDList(3x)` function.

NOTES

The `cpusetFreePIDList` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetGetPIDList(3x)`, and `cpuset(5)`.

`cpusetFreeProperties`(3x)

NAME

`cpusetFreeProperties` - releases memory used by a `cpuset_Properties_t` structure

SYNOPSIS

    #include <cpuset.h>
    void cpusetFreeProperties(cpuset_Properties_t *csp);

DESCRIPTION

The `cpusetFreeProperties` function is used to release memory used by a `cpuset_Properties_t` structure. This function releases all memory associated with the `cpuset_Properties_t` structure.

The `csp` argument is the pointer to the `cpuset_Properties_t` structure that will have its memory released.

This function should be used to release the memory allocated during a previous call to the `cpusetGetProperties(3x)`) function.

NOTES

The `cpusetFreeProperties` function is found in the `libcpuset.so` library and is loaded if the `-lcpuset` option is used with either the `cc(1)` or `ld(1)` commands.

SEE ALSO

`cpuset(1)`, `cpusetGetProperties(3x)`, and `cpuset(5)`.

### Using the Cpuset Library

This section provides an example of how to use the Cpuset library functions to create a cpuset and an example of creating a replacement library for `/lib32/libcpuset.so`.

Example A-1. Example of Creating a Cpuset

This example creates a cpuset named `myqueue` containing CPUs 4, 8, and 12. The example uses the interfaces in the cpuset library, `/lib32/libcpuset.so`, if they are present. If the interfaces are not present, it attempts to use the `cpuset(1)` command to create the cpuset.

    #include <cpuset.h>
    #include <stdio.h>
    #include <errno.h>

    #define PERMFILE "/usr/tmp/permfile"

    int
    main(int argc, char **argv)
    {
        cpuset_QueueDef_t *qdef;
        char              *qname = "myqueue";
        FILE              *fp;

        /* Alloc queue def for 3 CPU IDs */
        if (_MIPS_SYMBOL_PRESENT(cpusetAllocQueueDef)) {
            printf("Creating cpuset definition\n");
            qdef = cpusetAllocQueueDef(3);
            if (!qdef) {
                perror("cpusetAllocQueueDef");
                exit(1);
        }
            /* Define attributes of the cpuset */
            qdef->flags = CPUSET_CPU_EXCLUSIVE
                        | CPUSET_MEMORY_LOCAL
                        | CPUSET_MEMORY_EXCLUSIVE;
            qdef->permfile = PERMFILE;
            qdef->cpu->count = 3;
            qdef->cpu->list[0] = 4;
            qdef->cpu->list[1] = 8;
            qdef->cpu->list[2] = 12;
        } else {
            printf("Writing cpuset command config"
                    " info into %s\n", PERMFILE);
            fp = fopen(PERMFILE, "a");
            if (!fp) {
                perror("fopen");
                exit(1);
            }
            fprintf(fp, "EXCLUSIVE\n");
            fprintf(fp, "MEMORY_LOCAL\n");
            fprintf(fp, "MEMORY_EXCLUSIVE\n\n");
            fprintf(fp, "CPU 4\n");
            fprintf(fp, "CPU 8\n");
            fprintf(fp, "CPU 12\n");
            fclose(fp);
        }

        /* Request that the cpuset be created */
        if (_MIPS_SYMBOL_PRESENT(cpusetCreate)) {
            printf("Creating cpuset = %s\n", qname);
            if (!cpusetCreate(qname, qdef)) {
                perror("cpusetCreate");
                exit(1);
            }
        } else {
            char command[256];

            fprintf(command, "/usr/sbin/cpuset -q %s -c"
                   "-f %s", qname,
                   [PERMFILE];
            if (system(command) < 0) {
                perror("system");
                exit(1);
            }
        }

        /* Free memory for queue def */
        if (_MIPS_SYMBOL_PRESENT(cpusetFreeQueueDef)) {
            printf("Finished with cpuset definition,"
                    " releasing memory\n");
            cpusetFreeQueueDef(qdef);
            }
            return 0;
        }

Example A-2. Example of Creating a Replacement Library

This example shows how to create a replacement library for `/lib32/libcpuset.so` so that a program built to use the cpuset library interfaces will execute if the library is not present.

1. Create the `replace.c` file that contains the following line of code:

       static void cpusetNULL(void) { }

2. Compile the `replace.c` file:

       cc -mips3 -n32 -c replace.c

3. Place the `replace.o` object created in the previous step in a library:

       ar ccrl libcpuset.a replace.o

4. Convert the library into a DSO:

       ld -mips3 -n32 -quickstart_info -nostdlib        \
          -elf -shared -all -soname libcpuset.so       \
          -no_unresolved -quickstart_info -set_version \
          sgi1.0 libcpuset.a -o libcpuset.so

5. Install the DSO on the system:

       install -F /opt/lib32 -m 444 -src libcpuset.so \
                            libcpuset.so

The replacement library can be installed in a directory defined by the `LD_LIBRARYN32_PATH` environment variable (see `rld(1)`). If the replacement library must be installed in a directory that is in the default search path for shared libraries, it should be installed in `/opt/lib32`.

Prev | Table of Contents | Next
Chapter 7. Array Services |  | Index