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.\" All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 44.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 45.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 46.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 47.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 48.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 49.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 51.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 52.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 53.\" SUCH DAMAGE. 54.\" 55.\" $FreeBSD$ 56.\" 57.Dd December 27, 2011 58.Dt RTPRIO 2 59.Os 60.Sh NAME 61.Nm rtprio , 62.Nm rtprio_thread 63.Nd examine or modify realtime or idle priority 64.Sh LIBRARY 65.Lb libc 66.Sh SYNOPSIS 67.In sys/types.h 68.In sys/rtprio.h 69.Ft int 70.Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" 71.Ft int 72.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp" 73.Sh DESCRIPTION 74The 75.Fn rtprio 76system call 77is used to lookup or change the realtime or idle priority of a process, 78or the calling thread. 79The 80.Fn rtprio_thread 81system call 82is used to lookup or change the realtime or idle priority of a thread. 83.Pp 84The 85.Fa function 86argument 87specifies the operation to be performed. 88RTP_LOOKUP to lookup the current priority, 89and RTP_SET to set the priority. 90.Pp 91For the 92.Fn rtprio 93system call, 94the 95.Fa pid 96argument 97specifies the process to operate on, 980 for the calling thread. 99When 100.Fa pid 101is non-zero, 102the system call reports the highest priority in the process, 103or sets all threads' priority in the process, 104depending on value of the 105.Fa function 106argument. 107.Pp 108For the 109.Fn rtprio_thread 110system call, 111the 112.Fa lwpid 113specifies the thread to operate on, 1140 for the calling thread. 115.Pp 116The 117.Fa *rtp 118argument 119is a pointer to a struct rtprio which is used to specify the priority and priority type. 120This structure has the following form: 121.Bd -literal 122struct rtprio { 123 u_short type; 124 u_short prio; 125}; 126.Ed 127.Pp 128The value of the 129.Va type 130field may be RTP_PRIO_REALTIME for realtime priorities, 131RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. 132The priority specified by the 133.Va prio 134field ranges between 0 and 135.Dv RTP_PRIO_MAX 136.Pq usually 31 . 1370 is the highest possible priority. 138.Pp 139Realtime and idle priority is inherited through fork() and 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 realtime priority. 169Only 170root is allowed to change the realtime priority of any thread, and non-root 171may only change the idle priority of threads the user owns, 172when the 173.Xr sysctl 8 174variable 175.Va security.bsd.unprivileged_idprio 176is set to non-zero. 177.It Bq Er ESRCH 178The specified process or thread was not found or visible. 179.El 180.Sh SEE ALSO 181.Xr nice 1 , 182.Xr ps 1 , 183.Xr rtprio 1 , 184.Xr setpriority 2 , 185.Xr nice 3 , 186.Xr renice 8 , 187.Xr p_cansee 9 188.Sh AUTHORS 189.An -nosplit 190The original author was 191.An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk . 192This implementation in 193.Fx 194was substantially rewritten by 195.An David Greenman . 196The 197.Fn rtprio_thread 198system call was implemented by 199.An David Xu . 200