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