1GETPRIORITY(P)             POSIX Programmer's Manual            GETPRIORITY(P)
2
3
4

NAME

6       getpriority, setpriority - get and set the nice value
7

SYNOPSIS

9       #include <sys/resource.h>
10
11       int getpriority(int which, id_t who);
12       int setpriority(int which, id_t who, int value);
13
14

DESCRIPTION

16       The  getpriority()  function  shall obtain the nice value of a process,
17       process group, or user. The setpriority() function shall set  the  nice
18       value of a process, process group, or user to value+ {NZERO}.
19
20       Target processes are specified by the values of the which and who argu‐
21       ments.  The  which  argument  may  be  one  of  the  following  values:
22       PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, indicating that the who argument
23       is to be interpreted as a process ID, a process group ID, or an  effec‐
24       tive  user  ID, respectively.  A 0 value for the who argument specifies
25       the current process, process group, or user.
26
27       The nice value set with setpriority() shall be applied to the  process.
28       If  the process is multi-threaded, the nice value shall affect all sys‐
29       tem scope threads in the process.
30
31       If more than one process is specified, getpriority() shall return value
32       {NZERO} less than the lowest nice value pertaining to any of the speci‐
33       fied processes, and setpriority() shall set the nice values of  all  of
34       the specified processes to value+ {NZERO}.
35
36       The  default  nice value is {NZERO}; lower nice values shall cause more
37       favorable  scheduling.  While  the  range  of  valid  nice  values   is
38       [0,{NZERO}*2-1],  implementations  may enforce more restrictive limits.
39       If value+ {NZERO} is less  than  the  system's  lowest  supported  nice
40       value,  setpriority()  shall set the nice value to the lowest supported
41       value; if value+ {NZERO} is greater than the system's highest supported
42       nice  value, setpriority() shall set the nice value to the highest sup‐
43       ported value.
44
45       Only a process with appropriate privileges can lower its nice value.
46
47       Any processes or threads using SCHED_FIFO or SCHED_RR  shall  be  unaf‐
48       fected  by  a call to setpriority(). This is not considered an error. A
49       process which subsequently reverts to SCHED_OTHER  need  not  have  its
50       priority affected by such a setpriority() call.
51
52       The  effect  of  changing  the  nice  value  may  vary depending on the
53       process-scheduling algorithm in effect.
54
55       Since getpriority() can return the value -1 on  successful  completion,
56       it  is necessary to set errno to 0 prior to a call to getpriority(). If
57       getpriority() returns the value -1, then errno can be checked to see if
58       an error occurred or if the value is a legitimate nice value.
59

RETURN VALUE

61       Upon  successful  completion,  getpriority() shall return an integer in
62       the range -{NZERO} to {NZERO}-1. Otherwise, -1 shall  be  returned  and
63       errno set to indicate the error.
64
65       Upon successful completion, setpriority() shall return 0; otherwise, -1
66       shall be returned and errno set to indicate the error.
67

ERRORS

69       The getpriority() and setpriority() functions shall fail if:
70
71       ESRCH  No process could be located using the  which  and  who  argument
72              values specified.
73
74       EINVAL The value of the which argument was not recognized, or the value
75              of the who argument is not a valid process ID, process group ID,
76              or user ID.
77
78
79       In addition, setpriority() may fail if:
80
81       EPERM  A  process  was located, but neither the real nor effective user
82              ID of the executing process match the effective user ID  of  the
83              process whose nice value is being changed.
84
85       EACCES A  request  was made to change the nice value to a lower numeric
86              value and the current process does not have  appropriate  privi‐
87              leges.
88
89
90       The following sections are informative.
91

EXAMPLES

93   Using getpriority()
94       The  following  example returns the current scheduling priority for the
95       process ID returned by the call to getpid().
96
97
98              #include <sys/resource.h>
99              ...
100              int which = PRIO_PROCESS;
101              id_t pid;
102              int ret;
103
104
105              pid = getpid();
106              ret = getpriority(which, pid);
107
108   Using setpriority()
109       The following example sets the priority for the current process  ID  to
110       -20.
111
112
113              #include <sys/resource.h>
114              ...
115              int which = PRIO_PROCESS;
116              id_t pid;
117              int priority = -20;
118              int ret;
119
120
121              pid = getpid();
122              ret = setpriority(which, pid, priority);
123

APPLICATION USAGE

125       The  getpriority() and setpriority() functions work with an offset nice
126       value  (nice  value  -{NZERO}).  The  nice  value  is  in   the   range
127       [0,2*{NZERO}  -1],  while  the  return  value for getpriority() and the
128       third parameter for setpriority() are in  the  range  [-{NZERO},{NZERO}
129       -1].
130

RATIONALE

132       None.
133

FUTURE DIRECTIONS

135       None.
136

SEE ALSO

138       nice()  ,  sched_get_priority_max()  ,  sched_setscheduler() , the Base
139       Definitions volume of IEEE Std 1003.1-2001, <sys/resource.h>
140
142       Portions of this text are reprinted and reproduced in  electronic  form
143       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
144       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
145       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
146       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
147       event of any discrepancy between this version and the original IEEE and
148       The Open Group Standard, the original IEEE and The Open Group  Standard
149       is  the  referee document. The original Standard can be obtained online
150       at http://www.opengroup.org/unix/online.html .
151
152
153
154IEEE/The Open Group                  2003                       GETPRIORITY(P)
Impressum