cpuset (2)

Leading comments

Copyright (c) 2008 Christian Brueffer
Copyright (c) 2008 Jeffrey Roberson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following discl...

(The comments found at the beginning of the groff file "man2/cpuset.2freebsd".)

NAME

cpuset cpuset_getid cpuset_setid - manage CPU affinity sets

LIBRARY

Lb libc

SYNOPSIS

In sys/param.h In sys/cpuset.h Ft int Fn cpuset cpusetid_t *setid Ft int Fn cpuset_setid cpuwhich_t which id_t id cpusetid_t setid Ft int Fn cpuset_getid cpulevel_t level cpuwhich_t which id_t id cpusetid_t *setid

DESCRIPTION

The family of system calls allow applications to control sets of processors and assign processes and threads to these sets. Processor sets contain lists of CPUs that members may run on and exist only as long as some process is a member of the set. All processes in the system have an assigned set. The default set for all processes in the system is the set numbered 1. Threads belong to the same set as the process which contains them, however, they may further restrict their set with the anonymous per-thread mask.

Sets are referenced by a number of type Ft cpuset_id_t . Each thread has a root set, an assigned set, and an anonymous mask. Only the root and assigned sets are numbered. The root set is the set of all CPUs available in the system or in the system partition the thread is running in. The assigned set is a subset of the root set and is administratively assignable on a per-process basis. Many processes and threads may be members of a numbered set.

The anonymous set is a further thread-specific refinement on the assigned set. It is intended that administrators will manipulate numbered sets using cpuset(1) while application developers will manipulate anonymous sets using cpuset_setaffinity2.

To select the correct set a value of type Ft cpulevel_t is used. The following values for Fa level are supported:

CPU_LEVEL_ROOT Ta Root set

CPU_LEVEL_CPUSET Ta Assigned set

CPU_LEVEL_WHICH Ta Set specified by which argument

The Fa which argument determines how the value of Fa id is interpreted and is of type Ft cpuwhich_t . The Fa which argument may have the following values:

CPU_WHICH_TID Ta id is lwpid_t (thread id)

CPU_WHICH_PID Ta id is pid_t (process id)

CPU_WHICH_CPUSET Ta id is a cpusetid_t (cpuset id)

CPU_WHICH_IRQ Ta id is an irq number

An Fa id of '-1' may be used with a Fa which of CPU_WHICH_TID CPU_WHICH_PID or CPU_WHICH_CPUSET to mean the current thread, process, or current thread's cpuset. All cpuset syscalls allow this usage.

A Fa level argument of CPU_LEVEL_WHICH combined with a Fa which argument other than CPU_WHICH_CPUSET refers to the anonymous mask of the object. This mask does not have an id and may only be manipulated with cpuset_setaffinity2.

Fn cpuset creates a new set containing the same CPUs as the root set of the current process and stores its id in the space provided by Fa setid . On successful completion the calling process joins the set and is the only member. Children inherit this set after a call to fork(2).

Fn cpuset_setid attempts to set the id of the object specified by the Fa which argument. Currently CPU_WHICH_PID is the only acceptable value for which as threads do not have an id distinct from their process and the API does not permit changing the id of an existing set. Upon successful completion all of the threads in the target process will be running on CPUs permitted by the set.

Fn cpuset_getid retrieves a set id from the object indicated by Fa which and stores it in the space pointed to by Fa setid . The retrieved id may be that of either the root or assigned set depending on the value of Fa level . Fa level should be CPU_LEVEL_CPUSET or CPU_LEVEL_ROOT to get the set id from the process or thread specified by the Fa id argument. Specifying CPU_LEVEL_WHICH with a process or thread is unsupported since this references the unnumbered anonymous mask.

The actual contents of the sets may be retrieved or manipulated using cpuset_getaffinity2 and cpuset_setaffinity2. See those manual pages for more detail.

RETURN VALUES

Rv -std

ERRORS

The following error codes may be set in errno

Bq Er EINVAL

The Fa which or Fa level argument was not a valid value.

Bq Er EDEADLK

The Fn cpuset_setid call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask.

Bq Er EFAULT

The setid pointer passed to Fn cpuset_getid or Fn cpuset was invalid.

Bq Er ESRCH

The object specified by the Fa id and Fa which arguments could not be found.

Bq Er EPERM

The calling process did not have the credentials required to complete the operation.

Bq Er ENFILE

There was no free Ft cpusetid_t for allocation.

SEE ALSO

cpuset(1), cpuset_getaffinity2, cpuset_setaffinity2, pthread_affinity_np3, pthread_attr_affinity_np3

HISTORY

The family of system calls first appeared in Fx 7.1 .

AUTHOR

An Jeffrey Roberson Aq jeff@FreeBSD.org