CORESCHED(1) User Commands CORESCHED(1)

coresched - manage core scheduling cookies for tasks

coresched [get] [-s pid]

coresched new [-t type] -d pid

coresched new [-t type] -- command [argument...]

coresched copy [-s pid] [-t type] -d pid

coresched copy [-s pid] [-t type] -- command [argument...]

The coresched command is used to retrieve or modify the core scheduling cookies of a running process given its pid, or to spawn a new command with core scheduling cookies.

Core scheduling permits the definition of groups of tasks that are allowed to share a physical core. This is done by assigning a cookie to each task. Only tasks have the same cookie are allowed to be scheduled on the same physical core.

It is possible to either assign a new random cookie to a task, or copy a cookie from another task. It is not possible to choose the value of the cookie.

get

Retrieve the core scheduling cookie of the PID specified in -s. If -s is omitted, it will get the cookie of the current coresched process.

new

Assign a new cookie to an existing PID specified in -d, or execute command with a new cookie.

copy

Copy the cookie from an existing PID (-s) to another PID (-d), or execute command with that cookie. If -s is omitted, it will get the cookie of the current coresched process.

If no function is specified, it will run the get function.

-s, --source PID

Which PID to get the cookie from. If this option is omitted, it will get the cookie from the current coresched process.

-d, --dest PID

Which PID to modify the cookie of.

-t, --dest-type TYPE

The type of the PID whose cookie will be modified. This can be one of three values:
•pid, or process ID
•tgid, or thread group ID (default value)
•pgid, or process group ID

-v, --verbose

Show extra information when modifying cookies of tasks.

-h, --help

Display help text and exit.

-V, --version

Display version and exit.

Get the core scheduling cookie of the coresched task itself, usually inherited from its parent:

coresched get

Get the core scheduling cookie of a task with PID 123:

coresched get -s 123

Give a task with PID 123 a new core scheduling cookie:

coresched new -d 123

Spawn a new task with a new core scheduling cookie:

coresched new -- command [argument...]

Copy the cookie from the current coresched process another task with pid 456:

coresched copy -d 456

Copy the cookie from a task with pid 123 to another task with pid 456:

coresched copy -s 123 -d 456

Copy the cookie from a task with pid 123 to a new task command:

coresched copy -s 123 -- command [argument...]

Copy the cookie from a task with pid 123 to the process group ID 456:

coresched copy -s 123 -t pgid -d 456

Retrieving or modifying the core scheduling cookie of a process requires PTRACE_MODE_READ_REALCREDS ptrace access to that process. See the section "Ptrace access mode checking" in ptrace(2) for more information.

On success, coresched returns 0. If coresched fails, it will print an error and return 1.

If a command is being executed, the return value of coresched will be the return value of command.

coresched requires core scheduling support in the kernel. This can be enabled via the CONFIG_SCHED_CORE kernel config option.

Thijs Raymakers <thijs@raymakers.nl>, Phil Auld <pauld@redhat.com>

Copyright © 2024 Thijs Raymakers and Phil Auld. This is free software licensed under the EUPL.

chrt(1), nice(1), renice(1), taskset(1), ptrace(2), sched(7)

The Linux kernel source files Documentation/admin-guide/hw-vuln/core-scheduling.rst

For bug reports, use the issue tracker https://github.com/util-linux/util-linux/issues.

The coresched command is part of the util-linux package which can be downloaded from Linux Kernel Archive https://www.kernel.org/pub/linux/utils/util-linux/.

2025-03-29 util-linux 2.41