lib/libc/sys/getpriority.2

   1 .\"     $NetBSD: getpriority.2,v 1.20 2012/04/13 16:32:15 wiz 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getpriority.2       8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd April 13, 2012
  33 .Dt GETPRIORITY 2
  34 .Os
  35 .Sh NAME
  36 .Nm getpriority ,
  37 .Nm setpriority
  38 .Nd get/set program scheduling priority
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/resource.h
  43 .Ft int
  44 .Fn getpriority "int which" "id_t who"
  45 .Ft int
  46 .Fn setpriority "int which" "id_t 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 call and set with the
  56 .Fn setpriority
  57 call.
  58 .Pp
  59 The priority is maintained in a per-process basis and
  60 affects scheduling of LWPs which belong to the process and use the
  61 .Dv SCHED_OTHER
  62 scheduling class.
  63 .Pp
  64 .Fa which
  65 is one of
  66 .Dv PRIO_PROCESS ,
  67 .Dv PRIO_PGRP ,
  68 or
  69 .Dv PRIO_USER ,
  70 and
  71 .Fa who
  72 is interpreted relative to
  73 .Fa which
  74 (a process identifier for
  75 .Dv PRIO_PROCESS ,
  76 process group
  77 identifier for
  78 .Dv PRIO_PGRP ,
  79 and a user ID for
  80 .Dv PRIO_USER ) .
  81 A zero value of
  82 .Fa who
  83 denotes the current process, process group, or user.
  84 .Fa prio
  85 is a value in the range -20 to 20.
  86 The default priority is 0;
  87 numerically lower priority values cause more favorable scheduling.
  88 A value of 19 or 20
  89 will schedule a process only when nothing at priority \*(Le 0 is runnable.
  90 .Pp
  91 The
  92 .Fn getpriority
  93 call returns the highest priority (lowest numerical value)
  94 enjoyed by any of the specified processes.
  95 The
  96 .Fn setpriority
  97 call sets the priorities of all of the specified processes
  98 to the specified value.
  99 Only the super-user may lower priority values.
 100 .Sh RETURN VALUES
 101 Since
 102 .Fn getpriority
 103 can legitimately return the value \-1, it is necessary
 104 to clear the external variable
 105 .Va errno
 106 prior to the
 107 call, then check it afterward to determine
 108 if a \-1 is an error or a legitimate value.
 109 The
 110 .Fn setpriority
 111 call returns 0 if there is no error, or
 112 \-1 if there is.
 113 .Sh ERRORS
 114 .Fn getpriority
 115 and
 116 .Fn setpriority
 117 will fail if:
 118 .Bl -tag -width Er
 119 .It Bq Er EINVAL
 120 .Fa which
 121 was not one of
 122 .Dv PRIO_PROCESS ,
 123 .Dv PRIO_PGRP ,
 124 or
 125 .Dv PRIO_USER .
 126 .It Bq Er ESRCH
 127 No process was located using the
 128 .Fa which
 129 and
 130 .Fa who
 131 values specified.
 132 .El
 133 .Pp
 134 In addition to the errors indicated above,
 135 .Fn setpriority
 136 will fail if:
 137 .Bl -tag -width Er
 138 .It Bq Er EACCES
 139 A non super-user attempted to lower a process priority value.
 140 .It Bq Er EPERM
 141 A process was located, but neither its effective nor real user
 142 ID matched the effective user ID of the caller.
 143 .El
 144 .Sh SEE ALSO
 145 .Xr nice 1 ,
 146 .Xr fork 2 ,
 147 .Xr sched 3 ,
 148 .Xr renice 8
 149 .Sh HISTORY
 150 The
 151 .Fn getpriority
 152 function call appeared in
 153 .Bx 4.2 .