# getpriority

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           getpriority, setpriority — get and set the nice value
    


## 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_
           arguments. 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 effective 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 system 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 specified 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 supported value.
    
           Only a process with appropriate privileges can lower its nice
           value.
    
           Any processes or threads using SCHED_FIFO or SCHED_RR shall be
           unaffected 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 upon 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



           Upon successful completion, _getpriority_() shall return an integer
           in the range -{NZERO} to {NZERO}-1.  Otherwise, -1 shall be
           returned and _errno_ set to indicate the error.
    
           Upon successful completion, _setpriority_() shall return 0;
           otherwise, -1 shall be returned and _errno_ set to indicate the
           error.
    


## ERRORS



           The _getpriority_() and _setpriority_() functions shall fail if:
    
           **ESRCH** No process could be located using the _which_ and _who_
                  argument values specified.
    
           **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 privileges.
    
           _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
           [0,2*{NZERO} -1], while the return value for _getpriority_() and the
           third parameter for _setpriority_() are in the range
           [-{NZERO},{NZERO} -1].
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *