.\"	$NetBSD: renice.8,v 1.18 2020/10/23 16:14:40 wiz Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)renice.8	8.1 (Berkeley) 6/9/93
.\"
.Dd October 22, 2020
.Dt RENICE 8
.Os
.Sh NAME
.Nm renice
.Nd alter priority of running processes
.Sh SYNOPSIS
.Nm
.Ar priority
.Oo
.Op Fl gpu
.Ar who ...
.Oc
.Ar ...
.Nm
.Fl n
.Ar increment
.Oo
.Op Fl gpu
.Ar who ...
.Oc
.Ar ...
.Sh DESCRIPTION
.Nm
alters the
scheduling priority of one or more running processes.
The first argument is the new priority to apply, or if
.Fl n
is given, the change to make (applied additively) to the priority.
This argument may be negative.
(The interpretation of priorities is discussed below.)
.Pp
The following
.Ar who
parameters name the target processes, as either process IDs, process
group IDs, or user names.
The
.Fl gpu
options control the interpretation as follows:
.Bl -tag -width Ds
.It Fl g
Interpret
.Ar who
parameters as process group ID's.
.It Fl p
Interpret
.Ar who
parameters as process IDs.
This is the default.
.It Fl u
Interpret
.Ar who
parameters as user names.
.El
.Pp
Each
.Ar who
parameter is processed separately and updates the priority of the
processes it names as follows:
.Bl -tag -width "with Ds"
.It with Fl g
All processes in the process group are updated to the selected
priority.
If an
.Ar increment
is used, the increment is added to the highest priority found among
the members of the process group prior to the change.
.It with Fl p
The named process is updated to the selected priority.
If an
.Ar increment
is used, the increment is added to the process's previous priority.
.It with Fl u
All processes belonging to the specified user are updated to the
selected priority.
If an
.Ar increment
is used, the increment is added to the highest priority found among
the processes belonging to the user prior to the change.
.El
.Pp
In conventional terminology a
.Dq high priority
process receives a lot of CPU time and a
.Dq low priority
process receives relatively little.
.Dq Niceness
is the inverse concept: a process with a high niceness level receives
relatively little CPU time.
It is about the process being nice to the rest of the system, rather
than the system being nice to the process.
.Pp
The numerical priority values accepted by
.Nm
are
.Em called
priorities but are actually nicenesses.
They range from
.Dv PRIO_MIN
(\-20)
to
.Dv PRIO_MAX
(20).
.Dv PRIO_MIN
is the highest priority, lowest niceness, and receives the most CPU
time.
.Dv PRIO_MAX
is the lowest priority, highest niceness, and receives the least CPU
time.
This is confusing but enshrined in historical practice and standards.
If in doubt, check with
.Xr ps 1 :
processes running with elevated priority (getting more CPU time)
include
.Sq <
in the FLAGS column; processes running with reduced priority
(getting less CPU time) show
.Sq N
for
.Dq nice
in FLAGS.
The default priority is 0.
.Pp
At priority 20, processes will specifically run only when nothing else
wants to.
.Pp
Users other than the super-user may only alter the priority of
processes they own,
and only by increasing the niceness.
(This prevents overriding administrative fiats.)
The super-user
may alter the priority of any process to any legal value.
.Sh FILES
.Bl -tag -width /etc/passwd -compact
.It Pa /etc/passwd
to map user names to user ID's
.El
.Sh EXAMPLES
.Bd -literal -offset indent
renice +1 987 -u daemon root -p 32
.Ed
.Pp
changes the priority of process ID's 987 and 32, and
all processes owned by users daemon and root.
.Sh SEE ALSO
.Xr nice 1 ,
.Xr prenice 1 ,
.Xr getpriority 2 ,
.Xr setpriority 2
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.0 .
.Sh BUGS
Non-super-users cannot increase scheduling priorities of their own processes,
even if they were the ones that decreased the priorities in the first place.