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