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.

---

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.

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

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

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

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

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

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

#include <sys/resource.h>

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

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

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

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

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;

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

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;

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:

#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

#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

#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

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

#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

#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

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

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:

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:

cpusetAttach(3x)

NAME

cpusetAttach - attaches the current process to a cpuset

SYNOPSIS

#include <cpuset.h>
     int cpusetDetachAll(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 to 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 attach a process to 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 to 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 to a cpuset queue named mpi_set.

char *qname = "mpi_set";

               /* Attach to 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).

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

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:

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);

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:

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:

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:

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 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:

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:

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

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 it's 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).

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.

#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;
    }