[PATCH] capabilities.7: typo: lowering niceness is special

[PATCH] capabilities.7: typo: lowering niceness is special

[Dan Kenigsberg]

Anyone can raise the niceness value. Only lowering requires CAP_SYS_NICE.

    $ nice -n +2 nice
    2
    $ nice -n -2 nice
    nice: cannot set niceness: Permission denied
    0
    $ sudo nice -n -2 nice
    -2

Signed-off-by: Dan Kenigsberg <danken@redhat.com>
---
 man7/capabilities.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man7/capabilities.7 b/man7/capabilities.7
index 6254c0ac0..64a9f8e34 100644
--- a/man7/capabilities.7
+++ b/man7/capabilities.7
@@ -527,7 +527,7 @@ drop capabilities from the system-wide capability
bounding set.
 .PD 0
 .RS
 .IP * 2
-Raise process nice value
+Lower process nice value
 .RB ( nice (2),
 .BR setpriority (2))
 and change the nice value for arbitrary processes;
-- 
2.25.4

Re: [PATCH] capabilities.7: typo: lowering niceness is special

[Michael Kerrisk (man-pages)]

Hi Dan,

On 6/11/20 7:13 AM, Dan Kenigsberg wrote:
> Anyone can raise the niceness value. Only lowering requires CAP_SYS_NICE.
> 
>     $ nice -n +2 nice
>     2
>     $ nice -n -2 nice
>     nice: cannot set niceness: Permission denied
>     0
>     $ sudo nice -n -2 nice
>     -2
> 
> Signed-off-by: Dan Kenigsberg <danken@redhat.com>

As I'm sure you're aware, the meaning of the nice value
is always a source of confusion! In writing the original text,
my intent was that the reader would understand that [higher nice
value] == [more negative nice value], but obviously that that
could be ambiguous.

> ---
>  man7/capabilities.7 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man7/capabilities.7 b/man7/capabilities.7
> index 6254c0ac0..64a9f8e34 100644
> --- a/man7/capabilities.7
> +++ b/man7/capabilities.7
> @@ -527,7 +527,7 @@ drop capabilities from the system-wide capability
> bounding set.
>  .PD 0
>  .RS
>  .IP * 2
> -Raise process nice value
> +Lower process nice value
>  .RB ( nice (2),
>  .BR setpriority (2))
>  and change the nice value for arbitrary processes;

I instead applied a differnt patch, as below.
I hope it works for you.

Cheers,

Michael

diff --git a/man7/capabilities.7 b/man7/capabilities.7
index 8f212bead..bf9949ad2 100644
--- a/man7/capabilities.7
+++ b/man7/capabilities.7
@@ -556,7 +556,7 @@ drop capabilities from the system-wide capability bounding set.
 .PD 0
 .RS
 .IP * 2
-Raise process nice value
+Give process a higher (i.e., more negative) nice value
 .RB ( nice (2),
 .BR setpriority (2))
 and change the nice value for arbitrary processes;



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] capabilities.7: typo: lowering niceness is special

[Dan Kenigsberg]

On Wed, Jun 24, 2020 at 1:16 PM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Hi Dan,
>
> On 6/11/20 7:13 AM, Dan Kenigsberg wrote:
> > Anyone can raise the niceness value. Only lowering requires CAP_SYS_NICE.
> >
> >     $ nice -n +2 nice
> >     2
> >     $ nice -n -2 nice
> >     nice: cannot set niceness: Permission denied
> >     0
> >     $ sudo nice -n -2 nice
> >     -2
> >
> > Signed-off-by: Dan Kenigsberg <danken@redhat.com>
>
> As I'm sure you're aware, the meaning of the nice value
> is always a source of confusion! In writing the original text,
> my intent was that the reader would understand that [higher nice
> value] == [more negative nice value], but obviously that that
> could be ambiguous.

Indeed, I'm aware of the old confusion. Some of it stems from people
thinking about this value as a priority. However, it was named
"niceness" because higher value means lesser cpu time. I think that
the man page language should stick to the code and command line
arguments (`nice -n +2` makes the value higher and the process less
likely to run)

>
> > ---
> >  man7/capabilities.7 | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/man7/capabilities.7 b/man7/capabilities.7
> > index 6254c0ac0..64a9f8e34 100644
> > --- a/man7/capabilities.7
> > +++ b/man7/capabilities.7
> > @@ -527,7 +527,7 @@ drop capabilities from the system-wide capability
> > bounding set.
> >  .PD 0
> >  .RS
> >  .IP * 2
> > -Raise process nice value
> > +Lower process nice value
> >  .RB ( nice (2),
> >  .BR setpriority (2))
> >  and change the nice value for arbitrary processes;
>
> I instead applied a differnt patch, as below.
> I hope it works for you.
>
> Cheers,
>
> Michael
>
> diff --git a/man7/capabilities.7 b/man7/capabilities.7
> index 8f212bead..bf9949ad2 100644
> --- a/man7/capabilities.7
> +++ b/man7/capabilities.7
> @@ -556,7 +556,7 @@ drop capabilities from the system-wide capability bounding set.
>  .PD 0
>  .RS
>  .IP * 2
> -Raise process nice value
> +Give process a higher (i.e., more negative) nice value

To me, this suggestion adds to the confusion. Higher numbers are
typically considered "less negative", not more.
How about saying:

Lower process nice value (i.e. make it less nice to other processes)

>  .RB ( nice (2),
>  .BR setpriority (2))
>  and change the nice value for arbitrary processes;
>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
>

Re: [PATCH] capabilities.7: typo: lowering niceness is special

[Michael Kerrisk (man-pages)]

Hello Dan,

On 6/24/20 1:17 PM, Dan Kenigsberg wrote:
> On Wed, Jun 24, 2020 at 1:16 PM Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>>
>> Hi Dan,
>>
>> On 6/11/20 7:13 AM, Dan Kenigsberg wrote:
>>> Anyone can raise the niceness value. Only lowering requires CAP_SYS_NICE.
>>>
>>>     $ nice -n +2 nice
>>>     2
>>>     $ nice -n -2 nice
>>>     nice: cannot set niceness: Permission denied
>>>     0
>>>     $ sudo nice -n -2 nice
>>>     -2
>>>
>>> Signed-off-by: Dan Kenigsberg <danken@redhat.com>
>>
>> As I'm sure you're aware, the meaning of the nice value
>> is always a source of confusion! In writing the original text,
>> my intent was that the reader would understand that [higher nice
>> value] == [more negative nice value], but obviously that that
>> could be ambiguous.
> 
> Indeed, I'm aware of the old confusion. Some of it stems from people
> thinking about this value as a priority. However, it was named
> "niceness" because higher value means lesser cpu time. I think that
> the man page language should stick to the code and command line
> arguments (`nice -n +2` makes the value higher and the process less
> likely to run)
> 
>>
>>> ---
>>>  man7/capabilities.7 | 2 +-
>>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>> diff --git a/man7/capabilities.7 b/man7/capabilities.7
>>> index 6254c0ac0..64a9f8e34 100644
>>> --- a/man7/capabilities.7
>>> +++ b/man7/capabilities.7
>>> @@ -527,7 +527,7 @@ drop capabilities from the system-wide capability
>>> bounding set.
>>>  .PD 0
>>>  .RS
>>>  .IP * 2
>>> -Raise process nice value
>>> +Lower process nice value
>>>  .RB ( nice (2),
>>>  .BR setpriority (2))
>>>  and change the nice value for arbitrary processes;
>>
>> I instead applied a differnt patch, as below.
>> I hope it works for you.
>>
>> Cheers,
>>
>> Michael
>>
>> diff --git a/man7/capabilities.7 b/man7/capabilities.7
>> index 8f212bead..bf9949ad2 100644
>> --- a/man7/capabilities.7
>> +++ b/man7/capabilities.7
>> @@ -556,7 +556,7 @@ drop capabilities from the system-wide capability bounding set.
>>  .PD 0
>>  .RS
>>  .IP * 2
>> -Raise process nice value
>> +Give process a higher (i.e., more negative) nice value
> 
> To me, this suggestion adds to the confusion. Higher numbers are
> typically considered "less negative", not more.
> How about saying:
> 
> Lower process nice value (i.e. make it less nice to other processes)
> 
>>  .RB ( nice (2),
>>  .BR setpriority (2))
>>  and change the nice value for arbitrary processes;

You know what, I think I should have just gone with your original proposal!
And now I've done that. If people are confused, they can read nice(2) and 
sched(7).

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/