Is it just me or is the man page for renice ambiguous?

Question

I am considering renicing some processes so that they will remain responsive under heavy load on a server.

I read the short man page for renice, and I understand it less each time I re-read it. It says it alters the scheduling priority. However, priority is the opposite of niceness so that is surprising given that the command is called renice. Reading further, they discuss scheduling priority in the description section.

Useful priorities are: 19 (the affected processes will run only when nothing else in the system wants to), 0 (the ``base'' scheduling priority), anything negative (to make things go very fast).

This is not in line with a relation between niceness and priority seen in the top command. From man top:

The nice value of the task. A negative nice value means higher priority, whereas a positive nice value means lower priority. Zero in this field simply means priority will not be adjusted in determining a task's dispatch-ability.

In the world of top, priority is the opposite of niceness, and the separate PR field shows the priority value, which is higher for faster running processes.

In the world of renice, priority and niceness are discussed as if they are the same value. In fact, renice -n is apparently equivalent to renice --priority.

The example given in the renice man pages seems like something useful on many systems: Increasing the speed of root processes. However, if I'm not mistaken, it is actually decreasing the speed. I feel it is a misleading, or at least poorly explained example.

Toss in the fact that values are either an increment or a priority, with no command flag differentiating the two. So renice +1 can be used, and so can renice -1. But -1 can be a priority OR an increment, so which is it interpreted as? I can only guess what renice -1 root would do, or determine it experimentally. There seems to be no logical way to determine what this would do from the man page.

Will a "nice" person please explain what command would make root processes run a bit faster, and how I can interpret the man page going forward?

Answer 1

As non-root, I shouldn't be able to get a faster priority. So, indeed a positive number is slower, negative faster:

$ renice -n -10 6341
renice: failed to set priority for 6341 (process ID): Permission denied
$ renice -n +10 6341
6341 (process ID) old priority 0, new priority 10
$ renice -n 0 6341
renice: failed to set priority for 6341 (process ID): Permission denied

That also matches what ps shows, it shows SN+ for that process now (sleeping, nice, in the foreground). The man page describes N as "low-priority (nice to other users)". Giving it a negative number as root turns that into S<+, where < is "high-priority (not nice to other users)"

---

You're right the documentation does look confusing. It doesn't help that the BSDs seem to have essentially the same man page for renice, so it's hard to look there for a better description. The POSIX text doesn't seem to be clear either, it defines the nice value as

3.244 Nice Value
A number used as advice to the system to alter process scheduling. Numerically smaller values give a process additional preference when scheduling a process to run. Numerically larger values reduce the preference and make a process less likely to run.

and then says of renice -n that

Specify how the nice value of the specified process or processes is to be adjusted. The increment option-argument is a positive or negative decimal integer that shall be used to modify the nice value of the specified process or processes.

Positive increment values shall cause a lower nice value. Negative increment values may require appropriate privileges and shall cause a higher nice value.

The second paragraph seems to contradict the nice value definition.