mpadvise(3) - Linux man page

Name

mpadvise - multiprocessor control

Synopsis

#include <mpadvise.h>

int mpadvise (int cmd, int which, int who, cpuset_t *setp)

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

Description

mpadvise performs a variety of multiprocessor functions.

CPUs are identified by specifying pointers to the cpuset_t object, which specifies a set of one or more CPUs. For more information on CPU sets, see the cpuset(3) man page.

Informational Commands

The following commands get or set information about the CPUs in the system. The which and who parameters are ignored.

MPA_CPU_PRESENT: Returns a mask indicating which CPUs are physically present in the system. CPUs brought down with the cpu(1) command (i386 only) are still included.
MPA_CPU_ACTIVE: Returns a mask indicating which CPUs are active - that is, initialized and accepting work, regardless of how many exist in the backplane. If a CPU has been brought down using the cpu(1) command (i386 only), it is not included.
MPA_CPU_BOOT: Returns a mask indicating the CPU that booted the system. The boot processor has some responsibilities not shared with the other CPUs.
Each process or thread has a CPU bias (affinity) restricting its use of processors. A process or thread may not run on a CPU not present in its affinity, and if more than one CPU is specified, the kernel is free to migrate the process or thread based on load and other considerations. Each process and thread inherits its CPU affinity from its parent after a fork(2) or clone(2), but may change it.
All general processes are a descendent from init(8). init is initially given a mask that includes all the processors in the system, but this can be changed via a run(1) command at the end of the /etc/rc.sysinit script or a shield(1) command at run time. See the RedHawk Linux User's Guide for details.

Control Commands

The following commands provide control over the use of CPUs by a process, a thread, a process group, or a user.

MPA_PRC_GETBIAS: Returns the exact unique bias for the specified thread (MPA_TID) or the sum of all CPU affinities of all threads that make up the process (MPA_PID).
MPA_PRC_SETBIAS: Sets the unique CPU affinity for the specified thread (MPA_TID) or the CPU affinity of all threads in the process (MPA_PID) to the specified cpuset. To change the CPU affinity of a process or thread, the real or effective user ID must match the real or the saved (from exec(2)) user ID of the process, unless the current user has the CAP_SYS_NICE capability.
MPA_PRC_GETRUN: Returns a CPU set with exactly one CPU in it that corresponds to the CPU where the specified thread is currently running (or waiting to run) (MPA_TID). When MPA_PID is specified, it returns one CPU for non-threaded programs and the set of CPUs in use by all threads of a multi-threaded program. Note that it is possible that the CPU assignment may have already changed by the time the value is returned.

Using Which And Who

which Used to specify the selection criteria. Can be one of the following:

MPA_PID
a specific process and all its threads
MPA_TID
a specific thread
MPA_PGID
a process group
MPA_UID
a user
MPA_LWPID
same as MPA_TID. For compatibility with Concurrent's PowerMAX OS.
who

Interpreted relative to which:

a process identifier
a thread identifier
a process group identifier
user identifier

A who value of 0 causes the process identifier, thread identifier, process group identifier, or user identifier of the caller to be used.

Using MPA_PID with a reference to a single subordinate (non-primordial) thread applies to the containing process as it does when a primordial thread id is supplied.

Return Values

Returns the number of CPUs contained in the specified CPU set. Otherwise, MPA_FAILURE is returned and errno is set to indicate the error.

Errors

EINVAL
The which or cmd was not one of the values documented above.
The CPU mask specified for MPA_PRC_SETBIAS is 0 or contains CPUs that are outside the supported range for the current system.
ESRCH
No processes were located for CPU biasing using the specified which and who parameters.
EACCES
The caller did not have sufficient privilege to do a MPA_PRC_SETBIAS command.
EIO
An error was encountered trying to access the processor file system through the /proc directory.

Notes

mpadvise is designed to be tolerant of simple errors, such as when a specified process group contains one or more processes for which the caller does not have the permissions needed for the requested operation. In such cases, mpadvise successfully completes the allowable requests and silently ignores the others.