{ "content": [ { "type": "text", "text": "# taskset (man)\n\n## NAME\n\ntaskset - set or retrieve a process's CPU affinity\n\n## SYNOPSIS\n\ntaskset [options] mask command [argument...]\ntaskset [options] -p [mask] pid\n\n## DESCRIPTION\n\nThe taskset command is used to set or retrieve the CPU affinity of a running process given\nits pid, or to launch a new command with a given CPU affinity. CPU affinity is a scheduler\nproperty that \"bonds\" a process to a given set of CPUs on the system. The Linux scheduler\nwill honor the given CPU affinity and the process will not run on any other CPUs. Note that\nthe Linux scheduler also supports natural CPU affinity: the scheduler attempts to keep\nprocesses on the same CPU as long as practical for performance reasons. Therefore, forcing a\nspecific CPU affinity is useful only in certain applications. The affinity of some processes\nlike kernel per-CPU threads cannot be set.\n\n## TLDR\n\n> Get or set a process' CPU affinity or start a new process with a defined CPU affinity.\n\n- Get a running process' CPU affinity by PID:\n `taskset {{-p|--pid}} {{-c|--cpu-list}} {{pid}}`\n- Set a running process' CPU affinity by PID:\n `taskset {{-p|--pid}} {{-c|--cpu-list}} {{cpu_id}} {{pid}}`\n- Start a new process with affinity for a single CPU:\n `taskset {{-c|--cpu-list}} {{cpu_id}} {{command}}`\n- Start a new process with affinity for multiple non-sequential CPUs:\n `taskset {{-c|--cpu-list}} {{cpu_id_1,cpu_id_2,cpu_id_3,...}}`\n- Start a new process with affinity for CPUs 1 through 4:\n `taskset {{-c|--cpu-list}} {{cpu_id_1}}-{{cpu_id_4}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (5 subsections)\n- **OPTIONS** (5 subsections)\n- **USAGE**\n- **PERMISSIONS**\n- **RETURN VALUE**\n- **AUTHORS**\n- **COPYRIGHT**\n- **SEE ALSO**\n- **REPORTING BUGS**\n- **AVAILABILITY**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "taskset", "section": "", "mode": "man", "summary": "taskset - set or retrieve a process's CPU affinity", "synopsis": "taskset [options] mask command [argument...]\ntaskset [options] -p [mask] pid", "tldr_summary": "Get or set a process' CPU affinity or start a new process with a defined CPU affinity.", "tldr_examples": [ { "description": "Get a running process' CPU affinity by PID", "command": "taskset {{-p|--pid}} {{-c|--cpu-list}} {{pid}}" }, { "description": "Set a running process' CPU affinity by PID", "command": "taskset {{-p|--pid}} {{-c|--cpu-list}} {{cpu_id}} {{pid}}" }, { "description": "Start a new process with affinity for a single CPU", "command": "taskset {{-c|--cpu-list}} {{cpu_id}} {{command}}" }, { "description": "Start a new process with affinity for multiple non-sequential CPUs", "command": "taskset {{-c|--cpu-list}} {{cpu_id_1,cpu_id_2,cpu_id_3,...}}" }, { "description": "Start a new process with affinity for CPUs 1 through 4", "command": "taskset {{-c|--cpu-list}} {{cpu_id_1}}-{{cpu_id_4}}" } ], "tldr_source": "official", "flags": [ { "flag": "-a", "long": "--all-tasks", "arg": null, "description": "Set or retrieve the CPU affinity of all the tasks (threads) for a given PID." }, { "flag": "-c", "long": "--cpu-list", "arg": null, "description": "Interpret mask as numerical list of processors instead of a bitmask. Numbers are separated by commas and may include ranges. For example: 0,5,8-11." }, { "flag": "-p", "long": "--pid", "arg": null, "description": "Operate on an existing PID and do not launch a new task." }, { "flag": "-h", "long": "--help", "arg": null, "description": "Display help text and exit." }, { "flag": "-V", "long": "--version", "arg": null, "description": "Print version and exit." } ], "examples": [], "see_also": [ { "name": "chrt", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/chrt/1/json" }, { "name": "nice", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/nice/1/json" }, { "name": "renice", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/renice/1/json" }, { "name": "schedgetaffinity", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/schedgetaffinity/2/json" }, { "name": "schedsetaffinity", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/schedsetaffinity/2/json" }, { "name": "sched", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/sched/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 4, "subsections": [] }, { "name": "DESCRIPTION", "lines": 17, "subsections": [ { "name": "0x00000001", "lines": 2 }, { "name": "0x00000003", "lines": 5 }, { "name": "0x32", "lines": 2 }, { "name": "--cpu-list 0-2,6", "lines": 2, "long": "--cpu-list" }, { "name": "--cpu-list 0-10:2", "lines": 6, "long": "--cpu-list" } ] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "-a --all-tasks", "lines": 2, "flag": "-a", "long": "--all-tasks" }, { "name": "-c --cpu-list", "lines": 3, "flag": "-c", "long": "--cpu-list" }, { "name": "-p --pid", "lines": 2, "flag": "-p", "long": "--pid" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" } ] }, { "name": "USAGE", "lines": 16, "subsections": [] }, { "name": "PERMISSIONS", "lines": 4, "subsections": [] }, { "name": "RETURN VALUE", "lines": 31, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "AVAILABILITY", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "taskset - set or retrieve a process's CPU affinity\n", "subsections": [] }, "SYNOPSIS": { "content": "taskset [options] mask command [argument...]\n\ntaskset [options] -p [mask] pid\n", "subsections": [] }, "DESCRIPTION": { "content": "The taskset command is used to set or retrieve the CPU affinity of a running process given\nits pid, or to launch a new command with a given CPU affinity. CPU affinity is a scheduler\nproperty that \"bonds\" a process to a given set of CPUs on the system. The Linux scheduler\nwill honor the given CPU affinity and the process will not run on any other CPUs. Note that\nthe Linux scheduler also supports natural CPU affinity: the scheduler attempts to keep\nprocesses on the same CPU as long as practical for performance reasons. Therefore, forcing a\nspecific CPU affinity is useful only in certain applications. The affinity of some processes\nlike kernel per-CPU threads cannot be set.\n\nThe CPU affinity is represented as a bitmask, with the lowest order bit corresponding to the\nfirst logical CPU and the highest order bit corresponding to the last logical CPU. Not all\nCPUs may exist on a given system but a mask may specify more CPUs than are present. A\nretrieved mask will reflect only the bits that correspond to CPUs physically on the system.\nIf an invalid mask is given (i.e., one that corresponds to no valid CPUs on the current\nsystem) an error is returned. The masks may be specified in hexadecimal (with or without a\nleading \"0x\"), or as a CPU list with the --cpu-list option. For example,\n", "subsections": [ { "name": "0x00000001", "content": "is processor #0,\n" }, { "name": "0x00000003", "content": "is processors #0 and #1,\n\nFFFFFFFF\nis processors #0 through #31,\n" }, { "name": "0x32", "content": "is processors #1, #4, and #5,\n" }, { "name": "--cpu-list 0-2,6", "content": "is processors #0, #1, #2, and #6.\n", "long": "--cpu-list" }, { "name": "--cpu-list 0-10:2", "content": "is processors #0, #2, #4, #6, #8 and #10. The suffix \":N\" specifies stride in the range,\nfor example 0-10:3 is interpreted as 0,3,6,9 list.\n\nWhen taskset returns, it is guaranteed that the given program has been scheduled to a legal\nCPU.\n", "long": "--cpu-list" } ] }, "OPTIONS": { "content": "", "subsections": [ { "name": "-a --all-tasks", "content": "Set or retrieve the CPU affinity of all the tasks (threads) for a given PID.\n", "flag": "-a", "long": "--all-tasks" }, { "name": "-c --cpu-list", "content": "Interpret mask as numerical list of processors instead of a bitmask. Numbers are\nseparated by commas and may include ranges. For example: 0,5,8-11.\n", "flag": "-c", "long": "--cpu-list" }, { "name": "-p --pid", "content": "Operate on an existing PID and do not launch a new task.\n", "flag": "-p", "long": "--pid" }, { "name": "-h --help", "content": "Display help text and exit.\n", "flag": "-h", "long": "--help" }, { "name": "-V --version", "content": "Print version and exit.\n", "flag": "-V", "long": "--version" } ] }, "USAGE": { "content": "The default behavior is to run a new command with a given affinity mask:\ntaskset mask command [arguments]\n\nYou can also retrieve the CPU affinity of an existing task:\ntaskset -p pid\n\nOr set it:\ntaskset -p mask pid\n\nWhen a cpu-list is specified for an existing process, the -p and -c options must be grouped\ntogether:\ntaskset -pc cpu-list pid\n\nThe --cpu-list form is applicable only for launching new commands:\ntaskset --cpu-list cpu-list command\n", "subsections": [] }, "PERMISSIONS": { "content": "A user can change the CPU affinity of a process belonging to the same user. A user must\npossess CAPSYSNICE to change the CPU affinity of a process belonging to another user. A\nuser can retrieve the affinity mask of any process.\n", "subsections": [] }, "RETURN VALUE": { "content": "taskset returns 0 in its affinity-getting mode as long as the provided PID exists.\n\ntaskset returns 0 in its affinity-setting mode as long as the underlying schedsetaffinity(2)\nsystem call does. The success of the command does not guarantee that the specified thread has\nactually migrated to the indicated CPU(s), but only that the thread will not migrate to a CPU\noutside the new affinity mask. For example, the affinity of the kernel thread kswapd can be\nset, but the thread may not immediately migrate and is not guaranteed to ever do so:\n\n$ ps ax -o comm,psr,pid | grep kswapd\nkswapd0 4 82\n$ sudo taskset -p 1 82\npid 82’s current affinity mask: 1\npid 82’s new affinity mask: 1\n$ echo $?\n0\n$ ps ax -o comm,psr,pid | grep kswapd\nkswapd0 4 82\n$ taskset -p 82\npid 82’s current affinity mask: 1\n\nIn contrast, when the user specifies an illegal affinity, taskset will print an error and\nreturn 1:\n\n$ ps ax -o comm,psr,pid | grep ksoftirqd/0\nksoftirqd/0 0 14\n$ sudo taskset -p 1 14\npid 14’s current affinity mask: 1\ntaskset: failed to set pid 14’s affinity: Invalid argument\n$ echo $?\n1\n", "subsections": [] }, "AUTHORS": { "content": "Written by Robert M. Love.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2004 Robert M. Love. This is free software; see the source for copying\nconditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR\nPURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "chrt(1), nice(1), renice(1), schedgetaffinity(2), schedsetaffinity(2)\n\nSee sched(7) for a description of the Linux scheduling scheme.\n", "subsections": [] }, "REPORTING BUGS": { "content": "For bug reports, use the issue tracker at \u001b[34mhttps://github.com/util-linux/util-linux/issues\u001b[0m.\n", "subsections": [] }, "AVAILABILITY": { "content": "The taskset command is part of the util-linux package which can be downloaded from \u001b[34mLinux\u001b[0m\n\u001b[34mKernel Archive \u001b[0m.\n\nutil-linux 2.39.3 2023-11-21 TASKSET(1)", "subsections": [] } } } }