getpriority

SYNOPSIS
       #include <sys/resource.h>

       int getpriority(int which, id_t who);
       int setpriority(int which, id_t who, int value);


DESCRIPTION
       The  getpriority()  function  shall obtain the nice value of a process,
       process group, or user. The setpriority() function shall set  the  nice
       value of a process, process group, or user to value+ {NZERO}.

       Target processes are specified by the values of the which and who argu-
       ments.  The  which  argument  may  be  one  of  the  following  values:
       PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, indicating that the who argument
       is to be interpreted as a process ID, a process group ID, or an  effec-
       tive  user  ID, respectively.  A 0 value for the who argument specifies
       the current process, process group, or user.

       The nice value set with setpriority() shall be applied to the  process.
       If  the process is multi-threaded, the nice value shall affect all sys-
       tem scope threads in the process.

       If more than one process is specified, getpriority() shall return value
       {NZERO} less than the lowest nice value pertaining to any of the speci-
       fied processes, and setpriority() shall set the nice values of  all  of
       the specified processes to value+ {NZERO}.

       The  default  nice value is {NZERO}; lower nice values shall cause more
       favorable  scheduling.  While  the  range  of  valid  nice  values   is
       [0,{NZERO}*2-1],  implementations  may enforce more restrictive limits.
       If value+ {NZERO} is less  than  the  system's  lowest  supported  nice
       value,  setpriority()  shall set the nice value to the lowest supported
       value; if value+ {NZERO} is greater than the system's highest supported
       nice  value, setpriority() shall set the nice value to the highest sup-
       ported value.

       Only a process with appropriate privileges can lower its nice value.

       Any processes or threads using SCHED_FIFO or SCHED_RR  shall  be  unaf-
       fected  by  a call to setpriority(). This is not considered an error. A
       process which subsequently reverts to SCHED_OTHER  need  not  have  its
       priority affected by such a setpriority() call.

       The  effect  of  changing  the  nice  value  may  vary depending on the
       process-scheduling algorithm in effect.

       Since getpriority() can return the value -1 on  successful  completion,
       it  is necessary to set errno to 0 prior to a call to getpriority(). If
       getpriority() returns the value -1, then errno can be checked to see if
       an error occurred or if the value is a legitimate nice value.

RETURN VALUE

       EINVAL The value of the which argument was not recognized, or the value
              of the who argument is not a valid process ID, process group ID,
              or user ID.


       In addition, setpriority() may fail if:

       EPERM  A  process  was located, but neither the real nor effective user
              ID of the executing process match the effective user ID  of  the
              process whose nice value is being changed.

       EACCES A  request  was made to change the nice value to a lower numeric
              value and the current process does not have  appropriate  privi-
              leges.


       The following sections are informative.

EXAMPLES
   Using getpriority()
       The  following  example returns the current scheduling priority for the
       process ID returned by the call to getpid().


              #include <sys/resource.h>
              ...
              int which = PRIO_PROCESS;
              id_t pid;
              int ret;


              pid = getpid();
              ret = getpriority(which, pid);

   Using setpriority()
       The following example sets the priority for the current process  ID  to
       -20.


              #include <sys/resource.h>
              ...
              int which = PRIO_PROCESS;
              id_t pid;
              int priority = -20;
              int ret;


              pid = getpid();
              ret = setpriority(which, pid, priority);

APPLICATION USAGE
       The  getpriority() and setpriority() functions work with an offset nice
       value  (nice  value  -{NZERO}).  The  nice  value  is  in   the   range
       Definitions volume of IEEE Std 1003.1-2001, <sys/resource.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                       GETPRIORITY(P)