logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

getpriority.3p (6150B)

    

  1. '\" et
  2. .TH GETPRIORITY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. getpriority,
  12. setpriority
  13. \(em get and set the nice value
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/resource.h>
  18. .P
  19. int getpriority(int \fIwhich\fP, id_t \fIwho\fP);
  20. int setpriority(int \fIwhich\fP, id_t \fIwho\fP, int \fIvalue\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIgetpriority\fR()
  25. function shall obtain the nice value of a process, process group, or
  26. user. The
  27. \fIsetpriority\fR()
  28. function shall set the nice value of a process, process group, or user
  29. to
  30. .IR value +\c
  31. {NZERO}.
  32. .P
  33. Target processes are specified by the values of the
  34. .IR which
  35. and
  36. .IR who
  37. arguments. The
  38. .IR which
  39. argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP,
  40. or PRIO_USER, indicating that the
  41. .IR who
  42. argument
  43. is to be interpreted as a process ID, a process group ID, or an
  44. effective user ID, respectively. A 0 value for the
  45. .IR who
  46. argument specifies the current process, process group, or user.
  47. .P
  48. The nice value set with
  49. \fIsetpriority\fR()
  50. shall be applied to the process. If the process is multi-threaded,
  51. the nice value shall affect all system scope threads in the process.
  52. .P
  53. If more than one process is specified,
  54. \fIgetpriority\fR()
  55. shall return value
  56. {NZERO}
  57. less than the lowest nice value pertaining to any of the specified
  58. processes, and
  59. \fIsetpriority\fR()
  60. shall set the nice values of all of the specified processes to
  61. .IR value +\c
  62. {NZERO}.
  63. .P
  64. The default nice value is
  65. {NZERO};
  66. lower nice values shall cause more favorable scheduling. While the
  67. range of valid nice values is [0,{NZERO}*2\-1], implementations may
  68. enforce more restrictive limits. If
  69. .IR value +\c
  70. {NZERO}
  71. is less than the system's lowest supported nice value,
  72. \fIsetpriority\fR()
  73. shall set the nice value to the lowest supported value; if
  74. .IR value +\c
  75. {NZERO}
  76. is greater than the system's highest supported nice value,
  77. \fIsetpriority\fR()
  78. shall set the nice value to the highest supported value.
  79. .P
  80. Only a process with appropriate privileges can lower its nice value.
  81. .P
  82. Any processes or threads using SCHED_FIFO or SCHED_RR shall be
  83. unaffected by a call to
  84. \fIsetpriority\fR().
  85. This is not considered an error. A process which subsequently reverts
  86. to SCHED_OTHER need not have its priority affected by such a
  87. \fIsetpriority\fR()
  88. call.
  89. .P
  90. The effect of changing the nice value may vary depending on the
  91. process-scheduling algorithm in effect.
  92. .P
  93. Since
  94. \fIgetpriority\fR()
  95. can return the value \-1 upon successful completion, it is necessary to
  96. set
  97. .IR errno
  98. to 0 prior to a call to
  99. \fIgetpriority\fR().
  100. If
  101. \fIgetpriority\fR()
  102. returns the value \-1, then
  103. .IR errno
  104. can be checked to see if an error occurred or if the value is a
  105. legitimate nice value.
  106. .SH "RETURN VALUE"
  107. Upon successful completion,
  108. \fIgetpriority\fR()
  109. shall return an integer in the range \-{NZERO} to
  110. {NZERO}\-1.
  111. Otherwise, \-1 shall be returned and
  112. .IR errno
  113. set to indicate the error.
  114. .P
  115. Upon successful completion,
  116. \fIsetpriority\fR()
  117. shall return 0; otherwise, \-1 shall be returned and
  118. .IR errno
  119. set to indicate the error.
  120. .br
  121. .SH ERRORS
  122. The
  123. \fIgetpriority\fR()
  124. and
  125. \fIsetpriority\fR()
  126. functions shall fail if:
  127. .TP
  128. .BR ESRCH
  129. No process could be located using the
  130. .IR which
  131. and
  132. .IR who
  133. argument values specified.
  134. .TP
  135. .BR EINVAL
  136. The value of the
  137. .IR which
  138. argument was not recognized, or the value of the
  139. .IR who
  140. argument is not a valid process ID, process group ID, or user ID.
  141. .P
  142. In addition,
  143. \fIsetpriority\fR()
  144. may fail if:
  145. .TP
  146. .BR EPERM
  147. A process was located, but neither the real nor effective user ID of
  148. the executing process match the effective user ID of the process whose
  149. nice value is being changed.
  150. .TP
  151. .BR EACCES
  152. A request was made to change the nice value to a lower numeric value
  153. and the current process does not have appropriate privileges.
  154. .LP
  155. .IR "The following sections are informative."
  156. .SH EXAMPLES
  157. .SS "Using getpriority(\|)"
  158. .P
  159. The following example returns the current scheduling priority for the
  160. process ID returned by the call to
  161. \fIgetpid\fR().
  162. .sp
  163. .RS 4
  164. .nf
  166. #include <sys/resource.h>
  167. \&...
  168. int which = PRIO_PROCESS;
  169. id_t pid;
  170. int ret;
  171. .P
  172. pid = getpid();
  173. ret = getpriority(which, pid);
  174. .fi
  175. .P
  176. .RE
  177. .SS "Using setpriority(\|)"
  178. .P
  179. The following example sets the priority for the current process ID to
  180. \-20.
  181. .sp
  182. .RS 4
  183. .nf
  185. #include <sys/resource.h>
  186. \&...
  187. int which = PRIO_PROCESS;
  188. id_t pid;
  189. int priority = -20;
  190. int ret;
  191. .P
  192. pid = getpid();
  193. ret = setpriority(which, pid, priority);
  194. .fi
  195. .P
  196. .RE
  197. .SH "APPLICATION USAGE"
  198. The
  199. \fIgetpriority\fR()
  200. and
  201. \fIsetpriority\fR()
  202. functions work with an offset nice value (nice value \-{NZERO}). The
  203. nice value is in the range [0,2*{NZERO} \-1], while the return value
  204. for
  205. \fIgetpriority\fR()
  206. and the third parameter for
  207. \fIsetpriority\fR()
  208. are in the range [\-{NZERO},{NZERO} \-1].
  209. .SH RATIONALE
  210. None.
  211. .SH "FUTURE DIRECTIONS"
  212. None.
  213. .SH "SEE ALSO"
  214. .IR "\fInice\fR\^(\|)",
  215. .IR "\fIsched_get_priority_max\fR\^(\|)",
  216. .IR "\fIsched_setscheduler\fR\^(\|)"
  217. .P
  218. The Base Definitions volume of POSIX.1\(hy2017,
  219. .IR "\fB<sys_resource.h>\fP"
  220. .\"
  221. .SH COPYRIGHT
  222. Portions of this text are reprinted and reproduced in electronic form
  223. from IEEE Std 1003.1-2017, Standard for Information Technology
  224. -- Portable Operating System Interface (POSIX), The Open Group Base
  225. Specifications Issue 7, 2018 Edition,
  226. Copyright (C) 2018 by the Institute of
  227. Electrical and Electronics Engineers, Inc and The Open Group.
  228. In the event of any discrepancy between this version and the original IEEE and
  229. The Open Group Standard, the original IEEE and The Open Group Standard
  230. is the referee document. The original Standard can be obtained online at
  231. http://www.opengroup.org/unix/online.html .
  232. .PP
  233. Any typographical or formatting errors that appear
  234. in this page are most likely
  235. to have been introduced during the conversion of the source files to
  236. man page format. To report such errors, see
  237. https://www.kernel.org/doc/man-pages/reporting_bugs.html .