| .\" 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, |
| .\" version 2, as published by the Free Software Foundation. |
| .\" |
| .\" 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 program; if not, write to the Free Software Foundation, Inc., |
| .\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
| .\" |
| .TH TASKSET 1 "August 2014" "util-linux" "User Commands" |
| .SH NAME |
| taskset \- set or retrieve a process's CPU affinity |
| .SH SYNOPSIS |
| .B taskset |
| [options] |
| .IR mask\ command\ [ argument ...] |
| .br |
| .B taskset |
| [options] |
| .B \-p |
| .RI [ mask ]\ pid |
| .SH DESCRIPTION |
| .PP |
| .B taskset |
| is used to set or retrieve the CPU affinity of a running process given its |
| \fIpid\fR, or to launch a new \fIcommand\fR 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 may be specified in hexadecimal (with or without |
| a leading "0x"), or as a CPU list with the |
| .BR \-\-cpu\-list |
| option. For example, |
| .RS 4 |
| .TP 12 |
| .BR 0x00000001 |
| is processor #0, |
| .TP |
| .BR 0x00000003 |
| is processors #0 and #1, |
| .TP |
| .BR 0xFFFFFFFF |
| is processors #0 through #31, |
| .TP |
| .BR 32 |
| is processors #1, #4, and #5, |
| .TP |
| .BR \-\-cpu\-list\ 0-2,6 |
| is processors #0, #1, #2, and #6. |
| .RE |
| .PP |
| When |
| .BR taskset |
| returns, it is guaranteed that the given program has been scheduled to a legal |
| CPU. |
| .SH OPTIONS |
| .TP |
| .BR \-a ,\ \-\-all\-tasks |
| Set or retrieve the CPU affinity of all the tasks (threads) for a given PID. |
| .TP |
| .BR \-c ,\ \-\-cpu\-list |
| Interpret \fImask\fR as numerical list of processors instead of a bitmask. |
| Numbers are separated by commas and may include ranges. For example: |
| .BR 0,5,8-11 . |
| .TP |
| .BR \-p ,\ \-\-pid |
| Operate on an existing PID and do not launch a new task. |
| .TP |
| .BR \-V ,\ \-\-version |
| Display version information and exit. |
| .TP |
| .BR \-h ,\ \-\-help |
| Display help text 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 can change the CPU affinity of a process belonging to the same user. |
| A user must possess |
| .B CAP_SYS_NICE |
| to change the CPU affinity of a process belonging to another user. |
| A user can retrieve the affinity mask of any process. |
| .SH SEE ALSO |
| .BR chrt (1), |
| .BR nice (1), |
| .BR renice (1), |
| .BR sched_getaffinity (2), |
| .BR sched_setaffinity (2) |
| .sp |
| See |
| .BR sched (7) |
| for a description of the Linux scheduling scheme. |
| .SH AUTHOR |
| Written by Robert M. Love. |
| .SH COPYRIGHT |
| Copyright \(co 2004 Robert M. Love. |
| 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 AVAILABILITY |
| The taskset command is part of the util-linux package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux/. |
