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
11

NAME

13       renice — set nice values of running processes
14

SYNOPSIS

16       renice [−g|−p|−u] −n increment ID...
17

DESCRIPTION

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

OPTIONS

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

OPERANDS

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

STDIN

82       Not used.
83

INPUT FILES

85       None.
86

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

113       Default.
114

STDOUT

116       Not used.
117

STDERR

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

OUTPUT FILES

122       None.
123

EXTENDED DESCRIPTION

125       None.
126

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

140       None.
141

EXAMPLES

143        1. Adjust the nice value so that process IDs 987 and 32 would  have  a
144           lower nice value:
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               renice −n −4 −g 324 76
152
153        3. Adjust the nice value so that numeric user ID 8 and user sas  would
154           have a lower nice value:
155
156               renice −n 4 −u 8 sas
157
158       Useful  nice  value  increments  on historical systems include 19 or 20
159       (the affected processes run  only  when  nothing  else  in  the  system
160       attempts  to  run)  and  any  negative  number  (to  make processes run
161       faster).
162

RATIONALE

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

FUTURE DIRECTIONS

210       None.
211

SEE ALSO

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