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 processes's CPU affinity
  31 .SH SYNOPSIS
  32 .B taskset
  33 [\fIoptions\fR] [\fImask\fR | \fIlist\fI ] [\fIpid\fR | \fIcommand\fR [\fIarg\fR]...]
  34 .SH DESCRIPTION
  35 .PP
  36 .BR taskset
  37 is used to set or retrieve the CPU affinity of a running process given its PID
  38 or to launch a new COMMAND with a given CPU affinity.  CPU affinity is a
  39 scheduler property that "bonds" a process to a given set of CPUs on the system.
  40 The Linux scheduler will honor the given CPU affinity and the process will not
  41 run on any other CPUs.  Note that the Linux scheduler also supports natural
  42 CPU affinity: the scheduler attempts to keep processes on the same CPU as long
  43 as practical for performance reasons.  Therefore, forcing a specific CPU
  44 affinity is useful only in certain applications.
  45 .sp
  46 The CPU affinity is represented as a bitmask, with the lowest order bit
  47 corresponding to the first logical CPU and the highest order bit corresponding
  48 to the last logical CPU.  Not all CPUs may exist on a given system but a mask
  49 may specify more CPUs than are present.  A retrieved mask will reflect only the
  50 bits that correspond to CPUs physically on the system.  If an invalid mask is
  51 given (i.e., one that corresponds to no valid CPUs on the current system) an
  52 error is returned.  The masks are typically given in hexadecimal.  For example,
  53 .TP
  54 .BR 0x00000001
  55 is processor #0
  56 .TP
  57 .BR 0x00000003
  58 is processors #0 and #1
  59 .TP
  60 .BR 0xFFFFFFFF
  61 is all processors (#0 through #31)
  62 .PP
  63 When
  64 .BR taskset
  65 returns, it is guaranteed that the given program has been scheduled to a legal
  66 CPU.
  67 .SH OPTIONS
  68 .TP
  69 .B -p, --pid
  70 operate on an existing PID and not launch a new task
  71 .TP
  72 .B -c, --cpu-list
  73 specifiy a numerical list of processors instead of a bitmask.  The list may
  74 contain multiple items, separated by comma, and ranges.  For example,
  75 .BR 0,5,7,9-11 .
  76 .TP
  77 .B -h, --help
  78 display usage information and exit
  79 .TP
  80 .B -V, --version
  81 output version information and exit
  82 .SH USAGE
  83 .TP
  84 The default behavior is to run a new command with a given affinity mask:
  85 taskset [mask] [command] [arguments]
  86 .TP
  87 You can also retrieve the CPU affinity of an existing task:
  88 taskset -p [pid]
  89 .TP
  90 Or set it:
  91 taskset -p [mask] [pid]
  92 .SH PERMISSIONS
  93 A user must possess
  94 .BR CAP_SYS_NICE
  95 to change the CPU affinity of a process.  Any user can retrieve the affinity
  96 mask.
  97 .SH AUTHOR
  98 Written by Robert M. Love.
  99 .SH COPYRIGHT
 100 Copyright \(co 2004 Robert M. Love
 101 .br
 102 This is free software; see the source for copying conditions.  There is NO
 103 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 104 .SH "SEE ALSO"
 105 .BR chrt (1),
 106 .BR nice (1),
 107 .BR renice (1),
 108 .BR sched_setaffinity (2),
 109 .BR sched_getaffinity (2)
 110 .sp
 111 See
 112 .BR sched_setscheduler (2)
 113 for a description of the Linux scheduling scheme.
 114 .SH AVAILABILITY
 115 The taskset command is part of the util-linux-ng package and is available from
 116 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.