lib/libc/sys/getpriority.2

   1 .\"     $NetBSD: getpriority.2,v 1.18 2009/03/11 13:39:14 joerg 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 25, 2004
  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 .Fa which
  59 is one of
  60 .Dv PRIO_PROCESS ,
  61 .Dv PRIO_PGRP ,
  62 or
  63 .Dv PRIO_USER ,
  64 and
  65 .Fa who
  66 is interpreted relative to
  67 .Fa which
  68 (a process identifier for
  69 .Dv PRIO_PROCESS ,
  70 process group
  71 identifier for
  72 .Dv PRIO_PGRP ,
  73 and a user ID for
  74 .Dv PRIO_USER ) .
  75 A zero value of
  76 .Fa who
  77 denotes the current process, process group, or user.
  78 .Fa prio
  79 is a value in the range -20 to 20.
  80 The default priority is 0;
  81 lower priorities cause more favorable scheduling.
  82 A value of 19 or 20
  83 will schedule a process only when nothing at priority \*(Le 0 is runnable.
  84 .Pp
  85 The
  86 .Fn getpriority
  87 call returns the highest priority (lowest numerical value)
  88 enjoyed by any of the specified processes.
  89 The
  90 .Fn setpriority
  91 call sets the priorities of all of the specified processes
  92 to the specified value.
  93 Only the super-user may lower priorities.
  94 .Sh RETURN VALUES
  95 Since
  96 .Fn getpriority
  97 can legitimately return the value \-1, it is necessary
  98 to clear the external variable
  99 .Va errno
 100 prior to the
 101 call, then check it afterward to determine
 102 if a \-1 is an error or a legitimate value.
 103 The
 104 .Fn setpriority
 105 call returns 0 if there is no error, or
 106 \-1 if there is.
 107 .Sh ERRORS
 108 .Fn getpriority
 109 and
 110 .Fn setpriority
 111 will fail if:
 112 .Bl -tag -width Er
 113 .It Bq Er ESRCH
 114 No process was located using the
 115 .Fa which
 116 and
 117 .Fa who
 118 values specified.
 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 .El
 127 .Pp
 128 In addition to the errors indicated above,
 129 .Fn setpriority
 130 will fail if:
 131 .Bl -tag -width Er
 132 .It Bq Er EPERM
 133 A process was located, but neither its effective nor real user
 134 ID matched the effective user ID of the caller.
 135 .It Bq Er EACCES
 136 A non super-user attempted to lower a process priority.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr nice 1 ,
 140 .Xr fork 2 ,
 141 .Xr renice 8
 142 .Sh HISTORY
 143 The
 144 .Fn getpriority
 145 function call appeared in
 146 .Bx 4.2 .