schedutils/coresched.1.adoc

   1 //po4a: entry man manual
   2 ////
   3 coresched(1) manpage
   4 ////
   5 = coresched(1)
   6 :doctype: manpage
   7 :man manual: User Commands
   8 :man source: util-linux {release-version}
   9 :page-layout: base
  10 :command: coresched
  11 :colon: :
  12 :copyright: ©
  13
  14 == NAME
  15
  16 coresched - manage core scheduling cookies for tasks
  17
  18 == SYNOPSIS
  19
  20 *{command}* [*get*] [*-s* _pid_]
  21
  22 *{command}* *new* [*-t* _type_] *-d* _pid_
  23
  24 *{command}* *new* [*-t* _type_] \-- _command_ [_argument_...]
  25
  26 *{command}* *copy* [*-s* _pid_] [*-t* _type_] *-d* _pid_
  27
  28 *{command}* *copy* [*-s* _pid_] [*-t* _type_] \-- _command_ [_argument_...]
  29
  30 == DESCRIPTION
  31 The *{command}* 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.
  32
  33 Core scheduling permits the definition of groups of tasks that are allowed to share a physical core.
  34 This is done by assigning a cookie to each task.
  35 Only tasks have the same cookie are allowed to be scheduled on the same physical core.
  36
  37 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.
  38
  39 == FUNCTIONS
  40 *get*::
  41 Retrieve the core scheduling cookie of the PID specified in *-s*.
  42 If *-s* is omitted, it will get the cookie of the current *{command}* process.
  43
  44 *new*::
  45 Assign a new cookie to an existing PID specified in *-d*, or execute _command_ with a new cookie.
  46
  47 *copy*::
  48 Copy the cookie from an existing PID (*-s*) to another PID (*-d*), or execute _command_ with that cookie.
  49 If *-s* is omitted, it will get the cookie of the current *{command}* process.
  50
  51 If no function is specified, it will run the *get* function.
  52
  53 == OPTIONS
  54 *-s*, *--source* _PID_::
  55 Which _PID_ to get the cookie from.
  56 If this option is omitted, it will get the cookie from the current *{command}* process.
  57
  58 *-d*, *--dest* _PID_::
  59 Which _PID_ to modify the cookie of.
  60
  61 *-t*, *--dest-type* _TYPE_::
  62 The type of the PID whose cookie will be modified. This can be one of three values:
  63 - *pid*, or process ID
  64 - *tgid*, or thread group ID (default value)
  65 - *pgid*, or process group ID
  66
  67 *-v*, *--verbose*::
  68 Show extra information when modifying cookies of tasks.
  69
  70 *-h*, *--help*::
  71 Display help text and exit.
  72
  73 *-V*, *--version*::
  74 Print version and exit.
  75
  76 == EXAMPLES
  77 Get the core scheduling cookie of the {command} task itself, usually inherited from its parent{colon}::
  78 *{command} get*
  79
  80 Get the core scheduling cookie of a task with PID _123_{colon}::
  81 *{command} get -s* _123_
  82
  83 Give a task with PID _123_ a new core scheduling cookie{colon}::
  84 *{command} new -d* _123_
  85
  86 Spawn a new task with a new core scheduling cookie{colon}::
  87 *{command} new* \-- _command_ [_argument_...]
  88
  89 Copy the cookie from the current {command} process another task with pid _456_{colon}::
  90 *{command} copy -d* _456_
  91
  92 Copy the cookie from a task with pid _123_ to another task with pid _456_{colon}::
  93 *{command} copy -s* _123_ *-d* _456_
  94
  95 Copy the cookie from a task with pid _123_ to a new task _command_{colon}::
  96 *{command} copy -s* _123_ \-- _command_ [_argument_...]
  97
  98 Copy the cookie from a task with pid _123_ to the process group ID _456_{colon}::
  99 *{command} copy -s* _123_ *-t* _pgid_ *-d* _456_
 100
 101 == PERMISSIONS
 102 Retrieving or modifying the core scheduling cookie of a process requires *PTRACE_MODE_READ_REALCREDS* ptrace access to that process.
 103 See the section "Ptrace access mode checking" in *ptrace*(2) for more information.
 104
 105 == RETURN VALUE
 106 On success, *{command}* returns 0.
 107 If *{command}* fails, it will print an error and return 1.
 108
 109 If a _command_ is being executed, the return value of *{command}* will be the return value of _command_.
 110
 111 == NOTES
 112 *{command}* requires core scheduling support in the kernel.
 113 This can be enabled via the *CONFIG_SCHED_CORE* kernel config option.
 114
 115 == AUTHORS
 116 mailto:thijs@raymakers.nl[Thijs Raymakers],
 117 mailto:pauld@redhat.com[Phil Auld]
 118
 119 == COPYRIGHT
 120
 121 Copyright {copyright} 2024 Thijs Raymakers and Phil Auld. This is free software licensed under the EUPL.
 122
 123 == SEE ALSO
 124 *chrt*(1),
 125 *nice*(1),
 126 *renice*(1),
 127 *taskset*(1),
 128 *ptrace*(2),
 129 *sched*(7)
 130
 131 The Linux kernel source files _Documentation/admin-guide/hw-vuln/core-scheduling.rst_
 132
 133 include::man-common/bugreports.adoc[]
 134
 135 include::man-common/footer.adoc[]
 136
 137 ifdef::translation[]
 138 include::man-common/translation.adoc[]
 139 endif::[]