schedutils/taskset.1

   1 .\" taskset(1) manpage
   2 .\"
   3 .\" Copyright (C) 2004 Robert Love
   4 .\"
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, write to the Free
  22 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  23 .\" USA.
  24 .\"
  25 .\" 2002-05-11 Robert Love <rml@tech9.net>
  26 .\"     Initial version
  27 .\"
  28 .TH TASKSET "1" "Apr 2003" "schedutils" "Linux User's Manual"
  29 .SH NAME
  30 taskset \- retrieve or set a process's CPU affinity
  31 .SH SYNOPSIS
  32 .B taskset
  33 .RI [ options ]\  mask
  34 .IR command\  [ arg ]...
  35 .br
  36 .B taskset
  37 .RI [ options ]
  38 .B \-p
  39 .RI [ mask ]\  pid
  40 .SH DESCRIPTION
  41 .PP
  42 .BR taskset
  43 is used to set or retrieve the CPU affinity of a running process given its PID
  44 or to launch a new COMMAND with a given CPU affinity.  CPU affinity is a
  45 scheduler property that "bonds" a process to a given set of CPUs on the system.
  46 The Linux scheduler will honor the given CPU affinity and the process will not
  47 run on any other CPUs.  Note that the Linux scheduler also supports natural
  48 CPU affinity: the scheduler attempts to keep processes on the same CPU as long
  49 as practical for performance reasons.  Therefore, forcing a specific CPU
  50 affinity is useful only in certain applications.
  51 .sp
  52 The CPU affinity is represented as a bitmask, with the lowest order bit
  53 corresponding to the first logical CPU and the highest order bit corresponding
  54 to the last logical CPU.  Not all CPUs may exist on a given system but a mask
  55 may specify more CPUs than are present.  A retrieved mask will reflect only the
  56 bits that correspond to CPUs physically on the system.  If an invalid mask is
  57 given (i.e., one that corresponds to no valid CPUs on the current system) an
  58 error is returned.  The masks are typically given in hexadecimal.  For example,
  59 .TP
  60 .BR 0x00000001
  61 is processor #0
  62 .TP
  63 .BR 0x00000003
  64 is processors #0 and #1
  65 .TP
  66 .BR 0xFFFFFFFF
  67 is all processors (#0 through #31)
  68 .PP
  69 When
  70 .BR taskset
  71 returns, it is guaranteed that the given program has been scheduled to a legal
  72 CPU.
  73 .SH OPTIONS
  74 .TP
  75 .BR \-p ,\  \-\-pid
  76 operate on an existing PID and not launch a new task
  77 .TP
  78 .BR \-c ,\  \-\-cpu-list
  79 specify a numerical list of processors instead of a bitmask.  The list may
  80 contain multiple items, separated by comma, and ranges.  For example,
  81 .BR 0,5,7,9-11 .
  82 .TP
  83 .BR \-h ,\  \-\-help
  84 display usage information and exit
  85 .TP
  86 .BR \-V ,\  \-\-version
  87 output version information and exit
  88 .SH USAGE
  89 .TP
  90 The default behavior is to run a new command with a given affinity mask:
  91 .B taskset
  92 .I mask
  93 .IR command\  [ arguments ]
  94 .TP
  95 You can also retrieve the CPU affinity of an existing task:
  96 .B taskset \-p
  97 .I pid
  98 .TP
  99 Or set it:
 100 .B taskset \-p
 101 .I mask pid
 102 .SH PERMISSIONS
 103 A user must possess
 104 .B CAP_SYS_NICE
 105 to change the CPU affinity of a process.  Any user can retrieve the affinity
 106 mask.
 107 .SH AUTHOR
 108 Written by Robert M. Love.
 109 .SH COPYRIGHT
 110 Copyright \(co 2004 Robert M. Love
 111 .br
 112 This is free software; see the source for copying conditions.  There is NO
 113 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 114 .SH "SEE ALSO"
 115 .BR chrt (1),
 116 .BR nice (1),
 117 .BR renice (1),
 118 .BR sched_setaffinity (2),
 119 .BR sched_getaffinity (2)
 120 .sp
 121 See
 122 .BR sched_setscheduler (2)
 123 for a description of the Linux scheduling scheme.
 124 .SH AVAILABILITY
 125 The taskset command is part of the util-linux-ng package and is available from
 126 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.