1NICE(1P)                   POSIX Programmer's Manual                  NICE(1P)
2
3
4

PROLOG

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
11

NAME

13       nice — invoke a utility with an altered nice value
14

SYNOPSIS

16       nice [−n increment] utility [argument...]
17

DESCRIPTION

19       The nice utility shall invoke a utility, requesting that it be run with
20       a   different   nice   value   (see  the  Base  Definitions  volume  of
21       POSIX.1‐2008, Section 3.240, Nice Value).  With no  options,  the  exe‐
22       cuted  utility  shall be run with a nice value that is some implementa‐
23       tion-defined quantity greater than or equal to the nice  value  of  the
24       current process. If the user lacks appropriate privileges to affect the
25       nice value in the requested manner, the nice utility shall  not  affect
26       the nice value; in this case, a warning message may be written to stan‐
27       dard error, but this shall not prevent the  invocation  of  utility  or
28       affect the exit status.
29

OPTIONS

31       The  nice  utility  shall  conform  to  the  Base Definitions volume of
32       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
33
34       The following option is supported:
35
36       −n increment
37                 A positive or negative decimal integer which shall  have  the
38                 same effect on the execution of the utility as if the utility
39                 had called the nice() function with the numeric value of  the
40                 increment option-argument.
41

OPERANDS

43       The following operands shall be supported:
44
45       utility   The  name  of a utility that is to be invoked. If the utility
46                 operand names any of the special built-in utilities  in  Sec‐
47                 tion  2.14, Special Built-In Utilities, the results are unde‐
48                 fined.
49
50       argument  Any string to be supplied as an argument  when  invoking  the
51                 utility named by the utility operand.
52

STDIN

54       Not used.
55

INPUT FILES

57       None.
58

ENVIRONMENT VARIABLES

60       The following environment variables shall affect the execution of nice:
61
62       LANG      Provide  a  default  value for the internationalization vari‐
63                 ables that are unset or null. (See the Base Definitions  vol‐
64                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
65                 ables for the precedence  of  internationalization  variables
66                 used to determine the values of locale categories.)
67
68       LC_ALL    If  set  to  a non-empty string value, override the values of
69                 all the other internationalization variables.
70
71       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
72                 bytes of text data as characters (for example, single-byte as
73                 opposed to multi-byte characters in arguments).
74
75       LC_MESSAGES
76                 Determine the locale that should be used to affect the format
77                 and  contents  of  diagnostic  messages  written  to standard
78                 error.
79
80       NLSPATH   Determine the location of message catalogs for the processing
81                 of LC_MESSAGES.
82
83       PATH      Determine  the  search  path used to locate the utility to be
84                 invoked.  See the Base Definitions  volume  of  POSIX.1‐2008,
85                 Chapter 8, Environment Variables.
86

ASYNCHRONOUS EVENTS

88       Default.
89

STDOUT

91       Not used.
92

STDERR

94       The standard error shall be used only for diagnostic messages.
95

OUTPUT FILES

97       None.
98

EXTENDED DESCRIPTION

100       None.
101

EXIT STATUS

103       If utility is invoked, the exit status of nice shall be the exit status
104       of utility; otherwise, the nice utility shall exit with one of the fol‐
105       lowing values:
106
107       1‐125   An error occurred in the nice utility.
108
109         126   The  utility  specified  by  utility was found but could not be
110               invoked.
111
112         127   The utility specified by utility could not be found.
113

CONSEQUENCES OF ERRORS

115       Default.
116
117       The following sections are informative.
118

APPLICATION USAGE

120       The only guaranteed portable uses of this utility are:
121
122       nice utility
123             Run utility with the default higher or equal nice value.
124
125       nice −n <positive integer> utility
126             Run utility with a higher nice value.
127
128       On some implementations they have no discernible effect on the  invoked
129       utility and on some others they are exactly equivalent.
130
131       Historical  systems have frequently supported the <positive integer> up
132       to 20. Since there is no error penalty associated with guessing a  num‐
133       ber  that  is  too high, users without access to the system conformance
134       document (to see what limits are actually in place) could use the  his‐
135       torical  1  to 20 range or attempt to use very large numbers if the job
136       should be truly low priority.
137
138       The nice value of a process can be displayed using the command:
139
140           ps −o nice
141
142       The command, env, nice, nohup, time,  and  xargs  utilities  have  been
143       specified  to use exit code 127 if an error occurs so that applications
144       can distinguish ``failure to find a utility''  from  ``invoked  utility
145       exited  with an error indication''. The value 127 was chosen because it
146       is not commonly used for other meanings; most utilities use small  val‐
147       ues  for  ``normal  error  conditions'' and the values above 128 can be
148       confused with termination due to receipt of a signal. The value 126 was
149       chosen in a similar manner to indicate that the utility could be found,
150       but not invoked. Some scripts produce meaningful error messages differ‐
151       entiating the 126 and 127 cases. The distinction between exit codes 126
152       and 127 is based on KornShell practice that uses 127 when all  attempts
153       to  exec  the utility fail with [ENOENT], and uses 126 when any attempt
154       to exec the utility fails for any other reason.
155

EXAMPLES

157       None.
158

RATIONALE

160       The 4.3 BSD version of nice does not check whether increment is a valid
161       decimal  integer.  The  command  nice −x utility, for example, would be
162       treated the same as the command nice −−1 utility.  If the user does not
163       have  appropriate  privileges,  this results in a ``permission denied''
164       error.  This is considered a bug.
165
166       When a user without appropriate privileges gives a negative  increment,
167       System  V  treats  it  like  the command nice −0 utility, while 4.3 BSD
168       writes a ``permission denied'' message and does not  run  the  utility.
169       The  standard specifies the System V behavior together with an optional
170       BSD-style ``permission denied'' message.
171
172       The C shell has a built-in version of nice that has a different  inter‐
173       face from the one described in this volume of POSIX.1‐2008.
174
175       The term ``utility'' is used, rather than ``command'', to highlight the
176       fact that shell compound commands, pipelines,  and  so  on,  cannot  be
177       used.  Special  built-ins  also  cannot  be used.  However, ``utility''
178       includes user application programs and shell scripts, not  just  utili‐
179       ties defined in this volume of POSIX.1‐2008.
180
181       Historical  implementations of nice provide a nice value range of 40 or
182       41 discrete steps, with the default nice value being  the  midpoint  of
183       that range. By default, they raise the nice value of the executed util‐
184       ity by 10.
185
186       Some historical documentation states that the increment value  must  be
187       within a fixed range. This is misleading; the valid increment values on
188       any invocation are determined by the current process nice value,  which
189       is not always the default.
190
191       The  definition  of nice value is not intended to suggest that all pro‐
192       cesses in a system have priorities that are comparable. Scheduling pol‐
193       icy extensions such as the realtime priorities in the System Interfaces
194       volume of POSIX.1‐2008 make the notion of a single underlying  priority
195       for  all  scheduling  policies  problematic.  Some  implementations may
196       implement the nice-related features to affect all processes on the sys‐
197       tem,  others to affect just the general time-sharing activities implied
198       by this volume of POSIX.1‐2008, and others may have no effect  at  all.
199       Because  of the use of ``implementation-defined'' in nice and renice, a
200       wide range of implementation strategies are possible.
201
202       Earlier versions of this standard allowed  a  increment  option.  This
203       form  is no longer specified by POSIX.1‐2008 but may be present in some
204       implementations.
205

FUTURE DIRECTIONS

207       None.
208

SEE ALSO

210       Chapter 2, Shell Command Language, renice
211
212       The Base Definitions volume of POSIX.1‐2008, Section 3.240, Nice Value,
213       Chapter  8,  Environment Variables, Section 12.2, Utility Syntax Guide‐
214       lines
215
216       The System Interfaces volume of POSIX.1‐2008, nice()
217
219       Portions of this text are reprinted and reproduced in  electronic  form
220       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
221       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
222       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
223       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
224       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) 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.unix.org/online.html .
229
230       Any  typographical  or  formatting  errors that appear in this page are
231       most likely to have been introduced during the conversion of the source
232       files  to  man page format. To report such errors, see https://www.ker
233       nel.org/doc/man-pages/reporting_bugs.html .
234
235
236
237IEEE/The Open Group                  2013                             NICE(1P)
Impressum