NAME    [Toc]    [Back]

       bind_to_cpu, bind_to_cpu_id - Bind execution to a specific
       CPU

SYNOPSIS    [Toc]    [Back]

       #include <sys/types.h> #include <sys/resource.h>  #include
       <sys/processor.h>

       int bind_to_cpu(
               pid_t pid,
               unsigned long cpu_mask,
               unsigned long flag ); int bind_to_cpu_id(
               pid_t pid,
               long cpu_id,
               unsigned long flag );

LIBRARY    [Toc]    [Back]

       Mach Library (libmach.a)

PARAMETERS    [Toc]    [Back]

       Specifies  the  target pid. You must have access rights to
       the pid.  Specifies the CPU on  which  the  thread  should
       run.  The  target CPU is the bit index in the mask. If you
       set more than one bit, an error is generated.  A  cpu_mask
       of  zero clears any previously set CPU binding.  Specifies
       flags  for  the   CPU   binding.   Currently,   only   the
       BIND_NO_INHERIT  flag  is  supported.  When set, this flag
       causes child processes and threads to not inherit the  CPU
       binding.   Specifies  the  CPU  on which the thread should
       run. The target CPU is the number of the CPU.

DESCRIPTION    [Toc]    [Back]

       Upon return from bind_to_cpu()  or  bind_to_cpu_id(),  all
       threads  of  the target pid are running on the target CPU.
       Bound threads are not eligible for execution on any  other
       CPU.  You  release  CPU  binding by invoking bind_to_cpu()
       with a cpu_mask of zero.

RETURN VALUES    [Toc]    [Back]

       Upon    successful    completion,    bind_to_cpu()     and
       bind_to_cpu_id()  both  return  zero.  Upon error, a -1 is
       returned and errno is set to indicate the error.

ERRORS    [Toc]    [Back]

       The operation did not have proper access permissions.  The
       call passed an invalid argument.  The specified process or
       child process ID is invalid or not in use.

EXAMPLES    [Toc]    [Back]

       /*
        * Fork child process and force it to run on cpu number 3.
        *  Processes created by the forked child will not inherit
       bindings.
        */  #include  <sys/resource.h>  #include  <sys/sysinfo.h>
       #include  <sys/signal.h>  #include  <sys/types.h> #include
       <sys/processor.h>

       #define CPU_3   0x8             /* Bit 3 set */

       main() {
          pid_t pid;

          if (pid = fork()) {     /* parent */
             if (bind_to_cpu(pid, CPU_3, BIND_NO_INHERIT)) {
                kill(pid, SIGKILL);
                exit(1); /* bind_to_cpu will print error msg */
             }
             sleep(2);       /*      wait for child to print  CPU
       */
          }
          else {                  /* child */
             long cpu_num;
             sleep(1);        /*      wait for parent to bind CPU
       */
             getsysinfo(GSI_CURRENT_CPU,                &cpu_num,
       sizeof(cpu_num), 0L, 0L, 0L);
             printf("child running on CPU %d\n", cpu_num);
          } }

       In  this  example, the CPU_3 symbol is defined so that bit
       three in the bit mask is set. When the pid  returned  from
       the  fork()  routine  identifies  the  parent routine, the
       bind_to_cpu() routine is called. This  routine  binds  the
       child  process  to  CPU  number three, as specified in the
       CPU_3 symbol. When the pid returned from the  fork()  routine
  identifies  the  child  routine,  the  child routine
       sleeps to give the parent routine  time  to  set  its  CPU
       binding.  Then  it uses the getsysinfo() call to determine
       its CPU and displays its CPU with the printf() routine.

       If  the   return   value   from   the   bind_to_cpu()   or
       bind_to_cpu_id()  routine  indicates  an error, the parent
       process kills the child process and exits  with  an  error
       status.

SEE ALSO    [Toc]    [Back]

       Commands: runon(1)

       Functions: getsysinfo(2)



                                                   bind_to_cpu(3)