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

NAME

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

SYNOPSIS

15       nice [-n increment] utility [argument...]
16

DESCRIPTION

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       POSIX.1‐2017, Section 3.244, Nice Value).  With no  options,  the  exe‐
21       cuted  utility  shall be run with a nice value that is some implementa‐
22       tion-defined quantity greater than or equal to the nice  value  of  the
23       current process. If the user lacks appropriate privileges to affect the
24       nice value in the requested manner, the nice utility shall  not  affect
25       the nice value; in this case, a warning message may be written to stan‐
26       dard error, but this shall not prevent the  invocation  of  utility  or
27       affect the exit status.
28

OPTIONS

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

OPERANDS

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

STDIN

53       Not used.
54

INPUT FILES

56       None.
57

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

87       Default.
88

STDOUT

90       Not used.
91

STDERR

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

OUTPUT FILES

96       None.
97

EXTENDED DESCRIPTION

99       None.
100

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

119       The only guaranteed portable uses of this utility are:
120
121       nice utility
122             Run utility with the default higher or equal nice value.
123
124       nice -n <positive integer> utility
125             Run utility with a higher nice value.
126
127       On some implementations they have no discernible effect on the  invoked
128       utility and on some others they are exactly equivalent.
129
130       Historical  systems have frequently supported the <positive integer> up
131       to 20. Since there is no error penalty associated with guessing a  num‐
132       ber  that  is  too high, users without access to the system conformance
133       document (to see what limits are actually in place) could use the  his‐
134       torical  1  to 20 range or attempt to use very large numbers if the job
135       should be truly low priority.
136
137       The nice value of a process can be displayed using the command:
138
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‐2017.
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‐2017.
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‐2017 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‐2017, 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‐2017, Section 3.244, Nice Value,
213       Chapter  8,  Environment Variables, Section 12.2, Utility Syntax Guide‐
214       lines
215
216       The System Interfaces volume of POSIX.1‐2017, nice()
217
219       Portions of this text are reprinted and reproduced in  electronic  form
220       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
221       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
222       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
223       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
224       event of any discrepancy between this version and the original IEEE and
225       The Open Group Standard, the original IEEE and The Open Group  Standard
226       is  the  referee document. The original Standard can be obtained online
227       at http://www.opengroup.org/unix/online.html .
228
229       Any typographical or formatting errors that appear  in  this  page  are
230       most likely to have been introduced during the conversion of the source
231       files to man page format. To report such errors,  see  https://www.ker
232       nel.org/doc/man-pages/reporting_bugs.html .
233
234
235
236IEEE/The Open Group                  2017                             NICE(1P)
Impressum