add more concrete examples of how to use chrt(1)

[thirdparty/util-linux.git] / schedutils / chrt.1.adoc

//po4a: entry man manual
////
chrt(1) manpage

Copyright (C) 2004 Robert Love
Copyright (C) 2015 Karel Zak <kzak@redhat.com>

This is free documentation; you can redistribute it and/or
modify it under the terms of the GNU General Public License,
version 2, as published by the Free Software Foundation.

The GNU General Public License's references to "object code"
and "executables" are to be interpreted as the output of any
document formatting or typesetting system, including
intermediate and printed output.

This manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
////
= chrt(1)
:doctype: manpage
:man manual: User Commands
:man source: util-linux {release-version}
:page-layout: base
:command: chrt
:colon: :

== NAME

chrt - manipulate the real-time attributes of a process

== SYNOPSIS

*chrt* [options] _priority command argument_ ...

*chrt* [options] *-p* [_priority_] _PID_

== DESCRIPTION

*chrt* sets or retrieves the real-time scheduling attributes of an existing _PID_, or runs _command_ with the given attributes.

== POLICIES

*-o*, *--other*::
Set scheduling policy to *SCHED_OTHER* (time-sharing scheduling). This is the default Linux scheduling policy.

*-f*, *--fifo*::
Set scheduling policy to *SCHED_FIFO* (first in-first out).

*-r*, *--rr*::
Set scheduling policy to *SCHED_RR* (round-robin scheduling). When no policy is defined, the *SCHED_RR* is used as the default.

*-b*, *--batch*::
Set scheduling policy to *SCHED_BATCH* (scheduling batch processes). Linux-specific, supported since 2.6.16. The priority argument has to be set to zero.

*-i*, *--idle*::
Set scheduling policy to *SCHED_IDLE* (scheduling very low priority jobs). Linux-specific, supported since 2.6.23. The priority argument has to be set to zero.

*-d*, *--deadline*::
Set scheduling policy to *SCHED_DEADLINE* (sporadic task model deadline scheduling). Linux-specific, supported since 3.14. The priority argument has to be set to zero. See also *--sched-runtime*, *--sched-deadline* and *--sched-period*. The relation between the options required by the kernel is runtime <= deadline <= period. *chrt* copies _period_ to _deadline_ if *--sched-deadline* is not specified and _deadline_ to _runtime_ if *--sched-runtime* is not specified. It means that at least *--sched-period* has to be specified. See *sched*(7) for more details.

== SCHEDULING OPTIONS

*-T*, *--sched-runtime* _nanoseconds_::
Specifies runtime parameter for *SCHED_DEADLINE* policy (Linux-specific).

*-P*, *--sched-period* _nanoseconds_::
Specifies period parameter for *SCHED_DEADLINE* policy (Linux-specific).

*-D*, *--sched-deadline* _nanoseconds_::
Specifies deadline parameter for *SCHED_DEADLINE* policy (Linux-specific).

*-R*, *--reset-on-fork*::
Use *SCHED_RESET_ON_FORK* or *SCHED_FLAG_RESET_ON_FORK* flag. Linux-specific, supported since 2.6.31.

Each thread has a _reset-on-fork_ scheduling flag. When this flag is set, children created by *fork*(2) do not inherit privileged scheduling policies. After the _reset-on-fork_ flag has been enabled, it can be reset only if the thread has the *CAP_SYS_NICE* capability. This flag is disabled in child processes created by *fork*(2).

More precisely, if the _reset-on-fork_ flag is set, the following rules apply for subsequently created children:

* If the calling thread has a scheduling policy of *SCHED_FIFO* or *SCHED_RR*, the policy is reset to *SCHED_OTHER* in child processes.

* If the calling process has a negative nice value, the nice value is reset to zero in child processes.

== OPTIONS

*-a*, *--all-tasks*::
Set or retrieve the scheduling attributes of all the tasks (threads) for a given PID.

*-m*, *--max*::
Show minimum and maximum valid priorities, then exit.

*-p*, *--pid*::
Operate on an existing PID and do not launch a new task.

*-v*, *--verbose*::
Show status information.

include::man-common/help-version.adoc[]

== EXAMPLES

//TRANSLATORS: Keep {colon} untranslated
The default behavior is to run a new command{colon}::

*chrt* _priority_ _command_ [_arguments_]

//TRANSLATORS: Keep {colon} untranslated
You can also retrieve the real-time attributes of an existing task{colon}::

*chrt -p* _PID_

//TRANSLATORS: Keep {colon} untranslated
Or set them{colon}::

*chrt -r -p* _priority PID_

This, for example, sets real-time scheduling to priority _30_ for the
process _PID_ with the *SCHED_RR* (round-robin) class:

*chrt -r -p 30 _PID_*

Reset priorities to default for a process:

*chrt -o -p 0 _PID_*

See *sched*(7) for a detailed discussion of the different scheduler
classes and how they interact.

== PERMISSIONS

A user must possess *CAP_SYS_NICE* to change the scheduling attributes of a process. Any user can retrieve the scheduling information.

== NOTES

Only *SCHED_FIFO*, *SCHED_OTHER* and *SCHED_RR* are part of POSIX 1003.1b Process Scheduling. The other scheduling attributes may be ignored on some systems.

Linux' default scheduling policy is *SCHED_OTHER*.

== AUTHORS

mailto:rml@tech9.net[Robert Love],
mailto:kzak@redhat.com[Karel Zak]

== SEE ALSO

*nice*(1),
*renice*(1),
*taskset*(1),
*sched*(7)

See *sched_setscheduler*(2) for a description of the Linux scheduling scheme.

include::man-common/bugreports.adoc[]

include::man-common/footer.adoc[]

ifdef::translation[]
include::man-common/translation.adoc[]
endif::[]