1RENICE(1P)                 POSIX Programmer's Manual                RENICE(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       renice — set nice values of running processes
13

SYNOPSIS

15       renice [-g|-p|-u] -n increment ID...
16

DESCRIPTION

18       The renice utility shall request that the nice  values  (see  the  Base
19       Definitions  volume  of POSIX.1‐2017, Section 3.244, Nice Value) of one
20       or more running processes be changed. By default, the  applicable  pro‐
21       cesses  are  specified  by  their  process IDs. When a process group is
22       specified (see -g), the request shall apply to  all  processes  in  the
23       process group.
24
25       The  nice  value  shall be bounded in an implementation-defined manner.
26       If the requested increment would raise or lower the nice value  of  the
27       executed  utility  beyond implementation-defined limits, then the limit
28       whose value was exceeded shall be used.
29
30       When a user is reniced, the request  applies  to  all  processes  whose
31       saved set-user-ID matches the user ID corresponding to the user.
32
33       Regardless  of  which  options are supplied or any other factor, renice
34       shall not alter the nice values of any process unless the user request‐
35       ing such a change has appropriate privileges to do so for the specified
36       process. If the  user  lacks  appropriate  privileges  to  perform  the
37       requested action, the utility shall return an error status.
38
39       The saved set-user-ID of the user's process shall be checked instead of
40       its effective user ID when renice attempts to determine the user ID  of
41       the  process  in  order  to  determine whether the user has appropriate
42       privileges.
43

OPTIONS

45       The renice utility shall conform to  the  Base  Definitions  volume  of
46       POSIX.1‐2017,  Section  12.2,  Utility  Syntax  Guidelines,  except for
47       Guideline 9.
48
49       The following options shall be supported:
50
51       -g        Interpret the following operands as unsigned decimal  integer
52                 process group IDs.
53
54       -n increment
55                 Specify  how  the nice value of the specified process or pro‐
56                 cesses is to be adjusted. The increment option-argument is  a
57                 positive  or  negative  decimal integer that shall be used to
58                 modify the nice value of the specified process or processes.
59
60                 Positive increment values shall cause  a  lower  nice  value.
61                 Negative  increment values may require appropriate privileges
62                 and shall cause a higher nice value.
63
64       -p        Interpret the following operands as unsigned decimal  integer
65                 process  IDs.  The -p option is the default if no options are
66                 specified.
67
68       -u        Interpret the following operands as users. If a  user  exists
69                 with  a  user  name equal to the operand, then the user ID of
70                 that user is used in further processing.  Otherwise,  if  the
71                 operand  represents  an unsigned decimal integer, it shall be
72                 used as the numeric user ID of the user.
73

OPERANDS

75       The following operands shall be supported:
76
77       ID        A process ID, process group ID, or user name/user ID, depend‐
78                 ing on the option selected.
79

STDIN

81       Not used.
82

INPUT FILES

84       None.
85

ENVIRONMENT VARIABLES

87       The  following  environment  variables  shall  affect  the execution of
88       renice:
89
90       LANG      Provide a default value for  the  internationalization  vari‐
91                 ables  that are unset or null. (See the Base Definitions vol‐
92                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
93                 ables  for  the  precedence of internationalization variables
94                 used to determine the values of locale categories.)
95
96       LC_ALL    If set to a non-empty string value, override  the  values  of
97                 all the other internationalization variables.
98
99       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
100                 bytes of text data as characters (for example, single-byte as
101                 opposed to multi-byte characters in arguments).
102
103       LC_MESSAGES
104                 Determine the locale that should be used to affect the format
105                 and contents  of  diagnostic  messages  written  to  standard
106                 error.
107
108       NLSPATH   Determine the location of message catalogs for the processing
109                 of LC_MESSAGES.
110

ASYNCHRONOUS EVENTS

112       Default.
113

STDOUT

115       Not used.
116

STDERR

118       The standard error shall be used only for diagnostic messages.
119

OUTPUT FILES

121       None.
122

EXTENDED DESCRIPTION

124       None.
125

EXIT STATUS

127       The following exit values shall be returned:
128
129        0    Successful completion.
130
131       >0    An error occurred.
132

CONSEQUENCES OF ERRORS

134       Default.
135
136       The following sections are informative.
137

APPLICATION USAGE

139       None.
140

EXAMPLES

142        1. Adjust the nice value so that process IDs 987 and 32 would  have  a
143           lower nice value:
144
145
146               renice -n 5 -p 987 32
147
148        2. Adjust  the  nice  value  so that group IDs 324 and 76 would have a
149           higher nice value, if the user has appropriate privileges to do so:
150
151
152               renice -n -4 -g 324 76
153
154        3. Adjust the nice value so that numeric user ID 8 and user sas  would
155           have a lower nice value:
156
157
158               renice -n 4 -u 8 sas
159
160       Useful  nice  value  increments  on historical systems include 19 or 20
161       (the affected processes run  only  when  nothing  else  in  the  system
162       attempts  to  run)  and  any  negative  number  (to  make processes run
163       faster).
164

RATIONALE

166       The gid, pid, and user specifications do not fit either the  definition
167       of  operand  or  option-argument.  However, for clarity, they have been
168       included in the OPTIONS section, rather than the OPERANDS section.
169
170       The definition of nice value is not intended to suggest that  all  pro‐
171       cesses in a system have priorities that are comparable. Scheduling pol‐
172       icy extensions such as the realtime priorities in the System Interfaces
173       volume  of POSIX.1‐2017 make the notion of a single underlying priority
174       for all  scheduling  policies  problematic.  Some  implementations  may
175       implement the nice-related features to affect all processes on the sys‐
176       tem, others to affect just the general time-sharing activities  implied
177       by  this  volume of POSIX.1‐2017, and others may have no effect at all.
178       Because of the use of ``implementation-defined'' in nice and renice,  a
179       wide range of implementation strategies are possible.
180
181       Originally,  this  utility  was written in the historical manner, using
182       the term ``nice value''. This was always a point of concern with  users
183       because  it was never intuitively obvious what this meant. With a newer
184       version of renice, which used the term ``system scheduling  priority'',
185       it  was hoped that novice users could better understand what this util‐
186       ity was meant to do. Also, it would be  easier  to  document  what  the
187       utility was meant to do. Unfortunately, the addition of the POSIX real‐
188       time scheduling capabilities introduced the  concepts  of  process  and
189       thread  scheduling  priorities  that  were  totally  unaffected  by the
190       nice/renice utilities or the nice()/setpriority() functions. Continuing
191       to  use  the term ``system scheduling priority'' would have incorrectly
192       suggested that these utilities  and  functions  were  indeed  affecting
193       these  realtime  priorities. It was decided to revert to the historical
194       term ``nice value'' to reference this unrelated process attribute.
195
196       Although this utility has use by system  administrators  (and  in  fact
197       appears in the system administration portion of the BSD documentation),
198       the standard developers considered that it was very useful for individ‐
199       ual end users to control their own processes.
200
201       Earlier  versions  of  this standard allowed the following forms in the
202       SYNOPSIS:
203
204
205           renice nice_value[-p] pid...[-g gid...][-p pid...][-u user...]
206           renice nice_value -g gid...[-g gid...]-p pid...][-u user...]
207           renice nice_value -u user...[-g gid...]-p pid...][-u user...]
208
209       These forms are no longer specified by POSIX.1‐2008 but may be  present
210       in some implementations.
211

FUTURE DIRECTIONS

213       None.
214

SEE ALSO

216       nice
217
218       The Base Definitions volume of POSIX.1‐2017, Section 3.244, Nice Value,
219       Chapter 8, Environment Variables, Section 12.2, Utility  Syntax  Guide‐
220       lines
221
223       Portions  of  this text are reprinted and reproduced in electronic form
224       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
225       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
226       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
227       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
228       event of any discrepancy between this version and the original IEEE and
229       The  Open Group Standard, the original IEEE and The Open Group Standard
230       is the referee document. The original Standard can be  obtained  online
231       at http://www.opengroup.org/unix/online.html .
232
233       Any  typographical  or  formatting  errors that appear in this page are
234       most likely to have been introduced during the conversion of the source
235       files  to  man page format. To report such errors, see https://www.ker
236       nel.org/doc/man-pages/reporting_bugs.html .
237
238
239
240IEEE/The Open Group                  2017                           RENICE(1P)
Impressum