diff options
Diffstat (limited to 'man1p/nice.1p')
| -rw-r--r-- | man1p/nice.1p | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/man1p/nice.1p b/man1p/nice.1p new file mode 100644 index 000000000..adcd4f46a --- /dev/null +++ b/man1p/nice.1p @@ -0,0 +1,253 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NICE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nice +.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 +Built-In Utilities\fP , the results are undefined. +.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 +\fIShell Command Language\fP , \fIrenice\fP , the System +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 . |