lib/libc/sys/getpriority.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getpriority.2       8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 4, 1993
  32 .Dt GETPRIORITY 2
  33 .Os
  34 .Sh NAME
  35 .Nm getpriority ,
  36 .Nm setpriority
  37 .Nd get/set program scheduling priority
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/time.h
  42 .In sys/resource.h
  43 .Ft int
  44 .Fn getpriority "int which" "int who"
  45 .Ft int
  46 .Fn setpriority "int which" "int who" "int prio"
  47 .Sh DESCRIPTION
  48 The scheduling
  49 priority of the process, process group, or user, as indicated by
  50 .Fa which
  51 and
  52 .Fa who
  53 is obtained with the
  54 .Fn getpriority
  55 system call and set with the
  56 .Fn setpriority
  57 system call.
  58 The
  59 .Fa which
  60 argument
  61 is one of
  62 .Dv PRIO_PROCESS ,
  63 .Dv PRIO_PGRP ,
  64 or
  65 .Dv PRIO_USER ,
  66 and
  67 .Fa who
  68 is interpreted relative to
  69 .Fa which
  70 (a process identifier for
  71 .Dv PRIO_PROCESS ,
  72 process group
  73 identifier for
  74 .Dv PRIO_PGRP ,
  75 and a user ID for
  76 .Dv PRIO_USER ) .
  77 A zero value of
  78 .Fa who
  79 denotes the current process, process group, or user.
  80 The
  81 .Fa prio
  82 argument
  83 is a value in the range -20 to 20.
  84 The default priority is 0;
  85 lower priorities cause more favorable scheduling.
  86 .Pp
  87 The
  88 .Fn getpriority
  89 system call returns the highest priority (lowest numerical value)
  90 enjoyed by any of the specified processes.
  91 The
  92 .Fn setpriority
  93 system call sets the priorities of all of the specified processes
  94 to the specified value.
  95 Only the super-user may lower priorities.
  96 .Sh RETURN VALUES
  97 Since
  98 .Fn getpriority
  99 can legitimately return the value -1, it is necessary
 100 to clear the external variable
 101 .Va errno
 102 prior to the
 103 call, then check it afterward to determine
 104 if a -1 is an error or a legitimate value.
 105 .Pp
 106 .Rv -std setpriority
 107 .Sh ERRORS
 108 The
 109 .Fn getpriority
 110 and
 111 .Fn setpriority
 112 system calls
 113 will fail if:
 114 .Bl -tag -width Er
 115 .It Bq Er ESRCH
 116 No process was located using the
 117 .Fa which
 118 and
 119 .Fa who
 120 values specified.
 121 .It Bq Er EINVAL
 122 The
 123 .Fa which
 124 argument
 125 was not one of
 126 .Dv PRIO_PROCESS ,
 127 .Dv PRIO_PGRP ,
 128 or
 129 .Dv PRIO_USER .
 130 .El
 131 .Pp
 132 In addition to the errors indicated above,
 133 .Fn setpriority
 134 will fail if:
 135 .Bl -tag -width Er
 136 .It Bq Er EPERM
 137 A process was located, but neither its effective nor real user
 138 ID matched the effective user ID of the caller.
 139 .It Bq Er EACCES
 140 A non super-user attempted to lower a process priority.
 141 .El
 142 .Sh SEE ALSO
 143 .Xr nice 1 ,
 144 .Xr fork 2 ,
 145 .Xr renice 8
 146 .Sh HISTORY
 147 The
 148 .Fn getpriority
 149 system call appeared in
 150 .Bx 4.2 .