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 <delphij@FreeBSD.org> 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.Dd December 8, 2021 55.Dt RTPRIO 2 56.Os 57.Sh NAME 58.Nm rtprio , 59.Nm rtprio_thread 60.Nd examine or modify realtime or idle priority 61.Sh LIBRARY 62.Lb libc 63.Sh SYNOPSIS 64.In sys/types.h 65.In sys/rtprio.h 66.Ft int 67.Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" 68.Ft int 69.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp" 70.Sh DESCRIPTION 71The 72.Fn rtprio 73system call 74is used to lookup or change the realtime or idle priority of a process, 75or the calling thread. 76The 77.Fn rtprio_thread 78system call 79is used to lookup or change the realtime or idle priority of a thread. 80.Pp 81The 82.Fa function 83argument 84specifies the operation to be performed. 85RTP_LOOKUP to lookup the current priority, 86and RTP_SET to set the priority. 87.Pp 88For the 89.Fn rtprio 90system call, 91the 92.Fa pid 93argument 94specifies the process to operate on, 950 for the calling thread. 96When 97.Fa pid 98is non-zero, 99the system call reports the highest priority in the process, 100or sets all threads' priority in the process, 101depending on value of the 102.Fa function 103argument. 104.Pp 105For the 106.Fn rtprio_thread 107system call, 108the 109.Fa lwpid 110specifies the thread to operate on, 1110 for the calling thread. 112.Pp 113The 114.Fa *rtp 115argument 116is a pointer to a struct rtprio which is used to specify the priority and priority type. 117This structure has the following form: 118.Bd -literal 119struct rtprio { 120 u_short type; 121 u_short prio; 122}; 123.Ed 124.Pp 125The value of the 126.Va type 127field may be RTP_PRIO_REALTIME for realtime priorities, 128RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. 129The priority specified by the 130.Va prio 131field ranges between 0 and 132.Dv RTP_PRIO_MAX 133.Pq usually 31 . 1340 is the highest possible priority. 135.Pp 136Realtime and idle priority is inherited through 137.Fn fork 138and 139.Fn exec . 140.Pp 141A realtime thread can only be preempted by a thread of equal or 142higher priority, or by an interrupt; idle priority threads will run only 143when no other real/normal priority thread is runnable. 144Higher real/idle priority threads 145preempt lower real/idle priority threads. 146Threads of equal real/idle priority are run round-robin. 147.Sh RETURN VALUES 148.Rv -std rtprio rtprio_thread 149.Sh ERRORS 150The 151.Fn rtprio 152and 153.Fn rtprio_thread 154system calls 155will fail if: 156.Bl -tag -width Er 157.It Bq Er EFAULT 158The rtp pointer passed to 159.Fn rtprio 160or 161.Fn rtprio_thread 162was invalid. 163.It Bq Er EINVAL 164The specified 165.Fa prio 166was out of range. 167.It Bq Er EPERM 168The calling thread is not allowed to set the priority. 169Only 170root is allowed to change the realtime or idle priority of any thread. 171Exceptional privileges can be granted through the 172.Xr mac_priority 4 173policy and the realtime and idletime user groups. 174The 175.Xr sysctl 8 176variable 177.Va security.bsd.unprivileged_idprio 178is deprecated. 179If set to non-zero, it lets any user change the idle priority of threads 180they own. 181.It Bq Er ESRCH 182The specified process or thread was not found or visible. 183.El 184.Sh SEE ALSO 185.Xr nice 1 , 186.Xr ps 1 , 187.Xr rtprio 1 , 188.Xr setpriority 2 , 189.Xr nice 3 , 190.Xr mac_priority 4 , 191.Xr renice 8 , 192.Xr p_cansee 9 193.Sh AUTHORS 194.An -nosplit 195The original author was 196.An Henrik Vestergaard Draboel Aq Mt hvd@terry.ping.dk . 197This implementation in 198.Fx 199was substantially rewritten by 200.An David Greenman . 201The 202.Fn rtprio_thread 203system call was implemented by 204.An David Xu . 205