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 .\" 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
  74 The
  75 .Fn rtprio
  76 system call
  77 is used to lookup or change the realtime or idle priority of a process,
  78 or the calling thread.
  79 The
  80 .Fn rtprio_thread
  81 system call
  82 is used to lookup or change the realtime or idle priority of a thread.
  83 .Pp
  84 The
  85 .Fa function
  86 argument
  87 specifies the operation to be performed.
  88 RTP_LOOKUP to lookup the current priority,
  89 and RTP_SET to set the priority.
  90 .Pp
  91 For the
  92 .Fn rtprio
  93 system call,
  94 the
  95 .Fa pid
  96 argument
  97 specifies the process to operate on,
  98 0 for the calling thread.
  99 When
 100 .Fa pid
 101 is non-zero,
 102 the system call reports the highest priority in the process,
 103 or sets all threads' priority in the process,
 104 depending on value of the
 105 .Fa function
 106 argument.
 107 .Pp
 108 For the
 109 .Fn rtprio_thread
 110 system call,
 111 the
 112 .Fa lwpid
 113 specifies the thread to operate on,
 114 0 for the calling thread.
 115 .Pp
 116 The
 117 .Fa *rtp
 118 argument
 119 is a pointer to a struct rtprio which is used to specify the priority and priority type.
 120 This structure has the following form:
 121 .Bd -literal
 122 struct rtprio {
 123         u_short type;
 124         u_short prio;
 125 };
 126 .Ed
 127 .Pp
 128 The value of the
 129 .Va type
 130 field may be RTP_PRIO_REALTIME for realtime priorities,
 131 RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities.
 132 The priority specified by the
 133 .Va prio
 134 field ranges between 0 and
 135 .Dv RTP_PRIO_MAX
 136 .Pq usually 31 .
 137 0 is the highest possible priority.
 138 .Pp
 139 Realtime and idle priority is inherited through fork() and 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 realtime priority.
 169 Only
 170 root is allowed to change the realtime priority of any thread, and non-root
 171 may only change the idle priority of threads the user owns,
 172 when the
 173 .Xr sysctl 8
 174 variable
 175 .Va security.bsd.unprivileged_idprio
 176 is set to non-zero.
 177 .It Bq Er ESRCH
 178 The 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
 190 The original author was
 191 .An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk .
 192 This implementation in
 193 .Fx
 194 was substantially rewritten by
 195 .An David Greenman .
 196 The
 197 .Fn rtprio_thread
 198 system call was implemented by
 199 .An David Xu .