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 (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
 148 .Sh ERRORS
 149 The
 150 .Fn rtprio
 151 system call
 152 will fail if
 153 .Bl -tag -width Er
 154 .It Bq Er EINVAL
 155 The specified
 156 .Fa prio
 157 was out of range.
 158 .It Bq Er EPERM
 159 The calling thread is not allowed to set the realtime priority.
 160 Only
 161 root is allowed to change the realtime priority of any thread, and non-root
 162 may only change the idle priority of threads the user owns,
 163 when the
 164 .Xr sysctl 8
 165 variable
 166 .Va security.bsd.unprivileged_idprio
 167 is set to non-zero.
 168 .It Bq Er ESRCH
 169 The specified process or thread was not found or visible.
 170 .El
 171 .Sh SEE ALSO
 172 .Xr nice 1 ,
 173 .Xr ps 1 ,
 174 .Xr rtprio 1 ,
 175 .Xr setpriority 2 ,
 176 .Xr nice 3 ,
 177 .Xr renice 8 ,
 178 .Xr p_cansee 9 .
 179 .Sh AUTHORS
 180 .An -nosplit
 181 The original author was
 182 .An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk .
 183 This implementation in
 184 .Fx
 185 was substantially rewritten by
 186 .An David Greenman .
 187 The
 188 .Fn rtprio_thread
 189 system call was implemented by
 190 .An David Xu .