lib/libc/sys/rtprio.2

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