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
 139 .Fn fork
 140 and
 141 .Fn exec .
 142 .Pp
 143 A realtime thread can only be preempted by a thread of equal or
 144 higher priority, or by an interrupt; idle priority threads will run only
 145 when no other real/normal priority thread is runnable.
 146 Higher real/idle priority threads
 147 preempt lower real/idle priority threads.
 148 Threads of equal real/idle priority are run round-robin.
 149 .Sh RETURN VALUES
 150 .Rv -std rtprio rtprio_thread
 151 .Sh ERRORS
 152 The
 153 .Fn rtprio
 154 and
 155 .Fn rtprio_thread
 156 system calls
 157 will fail if:
 158 .Bl -tag -width Er
 159 .It Bq Er EFAULT
 160 The rtp pointer passed to
 161 .Fn rtprio
 162 or
 163 .Fn rtprio_thread
 164 was invalid.
 165 .It Bq Er EINVAL
 166 The specified
 167 .Fa prio
 168 was out of range.
 169 .It Bq Er EPERM
 170 The calling thread is not allowed to set the realtime priority.
 171 Only
 172 root is allowed to change the realtime priority of any thread, and non-root
 173 may only change the idle priority of threads the user owns,
 174 when the
 175 .Xr sysctl 8
 176 variable
 177 .Va security.bsd.unprivileged_idprio
 178 is set to non-zero.
 179 .It Bq Er ESRCH
 180 The specified process or thread was not found or visible.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr nice 1 ,
 184 .Xr ps 1 ,
 185 .Xr rtprio 1 ,
 186 .Xr setpriority 2 ,
 187 .Xr nice 3 ,
 188 .Xr renice 8 ,
 189 .Xr p_cansee 9
 190 .Sh AUTHORS
 191 .An -nosplit
 192 The original author was
 193 .An Henrik Vestergaard Draboel Aq Mt hvd@terry.ping.dk .
 194 This implementation in
 195 .Fx
 196 was substantially rewritten by
 197 .An David Greenman .
 198 The
 199 .Fn rtprio_thread
 200 system call was implemented by
 201 .An David Xu .