2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "NICE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" nice
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
nice \- invoke a utility with an altered nice value
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBnice\fP \fB[\fP\fB-n\fP \fIincrement\fP\fB]\fP \fIutility\fP
|
|
|
|
\fB[\fP\fIargument\fP\fB...\fP\fB]\fP\fB\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fInice\fP utility shall invoke a utility, requesting that it
|
|
|
|
be run with a different nice value (see the Base Definitions
|
|
|
|
volume of IEEE\ Std\ 1003.1-2001, Section 3.239, Nice Value). With
|
|
|
|
no
|
|
|
|
options and only if the user has appropriate privileges, the executed
|
|
|
|
utility shall be run with a nice value that is some
|
|
|
|
implementation-defined quantity less than or equal to the nice value
|
|
|
|
of the current process. If the user lacks appropriate
|
|
|
|
privileges to affect the nice value in the requested manner, the \fInice\fP
|
|
|
|
utility shall not affect the nice value; in this case,
|
|
|
|
a warning message may be written to standard error, but this shall
|
|
|
|
not prevent the invocation of \fIutility\fP or affect the exit
|
|
|
|
status.
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fInice\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following option is supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-n\ \fP \fIincrement\fP
|
|
|
|
A positive or negative decimal integer which shall have the same effect
|
|
|
|
on the execution of the utility as if the utility had
|
|
|
|
called the \fInice\fP() function with the numeric value of the \fIincrement\fP
|
|
|
|
option-argument.
|
|
|
|
.sp
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operands shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIutility\fP
|
|
|
|
The name of a utility that is to be invoked. If the \fIutility\fP
|
|
|
|
operand names any of the special built-in utilities in \fISpecial
|
2007-09-20 06:36:16 +00:00
|
|
|
Built-In Utilities\fP, the results are undefined.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP 7
|
|
|
|
\fIargument\fP
|
|
|
|
Any string to be supplied as an argument when invoking the utility
|
|
|
|
named by the \fIutility\fP operand.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fInice\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
Provide a default value for the internationalization variables that
|
|
|
|
are unset or null. (See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
|
|
for
|
|
|
|
the precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
|
|
of text data as characters (for example, single-byte as
|
|
|
|
opposed to multi-byte characters in arguments).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.TP 7
|
|
|
|
\fIPATH\fP
|
|
|
|
Determine the search path used to locate the utility to be invoked.
|
|
|
|
See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables.
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
If \fIutility\fP is invoked, the exit status of \fInice\fP shall be
|
|
|
|
the exit status of \fIutility\fP; otherwise, the
|
|
|
|
\fInice\fP utility shall exit with one of the following values:
|
|
|
|
.TP 7
|
|
|
|
1-125
|
|
|
|
An error occurred in the \fInice\fP utility.
|
|
|
|
.TP 7
|
|
|
|
\ \ 126
|
|
|
|
The utility specified by \fIutility\fP was found but could not be
|
|
|
|
invoked.
|
|
|
|
.TP 7
|
|
|
|
\ \ 127
|
|
|
|
The utility specified by \fIutility\fP could not be found.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The only guaranteed portable uses of this utility are:
|
|
|
|
.TP 7
|
|
|
|
\fInice\ utility\fP
|
|
|
|
.sp
|
|
|
|
Run \fIutility\fP with the default lower nice value.
|
|
|
|
.TP 7
|
|
|
|
\fInice\ \fP \fB-n\ \fP <\fIpositive\ integer\fP>\fI\ utility\fP
|
|
|
|
.sp
|
|
|
|
Run \fIutility\fP with a lower nice value.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
On some implementations they have no discernible effect on the invoked
|
|
|
|
utility and on some others they are exactly
|
|
|
|
equivalent.
|
|
|
|
.LP
|
|
|
|
Historical systems have frequently supported the <\fIpositive integer\fP>
|
|
|
|
up to 20. Since there is no error penalty
|
|
|
|
associated with guessing a number that is too high, users without
|
|
|
|
access to the system conformance document (to see what limits are
|
|
|
|
actually in place) could use the historical 1 to 20 range or attempt
|
|
|
|
to use very large numbers if the job should be truly low
|
|
|
|
priority.
|
|
|
|
.LP
|
|
|
|
The nice value of a process can be displayed using the command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBps -o nice
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP,
|
|
|
|
and \fIxargs\fP utilities have been specified to use exit code 127
|
|
|
|
if an error occurs so that
|
|
|
|
applications can distinguish "failure to find a utility" from "invoked
|
|
|
|
utility exited with an error indication". The value 127
|
|
|
|
was chosen because it is not commonly used for other meanings; most
|
|
|
|
utilities use small values for "normal error conditions" and
|
|
|
|
the values above 128 can be confused with termination due to receipt
|
|
|
|
of a signal. The value 126 was chosen in a similar manner to
|
|
|
|
indicate that the utility could be found, but not invoked. Some scripts
|
|
|
|
produce meaningful error messages differentiating the 126
|
|
|
|
and 127 cases. The distinction between exit codes 126 and 127 is based
|
|
|
|
on KornShell practice that uses 127 when all attempts to
|
|
|
|
\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt
|
|
|
|
to \fIexec\fP the utility fails for any other
|
|
|
|
reason.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
Due to the text about the limits of the nice value being implementation-defined,
|
|
|
|
\fInice\fP is not actually required to change
|
|
|
|
the nice value of the executed command; the limits could be zero differences
|
|
|
|
from the system default, although the implementor is
|
|
|
|
required to document this fact in the conformance document.
|
|
|
|
.LP
|
|
|
|
The 4.3 BSD version of \fInice\fP does not check whether \fIincrement\fP
|
|
|
|
is a valid decimal integer. The command \fInice\fP
|
|
|
|
\fB-x\fP \fIutility\fP, for example, would be treated the same as
|
|
|
|
the command \fInice\fP \fB--1\fP \fIutility\fP. If the user
|
|
|
|
does not have appropriate privileges, this results in a "permission
|
|
|
|
denied" error. This is considered a bug.
|
|
|
|
.LP
|
|
|
|
When a user without appropriate privileges gives a negative \fIincrement\fP,
|
|
|
|
System V treats it like the command \fInice\fP
|
|
|
|
\fB-0\fP \fIutility\fP, while 4.3 BSD writes a "permission denied"
|
|
|
|
message and does not run the utility. Neither was considered
|
|
|
|
clearly superior, so the behavior was left unspecified.
|
|
|
|
.LP
|
|
|
|
The C shell has a built-in version of \fInice\fP that has a different
|
|
|
|
interface from the one described in this volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001.
|
|
|
|
.LP
|
|
|
|
The term "utility" is used, rather than "command", to highlight the
|
|
|
|
fact that shell compound commands, pipelines, and so on,
|
|
|
|
cannot be used. Special built-ins also cannot be used. However, "utility"
|
|
|
|
includes user application programs and shell scripts,
|
|
|
|
not just utilities defined in this volume of IEEE\ Std\ 1003.1-2001.
|
|
|
|
.LP
|
|
|
|
Historical implementations of \fInice\fP provide a nice value range
|
|
|
|
of 40 or 41 discrete steps, with the default nice value
|
|
|
|
being the midpoint of that range. By default, they lower the nice
|
|
|
|
value of the executed utility by 10.
|
|
|
|
.LP
|
|
|
|
Some historical documentation states that the \fIincrement\fP value
|
|
|
|
must be within a fixed range. This is misleading; the valid
|
|
|
|
\fIincrement\fP values on any invocation are determined by the current
|
|
|
|
process nice value, which is not always the default.
|
|
|
|
.LP
|
|
|
|
The definition of nice value is not intended to suggest that all processes
|
|
|
|
in a system have priorities that are comparable.
|
|
|
|
Scheduling policy extensions such as the realtime priorities in the
|
|
|
|
System Interfaces volume of IEEE\ Std\ 1003.1-2001 make
|
|
|
|
the notion of a single underlying priority for all scheduling policies
|
|
|
|
problematic. Some implementations may implement the
|
|
|
|
\fInice\fP-related features to affect all processes on the system,
|
|
|
|
others to affect just the general time-sharing activities
|
|
|
|
implied by this volume of IEEE\ Std\ 1003.1-2001, and others may have
|
|
|
|
no effect at all. Because of the use of
|
|
|
|
"implementation-defined" in \fInice\fP and \fIrenice\fP, a wide range
|
|
|
|
of implementation
|
|
|
|
strategies are possible.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fIShell Command Language\fP, \fIrenice\fP, the System
|
2004-11-03 13:51:07 +00:00
|
|
|
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fInice\fP()
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version 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 .
|