path: root/usr/src/man/man1/renice.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved
.\"
.TH RENICE 1 "Jan 9, 2004"
.SH NAME
renice \- alter priority of running processes
.SH SYNOPSIS
.LP
.nf
\fBrenice\fR [\fB-n\fR \fIincrement\fR] [\fB-i\fR \fIidtype\fR] \fIID\fR...
.fi

.LP
.nf
\fBrenice\fR [\fB-n\fR \fIincrement\fR] [\fB-g\fR | \fB-p\fR | \fB-u\fR] \fIID\fR...
.fi

.LP
.nf
\fBrenice\fR \fIpriority\fR [\fB-p\fR] \fIpid\fR... [\fB-g\fR \fIgid\fR]... [\fB-p\fR \fIpid\fR]...
     [\fB-u\fR \fIuser\fR]...
.fi

.LP
.nf
\fBrenice\fR \fIpriority\fR \fB-g\fR \fIgid\fR... [\fB-g\fR \fIgid\fR]... [\fB-p\fR \fIpid\fR]...
     [\fB-u\fR \fIuser\fR]...
.fi

.LP
.nf
\fBrenice\fR \fIpriority\fR \fB-u\fR \fIuser\fR... [\fB-g\fR \fIgid\fR]... [\fB-p\fR \fIpid\fR]...
     [\fB-u\fR \fIuser\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBrenice\fR command alters the scheduling priority of one or more running
processes. By default, the processes to be affected are specified by their
process \fBID\fRs.
.sp
.LP
If the first operand is a number within the valid range of priorities
(\fB\(mi20\fR to \fB20\fR), \fBrenice\fR will treat it as a \fIpriority\fR (as
in all but the first synopsis form). Otherwise, \fBrenice\fR will treat it as
an \fIID\fR (as in the first synopsis form).
.SS "Altering Process Priority"
.sp
.LP
Users other than the privileged user may only alter the priority of processes
they own, and can only monotonically increase their "nice value" within the
range \fB0\fR to \fB19\fR. This prevents overriding administrative fiats. The
privileged user may alter the priority of any process and set the priority to
any value in the range \fB\(mi20\fR to \fB19\fR. Useful priorities are:
\fB19\fR (the affected processes will run only when nothing else in the system
wants to); \fB0\fR (the "base" scheduling priority),; and any negative value
(to make things go very fast). \fB20\fR is an acceptable nice value, but will
be rounded down to \fB19\fR.
.SH OPTIONS
.sp
.LP
\fBrenice\fR supports the following option features:
.RS +4
.TP
.ie t \(bu
.el o
The first operand, \fIpriority\fR, must precede the options and can have the
appearance of a multi-digit option.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fB-g\fR, \fB-p\fR, and \fB-u\fR options can each take multiple
option-arguments.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fIpid\fR option-argument can be used without its \fB-p\fR option.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fB-i\fR option can be used to specify the \fIID\fR type for the \fBID\fR
list. This is preferred in specifying \fIID\fR type over the use of the
\fB-g\fR | \fB-p\fR | \fB-u\fR syntax, which is now obsolete. See NOTES.
.RE
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 16n
Interprets all operands or just the \fIgid\fR arguments as unsigned decimal
integer process group IDs.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 16n
This option, together with the \fIID\fR list arguments, specifies a class of
processes to which the \fBrenice\fR command is to apply. The interpretation of
the \fBID\fR list depends on the value of \fIidtype\fR. The valid \fIidtype\fR
arguments are: \fBpid\fR, \fBpgid\fR, \fBuid\fR, \fBgid\fR, \fBsid\fR,
\fBtaskid\fR, \fBprojid\fR, and \fBzoneid\fR.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIincrement\fR\fR
.ad
.RS 16n
Specifies how the system scheduling priority of the specified process or
processes is to be adjusted. The \fIincrement\fR option-argument is a positive
or negative decimal integer that will be used to modify the system scheduling
priority of the specified process or processes. Positive \fIincrement\fR values
cause a lower system scheduling priority. Negative \fIincrement\fR values may
require appropriate privileges and will cause a higher system scheduling
priority.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 16n
Interprets all operands or just the \fIpid\fR arguments as unsigned decimal
integer process \fBID\fRs. The \fB-p\fR option is the default if no options are
specified.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 16n
Interprets all operands or just the \fIuser\fR argument as users. If a user
exists with a user name equal to the operand, then the user \fBID\fR of that
user will be used in further processing. Otherwise, if the operand represents
an unsigned decimal integer, it will be used as the numeric user \fBID\fR of
the user.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIID\fR\fR
.ad
.RS 12n
A process \fBID\fR, process group \fBID\fR, or user name/user \fBID\fR,
depending on the option selected.
.RE

.sp
.ne 2
.na
\fB\fIpriority\fR\fR
.ad
.RS 12n
The value specified is taken as the actual system scheduling priority, rather
than as an increment to the existing system scheduling priority. Specifying a
scheduling priority higher than that of the existing process may require
appropriate privileges.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAdjusting the scheduling priority of process IDs
.sp
.LP
Adjust the system scheduling priority so that process \fBID\fRs \fB987\fR and
\fB32\fR would have a lower scheduling priority:

.sp
.in +2
.nf
example% \fBrenice -n 5 -p 987 32\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAdjusting the scheduling priority of group IDs
.sp
.LP
Adjust the system scheduling priority so that group \fBID\fRs \fB324\fR and
\fB76\fR would have a higher scheduling priority, if the user has the
appropriate privileges to do so:

.sp
.in +2
.nf
example% \fBrenice -n -4 -g 324 76\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRAdjusting the scheduling priority of a user ID and user name
.sp
.LP
Adjust the system scheduling priority so that numeric user ID \fB8\fR and user
\fBsas\fR would have a lower scheduling priority:

.sp
.in +2
.nf
example% \fBrenice -n 4 -u 8 sas\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBrenice\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.RS 15n
map user names to user \fBID\fRs
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.sp
.LP
\fBnice\fR(1), \fBpasswd\fR(1), \fBpriocntl\fR(1), \fBattributes\fR(5),
\fBenviron\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
The \fBrenice\fR syntax
.sp
.in +2
.nf
\fBrenice [-n \fIincrement\fR] [-i \fIidtype\fR] \fIID\fR ...\fR
.fi
.in -2
.sp

.sp
.LP
is preferred over the old syntax
.sp
.in +2
.nf
\fBrenice [-n \fIincrement\fR] [-g | -p| -u] \fIID\fR ...\fR
.fi
.in -2
.sp

.sp
.LP
which is now obsolete.
.sp
.LP
If you make the priority very negative, then the process cannot be interrupted.
.sp
.LP
To regain control you must make the priority greater than \fB0\fR.
.sp
.LP
Users other than the privileged user cannot increase scheduling priorities of
their own processes, even if they were the ones that decreased the priorities
in the first place.
.sp
.LP
The \fBpriocntl\fR command subsumes the function of \fBrenice\fR.