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 8, 2021 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 139.Fn fork 140and 141.Fn exec . 142.Pp 143A realtime thread can only be preempted by a thread of equal or 144higher priority, or by an interrupt; idle priority threads will run only 145when no other real/normal priority thread is runnable. 146Higher real/idle priority threads 147preempt lower real/idle priority threads. 148Threads of equal real/idle priority are run round-robin. 149.Sh RETURN VALUES 150.Rv -std rtprio rtprio_thread 151.Sh ERRORS 152The 153.Fn rtprio 154and 155.Fn rtprio_thread 156system calls 157will fail if: 158.Bl -tag -width Er 159.It Bq Er EFAULT 160The rtp pointer passed to 161.Fn rtprio 162or 163.Fn rtprio_thread 164was invalid. 165.It Bq Er EINVAL 166The specified 167.Fa prio 168was out of range. 169.It Bq Er EPERM 170The calling thread is not allowed to set the priority. 171Only 172root is allowed to change the realtime or idle priority of any thread. 173Exceptional privileges can be granted through the 174.Xr mac_priority 4 175policy and the realtime and idletime user groups. 176The 177.Xr sysctl 8 178variable 179.Va security.bsd.unprivileged_idprio 180is deprecated. 181If set to non-zero, it lets any user change the idle priority of threads 182they own. 183.It Bq Er ESRCH 184The specified process or thread was not found or visible. 185.El 186.Sh SEE ALSO 187.Xr nice 1 , 188.Xr ps 1 , 189.Xr rtprio 1 , 190.Xr setpriority 2 , 191.Xr nice 3 , 192.Xr mac_priority 4 , 193.Xr renice 8 , 194.Xr p_cansee 9 195.Sh AUTHORS 196.An -nosplit 197The original author was 198.An Henrik Vestergaard Draboel Aq Mt [email protected] . 199This implementation in 200.Fx 201was substantially rewritten by 202.An David Greenman . 203The 204.Fn rtprio_thread 205system call was implemented by 206.An David Xu . 207