Index for Section 3

Alphabetical listing for B

Bottom of page

bind_to_cpu(3)
NAME
  bind_to_cpu, bind_to_cpu_id - Bind execution to a specific CPU

SYNOPSIS
  #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
  Mach Library (libmach.a)

PARAMETERS
  pid Specifies the target pid. You must have access rights to the pid.

  cpu_mask
      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.

  flag
      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.

  cpu_id
      Specifies the CPU on which the thread should run. The target CPU is the
      number of the CPU.

DESCRIPTION
  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
  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
  [EACCES]
	  The operation did not have proper access permissions.

  [EINVAL]
	  The call passed an invalid argument.

  [ESRCH] The specified process or child process ID is invalid or not in use.

EXAMPLES
       /*
	* 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
  Commands: runon(1)

  Functions: getsysinfo(2)

Index for Section 3

Alphabetical listing for B

Top of page