1NICE(1P) POSIX Programmer's Manual NICE(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 nice - invoke a utility with an altered nice value
13
15 nice [-n increment] utility [argument...]
16
18 The nice utility shall invoke a utility, requesting that it be run with
19 a different nice value (see the Base Definitions volume of
20 IEEE Std 1003.1-2001, Section 3.239, Nice Value). With no options and
21 only if the user has appropriate privileges, the executed utility shall
22 be run with a nice value that is some implementation-defined quantity
23 less than or equal to the nice value of the current process. If the
24 user lacks appropriate privileges to affect the nice value in the
25 requested manner, the nice utility shall not affect the nice value; in
26 this case, a warning message may be written to standard error, but this
27 shall not prevent the invocation of utility or affect the exit status.
28
30 The nice utility shall conform to the Base Definitions volume of
31 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
32 The following option is supported:
34 -n increment
36 A positive or negative decimal integer which shall have the same
37 effect on the execution of the utility as if the utility had
38 called the nice() function with the numeric value of the incre‐
39 ment option-argument.
40
43 The following operands shall be supported:
44 utility
46 The name of a utility that is to be invoked. If the utility op‐
47 erand names any of the special built-in utilities in Special
48 Built-In Utilities, the results are undefined.
49 argument
51 Any string to be supplied as an argument when invoking the util‐
52 ity named by the utility operand.
53
56 Not used.
57
59 None.
60
62 The following environment variables shall affect the execution of nice:
63 LANG Provide a default value for the internationalization variables
65 that are unset or null. (See the Base Definitions volume of
66 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
67 ables for the precedence of internationalization variables used
68 to determine the values of locale categories.)
69 LC_ALL If set to a non-empty string value, override the values of all
71 the other internationalization variables.
72 LC_CTYPE
74 Determine the locale for the interpretation of sequences of
75 bytes of text data as characters (for example, single-byte as
76 opposed to multi-byte characters in arguments).
77 LC_MESSAGES
79 Determine the locale that should be used to affect the format
80 and contents of diagnostic messages written to standard error.
81 NLSPATH
83 Determine the location of message catalogs for the processing of
84 LC_MESSAGES .
85 PATH Determine the search path used to locate the utility to be
87 invoked. See the Base Definitions volume of
88 IEEE Std 1003.1-2001, Chapter 8, Environment Variables.
89
92 Default.
93
95 Not used.
96
98 The standard error shall be used only for diagnostic messages.
99
101 None.
102
104 None.
105
107 If utility is invoked, the exit status of nice shall be the exit status
108 of utility; otherwise, the nice utility shall exit with one of the fol‐
109 lowing values:
110 1-125 An error occurred in the nice utility.
112 126 The utility specified by utility was found but could not be
114 invoked.
115 127 The utility specified by utility could not be found.
117
120 Default.
121 The following sections are informative.
123
125 The only guaranteed portable uses of this utility are:
126 nice utility
128 Run utility with the default lower nice value.
130 nice -n <positive integer> utility
132 Run utility with a lower nice value.
134 On some implementations they have no discernible effect on the invoked
137 utility and on some others they are exactly equivalent.
138 Historical systems have frequently supported the <positive integer> up
140 to 20. Since there is no error penalty associated with guessing a num‐
141 ber that is too high, users without access to the system conformance
142 document (to see what limits are actually in place) could use the his‐
143 torical 1 to 20 range or attempt to use very large numbers if the job
144 should be truly low priority.
145 The nice value of a process can be displayed using the command:
147 ps -o nice
150 The command, env, nice, nohup, time, and xargs utilities have been
152 specified to use exit code 127 if an error occurs so that applications
153 can distinguish "failure to find a utility" from "invoked utility
154 exited with an error indication". The value 127 was chosen because it
155 is not commonly used for other meanings; most utilities use small val‐
156 ues for "normal error conditions" and the values above 128 can be con‐
157 fused with termination due to receipt of a signal. The value 126 was
158 chosen in a similar manner to indicate that the utility could be found,
159 but not invoked. Some scripts produce meaningful error messages differ‐
160 entiating the 126 and 127 cases. The distinction between exit codes 126
161 and 127 is based on KornShell practice that uses 127 when all attempts
162 to exec the utility fail with [ENOENT], and uses 126 when any attempt
163 to exec the utility fails for any other reason.
164
166 None.
167
169 Due to the text about the limits of the nice value being implementa‐
170 tion-defined, nice is not actually required to change the nice value of
171 the executed command; the limits could be zero differences from the
172 system default, although the implementor is required to document this
173 fact in the conformance document.
174 The 4.3 BSD version of nice does not check whether increment is a valid
176 decimal integer. The command nice -x utility, for example, would be
177 treated the same as the command nice --1 utility. If the user does not
178 have appropriate privileges, this results in a "permission denied"
179 error. This is considered a bug.
180 When a user without appropriate privileges gives a negative increment,
182 System V treats it like the command nice -0 utility, while 4.3 BSD
183 writes a "permission denied" message and does not run the utility. Nei‐
184 ther was considered clearly superior, so the behavior was left unspeci‐
185 fied.
186 The C shell has a built-in version of nice that has a different inter‐
188 face from the one described in this volume of IEEE Std 1003.1-2001.
189 The term "utility" is used, rather than "command", to highlight the
191 fact that shell compound commands, pipelines, and so on, cannot be
192 used. Special built-ins also cannot be used. However, "utility"
193 includes user application programs and shell scripts, not just utili‐
194 ties defined in this volume of IEEE Std 1003.1-2001.
195 Historical implementations of nice provide a nice value range of 40 or
197 41 discrete steps, with the default nice value being the midpoint of
198 that range. By default, they lower the nice value of the executed util‐
199 ity by 10.
200 Some historical documentation states that the increment value must be
202 within a fixed range. This is misleading; the valid increment values on
203 any invocation are determined by the current process nice value, which
204 is not always the default.
205 The definition of nice value is not intended to suggest that all pro‐
207 cesses in a system have priorities that are comparable. Scheduling
208 policy extensions such as the realtime priorities in the System Inter‐
209 faces volume of IEEE Std 1003.1-2001 make the notion of a single under‐
210 lying priority for all scheduling policies problematic. Some implemen‐
211 tations may implement the nice-related features to affect all processes
212 on the system, others to affect just the general time-sharing activi‐
213 ties implied by this volume of IEEE Std 1003.1-2001, and others may
214 have no effect at all. Because of the use of "implementation-defined"
215 in nice and renice, a wide range of implementation strategies are pos‐
216 sible.
217
219 None.
220
222 Shell Command Language, renice, the System Interfaces volume of
223 IEEE Std 1003.1-2001, nice()
224
226 Portions of this text are reprinted and reproduced in electronic form
227 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
228 -- Portable Operating System Interface (POSIX), The Open Group Base
229 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
230 Electrical and Electronics Engineers, Inc and The Open Group. In the
231 event of any discrepancy between this version and the original IEEE and
232 The Open Group Standard, the original IEEE and The Open Group Standard
233 is the referee document. The original Standard can be obtained online
234 at http://www.opengroup.org/unix/online.html .
235IEEE/The Open Group 2003 NICE(1P)