documentation and diagnostic fixes for "nice" and "nice values"

[Paul Eggert]

I noticed that the coreutils documention and usage strings for "nice"
referred to "nice values" in the range of (say) -20 to 19.  But POSIX
says that nice values are nonnegative.  I thought the simplest fix was
to use the word "niceness" to refer to a value in the range -20 to 19,
so that we don't contradict POSIX.  That way, we don't have to mention
"nice values" at all.  I installed this:

2005-09-07  Paul Eggert  <address@hidden>

        Use the phrase "niceness" instead of "nice value" to describe
        the biased nice value that can go negative.  This corrects
        a discrepancy with POSIX, which states that nice values are
        nonnegative.
        * src/nice.c (GET_NICENESS): Renamed from GET_NICE_VALUE.
        All uses changed.
        (usage): Say "niceness" rather than "nice value".
        (main): Say "niceness" rather than "priority" (which is something else
        entirely nowadays).
        * doc/coreutils.texi (nice invocation): Use "niceness", not "nice
        value" to talk about nice values offset by -20.  Don't use the word
        "priority" when niceness is intended.

Index: src/nice.c
===================================================================
RCS file: /fetish/cu/src/nice.c,v
retrieving revision 1.83
diff -p -u -r1.83 nice.c
--- src/nice.c  16 Jun 2005 21:36:48 -0000      1.83
+++ src/nice.c  8 Sep 2005 05:25:58 -0000
@@ -1,4 +1,4 @@
-/* nice -- run a program with modified scheduling priority
+/* nice -- run a program with modified nice value
    Copyright (C) 1990-2005 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
@@ -44,9 +44,9 @@
 #define AUTHORS "David MacKenzie"
 
 #ifdef NICE_PRIORITY
-# define GET_NICE_VALUE() nice (0)
+# define GET_NICENESS() nice (0)
 #else
-# define GET_NICE_VALUE() getpriority (PRIO_PROCESS, 0)
+# define GET_NICENESS() getpriority (PRIO_PROCESS, 0)
 #endif
 
 #ifndef NZERO
@@ -78,11 +78,11 @@ usage (int status)
     {
       printf (_("Usage: %s [OPTION] [COMMAND [ARG]...]\n"), program_name);
       printf (_("\
-Run COMMAND with an adjusted nice value, which affects the scheduling 
priority.\n\
-With no COMMAND, print the current nice value.  Nice values range from\n\
+Run COMMAND with an adjusted niceness, which affects process scheduling.\n\
+With no COMMAND, print the current niceness.  Nicenesses range from\n\
 %d (most favorable scheduling) to %d (least favorable).\n\
 \n\
-  -n, --adjustment=N   add integer N to the nice value (default 10)\n\
+  -n, --adjustment=N   add integer N to the niceness (default 10)\n\
 "),
              - NZERO, NZERO - 1);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
@@ -96,7 +96,7 @@ With no COMMAND, print the current nice 
 int
 main (int argc, char **argv)
 {
-  int current_nice_value;
+  int current_niceness;
   int adjustment = 10;
   char const *adjustment_given = NULL;
   bool ok;
@@ -169,25 +169,25 @@ main (int argc, char **argv)
        }
       /* No command given; print the nice value.  */
       errno = 0;
-      current_nice_value = GET_NICE_VALUE ();
-      if (current_nice_value == -1 && errno != 0)
-       error (EXIT_FAIL, errno, _("cannot get priority"));
-      printf ("%d\n", current_nice_value);
+      current_niceness = GET_NICENESS ();
+      if (current_niceness == -1 && errno != 0)
+       error (EXIT_FAIL, errno, _("cannot get niceness"));
+      printf ("%d\n", current_niceness);
       exit (EXIT_SUCCESS);
     }
 
 #ifndef NICE_PRIORITY
   errno = 0;
-  current_nice_value = GET_NICE_VALUE ();
-  if (current_nice_value == -1 && errno != 0)
-    error (EXIT_FAIL, errno, _("cannot get priority"));
-  ok = (setpriority (PRIO_PROCESS, 0, current_nice_value + adjustment) == 0);
+  current_niceness = GET_NICENESS ();
+  if (current_niceness == -1 && errno != 0)
+    error (EXIT_FAIL, errno, _("cannot get niceness"));
+  ok = (setpriority (PRIO_PROCESS, 0, current_niceness + adjustment) == 0);
 #else
   errno = 0;
   ok = (nice (adjustment) != -1 || errno == 0);
 #endif
   if (!ok)
-    error (errno == EPERM ? 0 : EXIT_FAIL, errno, _("cannot set priority"));
+    error (errno == EPERM ? 0 : EXIT_FAIL, errno, _("cannot set niceness"));
 
   execvp (argv[i], &argv[i]);
 
Index: doc/coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.276
diff -p -u -r1.276 coreutils.texi
--- doc/coreutils.texi.~1.276.~ 2005-08-15 01:41:21.000000000 -0700
+++ doc/coreutils.texi  2005-09-07 22:34:10.000000000 -0700
@@ -79,7 +79,7 @@
 * mkfifo: (coreutils)mkfifo invocation.         Create FIFOs (named pipes).
 * mknod: (coreutils)mknod invocation.           Create special files.
 * mv: (coreutils)mv invocation.                 Rename files.
-* nice: (coreutils)nice invocation.             Modify scheduling priority.
+* nice: (coreutils)nice invocation.             Modify niceness.
 * nl: (coreutils)nl invocation.                 Number lines and write files.
 * nohup: (coreutils)nohup invocation.           Immunize to hangups.
 * od: (coreutils)od invocation.                 Dump files in octal, etc.
@@ -407,7 +407,7 @@ Modified command invocation
 
 * chroot invocation::            Run a command with a different root directory
 * env invocation::               Run a command in a modified environment
-* nice invocation::              Run a command with modified scheduling 
priority
+* nice invocation::              Run a command with modified niceness
 * nohup invocation::             Run a command immune to hangups
 * su invocation::                Run a command with substitute user and group 
ID
 
@@ -12339,7 +12339,7 @@ user, etc.
 @menu
 * chroot invocation::           Modify the root directory.
 * env invocation::              Modify environment variables.
-* nice invocation::             Modify scheduling priority.
+* nice invocation::             Modify niceness.
 * nohup invocation::            Immunize to hangups.
 * su invocation::               Modify user and group ID.
 @end menu
@@ -12491,32 +12491,29 @@ the exit status of @var{command} otherwi
 
 
 @node nice invocation
address@hidden @command{nice}: Run a command with modified scheduling priority
address@hidden @command{nice}: Run a command with modified niceness
 
 @pindex nice
address@hidden nice value
address@hidden modifying scheduling priority
address@hidden scheduling priority, modifying
address@hidden priority, modifying
address@hidden niceness
address@hidden scheduling, affecting
 @cindex appropriate privileges
 
address@hidden prints or modifies a process's @dfn{nice value},
-a parameter that affects the process's scheduling priority.
address@hidden prints or modifies a process's @dfn{niceness},
+a parameter that affects whether the process is scheduled favorably.
 Synopsis:
 
 @example
 nice address@hidden@dots{} address@hidden address@hidden@dots{}]
 @end example
 
-If no arguments are given, @command{nice} prints the current nice
-value, which it inherited.  Otherwise, @command{nice} runs the given
address@hidden with its nice value adjusted.  By default, its nice
-value is incremented by 10.
+If no arguments are given, @command{nice} prints the current niceness.
+Otherwise, @command{nice} runs the given @var{command} with its
+niceness adjusted.  By default, its niceness is incremented by 10.
 
-Nice values range at least from @minus{}20 (resulting in the most
+Nicenesses range at least from @minus{}20 (resulting in the most
 favorable scheduling) through 19 (the least favorable).  Some systems
-may have a wider range of nice values; conversely, other systems may
-enforce more restrictive limits.  An attempt to set the nice value
+may have a wider range of nicenesses; conversely, other systems may
+enforce more restrictive limits.  An attempt to set the niceness
 outside the supported range is treated as an attempt to use the
 minimum or maximum supported value.
 
@@ -12537,7 +12534,7 @@ Options must precede operands.
 @itemx address@hidden
 @opindex -n
 @opindex --adjustment
-Add @var{adjustment} instead of 10 to the command's nice value.  If
+Add @var{adjustment} instead of 10 to the command's niceness.  If
 @var{adjustment} is negative and you lack appropriate privileges,
 @command{nice} issues a warning but otherwise acts as if you specified
 a zero adjustment.
@@ -12552,23 +12549,23 @@ option syntax @address@hidden
 Exit status:
 
 @display
-0   if no @var{command} is specified and the current priority is output
+0   if no @var{command} is specified and the niceness is output
 1   if @command{nice} itself fails
 126 if @var{command} is found but cannot be invoked
 127 if @var{command} cannot be found
 the exit status of @var{command} otherwise
 @end display
 
-It is sometimes useful to run non-interactive programs with reduced priority.
+It is sometimes useful to run a non-interactive program with reduced niceness.
 
 @example
 $ nice factor 4611686018427387903
 @end example
 
-Since @command{nice} prints the current priority,
+Since @command{nice} prints the current niceness,
 you can invoke it through itself to demonstrate how it works.
 
-The default behavior is to increase the nice value by @samp{10}:
+The default behavior is to increase the niceness by @samp{10}:
 
 @example
 $ nice
@@ -12579,17 +12576,17 @@ $ nice -n 10 nice
 10
 @end example
 
-The @var{adjustment} is relative to the current nice value.  In the
+The @var{adjustment} is relative to the current niceness.  In the
 next example, the first @command{nice} invocation runs the second one
-with nice value 10, and it in turn runs the final one with a nice
-value that is 3 more:
+with niceness 10, and it in turn runs the final one with a niceness
+that is 3 more:
 
 @example
 $ nice nice -n 3 nice
 13
 @end example
 
-Specifying a nice value larger than the supported range
+Specifying a niceness larger than the supported range
 is the same as specifying the maximum supported value:
 
 @example
@@ -12597,11 +12594,11 @@ $ nice -n 10000000000 nice
 19
 @end example
 
-Only a privileged user may run a process with higher priority:
+Only a privileged user may run a process with lower niceness:
 
 @example
 $ nice -n -1 nice
-nice: cannot set priority: Permission denied
+nice: cannot set niceness: Permission denied
 0
 $ sudo nice -n -1 nice
 -1
@@ -12646,8 +12643,8 @@ descriptor as the (possibly-redirected) 
 
 @command{nohup} does not automatically put the command it runs in the
 background; you must do that explicitly, by ending the command line
-with an @samp{&}.  Also, @command{nohup} does not change the
-scheduling priority of @var{command}; use @command{nice} for that,
+with an @samp{&}.  Also, @command{nohup} does not alter the
+niceness of @var{command}; use @command{nice} for that,
 e.g., @samp{nohup nice @var{command}}.
 
 @var{command} must not be a special built-in utility (@pxref{Special