1.\"- 2.\" Copyright (c) 1994, Henrik Vestergaard Draboel 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by Henrik Vestergaard Draboel. 16.\" 4. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\"- 31.\" Copyright (c) 2011 Xin LI <[email protected]> 32.\" 33.\" Redistribution and use in source and binary forms, with or without 34.\" modification, are permitted provided that the following conditions 35.\" are met: 36.\" 1. Redistributions of source code must retain the above copyright 37.\" notice, this list of conditions and the following disclaimer. 38.\" 2. Redistributions in binary form must reproduce the above copyright 39.\" notice, this list of conditions and the following disclaimer in the 40.\" documentation and/or other materials provided with the distribution. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 43.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 45.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 46.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 47.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 48.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 50.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 51.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52.\" SUCH DAMAGE. 53.\" 54.\" $FreeBSD$ 55.\" 56.Dd December 27, 2011 57.Dt RTPRIO 2 58.Os 59.Sh NAME 60.Nm rtprio , 61.Nm rtprio_thread 62.Nd examine or modify realtime or idle priority 63.Sh LIBRARY 64.Lb libc 65.Sh SYNOPSIS 66.In sys/types.h 67.In sys/rtprio.h 68.Ft int 69.Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" 70.Ft int 71.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp" 72.Sh DESCRIPTION 73The 74.Fn rtprio 75system call 76is used to lookup or change the realtime or idle priority of a process, 77or the calling thread. 78The 79.Fn rtprio_thread 80system call 81is used to lookup or change the realtime or idle priority of a thread. 82.Pp 83The 84.Fa function 85argument 86specifies the operation to be performed. 87RTP_LOOKUP to lookup the current priority, 88and RTP_SET to set the priority. 89.Pp 90For the 91.Fn rtprio 92system call, 93the 94.Fa pid 95argument 96specifies the process to operate on, 970 for the calling thread. 98When 99.Fa pid 100is non-zero, 101the system call reports the highest priority in the process, 102or sets all threads' priority in the process, 103depending on value of the 104.Fa function 105argument. 106.Pp 107For the 108.Fn rtprio_thread 109system call, 110the 111.Fa lwpid 112specifies the thread to operate on, 1130 for the calling thread. 114.Pp 115The 116.Fa *rtp 117argument 118is a pointer to a struct rtprio which is used to specify the priority and priority type. 119This structure has the following form: 120.Bd -literal 121struct rtprio { 122 u_short type; 123 u_short prio; 124}; 125.Ed 126.Pp 127The value of the 128.Va type 129field may be RTP_PRIO_REALTIME for realtime priorities, 130RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. 131The priority specified by the 132.Va prio 133field ranges between 0 and 134.Dv RTP_PRIO_MAX 135.Pq usually 31 . 1360 is the highest possible priority. 137.Pp 138Realtime and idle priority is inherited through fork() and exec(). 139.Pp 140A realtime thread can only be preempted by a thread of equal or 141higher priority, or by an interrupt; idle priority threads will run only 142when no other real/normal priority thread is runnable. 143Higher real/idle priority threads 144preempt lower real/idle priority threads. 145Threads of equal real/idle priority are run round-robin. 146.Sh RETURN VALUES 147.Rv -std rtprio rtprio_thread 148.Sh ERRORS 149The 150.Fn rtprio 151and 152.Fn rtprio_thread 153system calls 154will fail if: 155.Bl -tag -width Er 156.It Bq Er EFAULT 157The rtp pointer passed to 158.Fn rtprio 159or 160.Fn rtprio_thread 161was invalid. 162.It Bq Er EINVAL 163The specified 164.Fa prio 165was out of range. 166.It Bq Er EPERM 167The calling thread is not allowed to set the realtime priority. 168Only 169root is allowed to change the realtime priority of any thread, and non-root 170may only change the idle priority of threads the user owns, 171when the 172.Xr sysctl 8 173variable 174.Va security.bsd.unprivileged_idprio 175is set to non-zero. 176.It Bq Er ESRCH 177The specified process or thread was not found or visible. 178.El 179.Sh SEE ALSO 180.Xr nice 1 , 181.Xr ps 1 , 182.Xr rtprio 1 , 183.Xr setpriority 2 , 184.Xr nice 3 , 185.Xr renice 8 , 186.Xr p_cansee 9 187.Sh AUTHORS 188.An -nosplit 189The original author was 190.An Henrik Vestergaard Draboel Aq Mt [email protected] . 191This implementation in 192.Fx 193was substantially rewritten by 194.An David Greenman . 195The 196.Fn rtprio_thread 197system call was implemented by 198.An David Xu . 199