bsd/man/man2/getpriority.2

   1 .\"     $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)getpriority.2       8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt GETPRIORITY 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm getpriority ,
  41 .Nm setpriority
  42 .Nd get/set program scheduling priority
  43 .Sh SYNOPSIS
  44 .Fd #include <sys/resource.h>
  45 .Ft int
  46 .Fo getpriority
  47 .Fa "int which"
  48 .Fa "id_t who"
  49 .Fc
  50 .Ft int
  51 .Fo setpriority
  52 .Fa "int which"
  53 .Fa "id_t who"
  54 .Fa "int prio"
  55 .Fc
  56 .Sh DESCRIPTION
  57 The scheduling priority of the process, process group, or user as indicated by
  58 .Fa which
  59 and
  60 .Fa who
  61 is obtained with the
  62 .Fn getpriority
  63 call and set with the
  64 .Fn setpriority
  65 call.
  66 .Fa Which
  67 is one of
  68 .Dv PRIO_PROCESS ,
  69 .Dv PRIO_PGRP ,
  70 or
  71 .Dv PRIO_USER ,
  72 and
  73 .Fa who
  74 is interpreted relative to
  75 .Fa which
  76 (a process identifier for
  77 .Dv PRIO_PROCESS ,
  78 process group
  79 identifier for
  80 .Dv PRIO_PGRP ,
  81 and a user ID for
  82 .Dv PRIO_USER ) .
  83 A zero value of
  84 .Fa who
  85 denotes the current process, process group, or user.
  86 .Fa prio
  87 is a value in the range -20 to 20.  The default priority is 0;
  88 lower priorities cause more favorable scheduling.
  89 .Pp
  90 The
  91 .Fn getpriority
  92 call returns the highest priority (lowest numerical value)
  93 enjoyed by any of the specified processes.
  94 The
  95 .Fn setpriority
  96 call sets the priorities of all of the specified processes
  97 to the specified value.  Only the super-user may lower priorities.
  98 .Pp
  99 Additionally, the current thread or process can be placed in a background state
 100 by specifying PRIO_DARWIN_THREAD or PRIO_DARWIN_PROCESS for
 101 .Fa which .
 102 Only a value of zero (the current thread or process) is supported for
 103 .Fa who
 104 when setting or getting background state.
 105 .Fa prio
 106 is either 0 (to remove current thread from background status) or PRIO_DARWIN_BG
 107 (to set current thread into background state).
 108 When a thread or process is in a background state the scheduling priority is set
 109 to the lowest value, disk IO is throttled (with behavior similar to using
 110 .Xr setiopolicy_np 3
 111 to set a throttleable policy), and network IO is throttled for
 112 any sockets opened after going into background state.  Any previously opened
 113 sockets are not affected.
 114 The
 115 .Fn getpriority
 116 call returns 0 when current thread or process is not in background state or 1
 117 when the current thread is in background state.  Any thread or process can set
 118 itself into background state.
 119 .Sh RETURN VALUES
 120 Since
 121 .Fn getpriority
 122 can legitimately return the value -1, it is necessary
 123 to clear the external variable
 124 .Va errno
 125 prior to the
 126 call, then check it afterward to determine
 127 if a -1 is an error or a legitimate value.
 128 The
 129 .Fn setpriority
 130 call returns 0 if there is no error, or
 131 -1 if there is.
 132 .Sh ERRORS
 133 .Fn Getpriority
 134 and
 135 .Fn setpriority
 136 will fail if:
 137 .Bl -tag -width Er
 138 .\" ==========
 139 .It Bq Er EINVAL
 140 .Fa Which
 141 is not one of
 142 .Dv PRIO_PROCESS ,
 143 .Dv PRIO_PGRP ,
 144 .Dv PRIO_USER ,
 145 .Dv PRIO_DARWIN_THREAD ,
 146 or
 147 .Dv PRIO_DARWIN_PROCESS .
 148 .\" ==========
 149 .It Bq Er EINVAL
 150 .Fa Who
 151 is not a valid process, process group, or user ID.
 152 .\" ==========
 153 .It Bq Er EINVAL
 154 .Fa Who
 155 is not 0 when
 156 .Fa which
 157 is
 158 .Dv PRIO_DARWIN_THREAD
 159 or
 160 .Dv PRIO_DARWIN_PROCESS .
 161 .\" ==========
 162 .It Bq Er ESRCH
 163 No process can be located using the
 164 .Fa which
 165 and
 166 .Fa who
 167 values specified.
 168 .El
 169 .Pp
 170 .Bl -tag -width Er
 171 In addition to the errors indicated above,
 172 .Fn setpriority
 173 will fail if:
 174 .\" ==========
 175 .It Bq Er EACCES
 176 A non super-user attempts to lower a process priority.
 177 .\" ==========
 178 .It Bq Er EPERM
 179 A process is located,
 180 but neither its effective nor real user ID
 181 matches the effective user ID of the caller.
 182 .El
 183 .Sh LEGACY SYNOPSIS
 184 .Fd #include <sys/types.h>
 185 .Fd #include <sys/resource.h>
 186 .Pp
 187 The include file
 188 .In sys/types.h
 189 is necessary.
 190 .Pp
 191 .Ft int
 192 .br
 193 .Fo getpriority
 194 .Fa "int which"
 195 .Fa "int who"
 196 .Fc ;
 197 .Pp
 198 .Ft int
 199 .br
 200 .Fo setpriority
 201 .Fa "int which"
 202 .Fa "int who"
 203 .Fa "int value"
 204 .Fc ;
 205 .Pp
 206 The type of
 207 .Fa who
 208 has changed.
 209 .Sh SEE ALSO
 210 .Xr nice 1 ,
 211 .Xr fork 2 ,
 212 .Xr setiopolicy_np 3 ,
 213 .Xr compat 5 ,
 214 .Xr renice 8
 215 .Sh HISTORY
 216 The
 217 .Fn getpriority
 218 function call appeared in
 219 .Bx 4.2 .