cpuset

cpuset(3)                  Concurrent RedHawk Linux                  cpuset(3)



NAME
       cpuset - manipulate sets of CPUs portably


SYNOPSIS
       #include <cpuset.h>

       cpuset_t* cpuset_alloc(void)
       void cpuset_free(cpuset_t* setp)
       void cpuset_init(cpuset_t* setp)
       void cpuset_copy(cpuset_t* dest, cpuset_t* src)
       int cpuset_get_cpu(cpuset_t* setp,  cpu_t  cpu)
       void cpuset_set_cpu(cpuset_t*, cpu_t cpu, int state)
       void cpuset_negate(cpuset_t* setp)
       int cpuset_is_empty(cpuset_t* setp)
       int cpuset_is_full(cpuset_t* setp)
       int cpuset_is_valid_cpu(cpu_t cpu)
       char* cpuset_get_string(cpuset_t* setp)
       void cpuset_set_string(cpuset_t* setp, char* hexstr)
       void cpuset_count(cpuset_t* setp)
       cpuset* cpuset_and(arg1, arg2)
       cpuset* cpuset_or(arg1, arg2)
       cpuset* cpuset_xor(arg1, arg2)
       void cpuset_and_eq(arg1, arg2)
       void cpuset_or_eq(arg1, arg2)
       void cpuset_xor_eq(arg1, arg2)

       gcc [options...] file -lmpadvise ...


DESCRIPTION
       These functions allow sets of CPUs to be manipulated portably as
       follows:


       cpuset_alloc()
            Dynamically create a CPU set object.

       cpuset_free()
            Dynamically destroy a previously allocated CPU set object.

       cpuset_init()
            Initialize a CPU set object to the empty set.

       cpuset_copy()
            Copy the contents of one CPU set object to another.

       cpuset_get_cpu()
            Get the state of an individual CPU in a CPU set.

       cpuset_set_cpu()
            Set or clear individual CPUs within the CPU set using a state of 1
            or 0 respectively.

       cpuset_negate()
            Negate the CPU set.  This inverts the state of each CPU in the CPU
            set.

       cpuset_is_empty()
            Compare the CPU set to the empty set.

       cpuset_is_full()
            Compare the CPU set to the complete set.

       cpuset_is_valid()
            Test a logical CPU identifier to see if it is supported by the
            current CPU set implementation.

            A successful test does not imply that the current system supports
            the CPU, only that it is within the limits imposed by the current
            CPU set implementation.

       cpuset_get_string()
            Obtain a human readable hexadecimal mask string representing the
            specified object's CPU set.

       cpuset_set_string()
            Set a CPU object to correspond to a specified hexadecimal mask
            string.  The length of the string is implementation defined and
            should not be assumed to be fixed (use of strlen() is
            recommended).

       cpuset_count()
            Returns the count of the number of CPUs that are currently set in
            the specified CPU set.

       cpuset_and()
            Performs a bitwise AND operation on arg1 and arg2.  This function
            allocates a new cpuset_t to store the results, and returns a
            pointer to the newly allocated cpuset_t.  You must call
            cpuset_free() on the returned cpuset_t when the results are no
            longer needed.

       cpuset_or()
            Performs a bitwise OR operation on arg1 and arg2.  This function
            allocates a new cpuset_t to store the results, and returns a
            pointer to the newly allocated cpuset_t.  You must call
            cpuset_free() on the returned cpuset_t when the results are no
            longer needed.

       cpuset_xor()
            Performs a bitwise XOR operation on arg1 and arg2.  This function
            allocates a new cpuset_t to store the results, and returns a
            pointer to the newly allocated cpuset_t.  You must call
            cpuset_free() on the returned cpuset_t when the results are no
            longer needed.

       cpuset_and_eq()
            Performs a bitwise AND operation on arg1 and arg2 and stores the
            results in arg1.  No new cpuset_t objects are allocated by the
            function.

       cpuset_or_eq()
            Performs a bitwise OR operation on arg1 and arg2 and stores the
            results in arg1.  No new cpuset_t objects are allocated by the
            function.

       cpuset_xor_eq()
            Performs a bitwise XOR operation on arg1 and arg2 and stores the
            results in arg1.  No new cpuset_t objects are allocated by the
            function.


OPTIONS
       setp   Pointer to a cpuset_t object.


       cpu    Logical CPU identifier starting with zero.


       state  A boolean value indicating whether the specified CPU is present
              in the set or not.


       hexstr A null-terminated string of continuous hexadecimal characters
              that specify a mask which can be directly mapped to a CPU set.


       arg1   A CPU set supplied as an argument.  When using cpuset_and_eq(),
              cpuset_or_eq(), or cpuset_xor_eq(), this value also stores the
              results of the function.


       arg2   A CPU set supplied as an argument.




RETURN VALUE
       Functions that return boolean values return 1 for TRUE and 0 for FALSE.


ERRORS
       cpuset_alloc() returns NULL if space could not be allocated for the
       cpuset_t object.  All other functions cannot fail.


EXAMPLES
       Allocate a CPU set object:

          cpuset_t* setp;
          setp = cpuset_alloc();

       Free a CPU set object:

          cpuset_free(setp);

       Initialize a CPU set object to the empty set:

          cpuset_init(setp);

       Test a CPU set object to see if it is the empty set:

          if (cpuset_is_empty(setp)) {
             /* empty */
          } else {
             /* not empty */
          }

       Initialize a CPU set object to the value corresponding to a mask string
       of hexadecimal characters:

          cpuset_set_string(setp, "ffff");


CAVEATS
       Although the cpuset_t typedef is available to the C programmer, it is
       cpuset implementation dependent and instances of the object should not
       be created directly.  Instead, use the cpuset_alloc() and cpuset_free()
       functions.


COPYRIGHT
       Copyright (C) 2002  Concurrent Computer Corporation This source code is
       licensed under the GNU GPL Version 2.  Author: Jason Baietto
       (jason.baietto@ccur.com)



                                 December 2002                       cpuset(3)