| .\" taskset(1) manpage |
| .\" |
| .\" Copyright (C) 2004 Robert Love |
| .\" |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, write to the Free |
| .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, |
| .\" USA. |
| .\" |
| .\" 2002-05-11 Robert Love <rml@tech9.net> |
| .\" Initial version |
| .\" |
| .TH TASKSET "1" "Apr 2003" "schedutils" "Linux User's Manual" |
| .SH NAME |
| taskset \- retrieve or set a process's CPU affinity |
| .SH SYNOPSIS |
| .B taskset |
| .RI [ options ]\ mask |
| .IR command\ [ arg ]... |
| .br |
| .B taskset |
| .RI [ options ] |
| .B \-p |
| .RI [ mask ]\ pid |
| .SH DESCRIPTION |
| .PP |
| .BR taskset |
| is used to set or retrieve the CPU affinity of a running process given its PID |
| or to launch a new COMMAND with a given CPU affinity. CPU affinity is a |
| scheduler property that "bonds" a process to a given set of CPUs on the system. |
| The Linux scheduler will honor the given CPU affinity and the process will not |
| run on any other CPUs. Note that the Linux scheduler also supports natural |
| CPU affinity: the scheduler attempts to keep processes on the same CPU as long |
| as practical for performance reasons. Therefore, forcing a specific CPU |
| affinity is useful only in certain applications. |
| .sp |
| The CPU affinity is represented as a bitmask, with the lowest order bit |
| corresponding to the first logical CPU and the highest order bit corresponding |
| to the last logical CPU. Not all CPUs may exist on a given system but a mask |
| may specify more CPUs than are present. A retrieved mask will reflect only the |
| bits that correspond to CPUs physically on the system. If an invalid mask is |
| given (i.e., one that corresponds to no valid CPUs on the current system) an |
| error is returned. The masks are typically given in hexadecimal. For example, |
| .TP |
| .BR 0x00000001 |
| is processor #0 |
| .TP |
| .BR 0x00000003 |
| is processors #0 and #1 |
| .TP |
| .BR 0xFFFFFFFF |
| is all processors (#0 through #31) |
| .PP |
| When |
| .BR taskset |
| returns, it is guaranteed that the given program has been scheduled to a legal |
| CPU. |
| .SH OPTIONS |
| .TP |
| .BR \-p ,\ \-\-pid |
| operate on an existing PID and not launch a new task |
| .TP |
| .BR \-c ,\ \-\-cpu-list |
| specify a numerical list of processors instead of a bitmask. The list may |
| contain multiple items, separated by comma, and ranges. For example, |
| .BR 0,5,7,9-11 . |
| .TP |
| .BR \-h ,\ \-\-help |
| display usage information and exit |
| .TP |
| .BR \-V ,\ \-\-version |
| output version information and exit |
| .SH USAGE |
| .TP |
| The default behavior is to run a new command with a given affinity mask: |
| .B taskset |
| .I mask |
| .IR command\ [ arguments ] |
| .TP |
| You can also retrieve the CPU affinity of an existing task: |
| .B taskset \-p |
| .I pid |
| .TP |
| Or set it: |
| .B taskset \-p |
| .I mask pid |
| .SH PERMISSIONS |
| A user must possess |
| .B CAP_SYS_NICE |
| to change the CPU affinity of a process. Any user can retrieve the affinity |
| mask. |
| .SH AUTHOR |
| Written by Robert M. Love. |
| .SH COPYRIGHT |
| Copyright \(co 2004 Robert M. Love |
| .br |
| This is free software; see the source for copying conditions. There is NO |
| warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| .SH "SEE ALSO" |
| .BR chrt (1), |
| .BR nice (1), |
| .BR renice (1), |
| .BR sched_setaffinity (2), |
| .BR sched_getaffinity (2) |
| .sp |
| See |
| .BR sched_setscheduler (2) |
| for a description of the Linux scheduling scheme. |
| .SH AVAILABILITY |
| The taskset command is part of the util-linux-ng package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/. |