Re: Man Page Simple Error: GETPRIORITY(2)
From: Michael Kerrisk (man-pages) <hidden>
Date: 2016-07-02 08:22:22
Hello Robin, On 06/30/2016 12:35 AM, Robin Kuzmin wrote:
http://man7.org/linux/man-pages/man2/getpriority.2.html 2015-07-23 1. What I see: "lower priorities cause more favorable scheduling". What I expect: "lower values (higher priority) cause more favorable scheduling". 2. What I see: "Only the superuser may lower priorities". What I expect: "Only the superuser may lower values (boost/increase the priorities)". 3. What I see: "The caller attempted to lower a process priority". What I expect: "The caller attempted to lower a priority value (to increase a priority)". 4. Add to section "SEE ALSO" the reference to "nice(2)" - http://man7.org/linux/man-pages/man2/nice.2.html Why I think so: The man page GETPRIORITY(2) should be in synch with nice(2) http://man7.org/linux/man-pages/man2/nice.2.html Both getpriority(2) and nice(2) are referred by sched(7) section "SCHED_OTHER: Default Linux time-sharing scheduling" - http://man7.org/linux/man-pages/man7/sched.7.html.
Thanks for the note. The text could indeed be better. I've made various changes, including your suggestions. See the diff below. Thanks for the report. Cheers, Michael
--- a/man2/getpriority.2
+++ b/man2/getpriority.2@@ -64,6 +64,9 @@ is obtained with the call and set with the .BR setpriority () call. +The process attribute dealt with by these system calls is +the same attribute (also known as the "nice" value) that is dealt with by +.BR nice (2). The value .I which
@@ -87,11 +90,13 @@ A zero value for .I who denotes (respectively) the calling process, the process group of the calling process, or the real user ID of the calling process. + The .I prio argument is a value in the range \-20 to 19 (but see NOTES below). +with \-20 being the highest priority and 19 being the lowest priority. The default priority is 0; -lower priorities cause more favorable scheduling. +lower values give a process a higher scheduling priority. The .BR getpriority ()
@@ -101,7 +106,15 @@ The .BR setpriority () call sets the priorities of all of the specified processes to the specified value. -Only the superuser may lower priorities. + +Traditionally, only a privileged process could lower the nice value +(i.e., set a higher priority). +However, since Linux 2.6.12, an unprivileged process can decrease +the nice value of a target process that has a suitable +.BR RLIMIT_NICE +soft limit; see +.BR getrlimit (2) +for details. .SH RETURN VALUE Since .BR getpriority ()
@@ -137,16 +150,11 @@ In addition to the errors indicated above, may fail if: .TP .B EACCES -The caller attempted to lower a process priority, but did not +The caller attempted to set a lower nice value +(i.e., a higher process priority), but did not have the required privilege (on Linux: did not have the .B CAP_SYS_NICE capability). -Since Linux 2.6.12, this error occurs only if the caller attempts -to set a process priority outside the range of the -.B RLIMIT_NICE -soft resource limit of the target process; see -.BR getrlimit (2) -for details. .TP .B EPERM A process was located, but its effective user ID did not match
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html