os.nice (or docs) BUG?

[Inconsistent Meowbot]

Roman Suzi <rnd at onego.ru> wrote:

> The following from the Python docs:
> 
>    nice (increment)
>           Add increment to the process's ``niceness''. Return the new
>           niceness. Availability: Unix.
> 
> Contradicts what I see in python 1.5.2 - 2.1:
> 
> >>> import os
> >>> os.nice(1)
> 0
> >>> os.nice(5)
> 0
> 
> (and the process niceness become 6 as reported by top)
> 
> It's docs inaccuracy or os.nice() bug? Or glibc bug?

Both the documentation and posix_nice() itself could use help.

The return value of the nice syscall is platform dependent.  Unix
returns (new nice value - 20), -1 on failure (but see below); while
Linux returns 0 on success, -1 on failure.

On at least some Unix systems, -1 may or may not really be an error,
depending on whether the process priority had been changed beforehand.

So, it looks like the One and Only Real True Way to call nice() is to
set errno to 0, raise an exception only if errno is set after the call
completes, and not to trust the return value to actually mean anything
unless you know what platform you're on and what its nice returns.

Ewwwwwwwww.