usr/src/man/man3c/getpriority.3c

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .TH GETPRIORITY 3C "Apr 1, 2008"
  10 .SH NAME
  11 getpriority, setpriority \- get and set the nice value
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <sys/resource.h>
  16
  17 \fBint\fR \fBgetpriority\fR(\fBint\fR \fIwhich\fR, \fBid_t\fR \fIwho\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBsetpriority\fR(\fBint\fR \fIwhich\fR, \fBid_t\fR \fIwho\fR, \fBint\fR \fIvalue\fR);
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBgetpriority()\fR function obtains the nice value of a process, thread,
  29 or set of processes.  The \fBsetpriority()\fR function sets the nice value of a
  30 process, thread, or set of processes to \fIvalue\fR+\fBNZERO\fR, where
  31 \fBNZERO\fR is defined to be 20.
  32 .sp
  33 .LP
  34 Target entities are specified by the values of the \fIwhich\fR and \fIwho\fR
  35 arguments.  The \fIwhich\fR argument can be one of the following values:
  36 \fBPRIO_PROCESS\fR, \fBPRIO_PGRP\fR, \fBPRIO_USER\fR, \fBPRIO_GROUP\fR,
  37 \fBPRIO_SESSION\fR, \fBPRIO_LWP\fR, \fBPRIO_TASK\fR, \fBPRIO_PROJECT\fR,
  38 \fBPRIO_ZONE\fR, or \fBPRIO_CONTRACT\fR, indicating that the \fIwho\fR argument
  39 is to be interpreted as a process ID, a process group ID, an effective user ID,
  40 an effective group ID, a session ID, a thread (lwp) ID, a task ID, a project
  41 ID, a zone ID, or a process contract ID, respectively.  A 0 value for the
  42 \fIwho\fR argument specifies the current process, process group, or user. A 0
  43 value for the \fIwho\fR argument is treated as valid group ID, session ID,
  44 thread (lwp) ID, task ID, project ID, zone ID, or process contract ID. A
  45 \fBP_MYID\fR value for the \fIwho\fR argument can be used to specify the
  46 current group, session, thread, task, project, zone, or process contract,
  47 respectively.
  48 .sp
  49 .LP
  50 If a specified process is multi-threaded, the nice value set with
  51 \fBsetpriority()\fR affects all threads in the process.
  52 .sp
  53 .LP
  54 If more than one process is specified, \fBgetpriority()\fR returns \fBNZERO\fR
  55 less than the lowest nice value pertaining to any of the specified entities,
  56 and \fBsetpriority()\fR sets the nice values of all of the specified processes
  57 to \fIvalue\fR+\fBNZERO\fR.
  58 .sp
  59 .LP
  60 The default nice value is \fBNZERO\fR. Lower nice values cause more favorable
  61 scheduling. The range of valid nice values is 0 to \fBNZERO\fR*2-1. If
  62 \fIvalue\fR+\fBNZERO\fR is less than the system's lowest supported nice value,
  63 \fBsetpriority()\fR sets the nice value to the lowest supported value. If
  64 \fIvalue\fR+\fBNZERO\fR is greater than the system's highest supported nice
  65 value, \fBsetpriority()\fR sets the nice value to the highest supported value.
  66 .sp
  67 .LP
  68 Only a process with appropriate privileges can lower the nice value.
  69 .sp
  70 .LP
  71 Any process or thread using \fBSCHED_FIFO\fR or \fBSCHED_RR\fR is unaffected by
  72 a call to \fBsetpriority()\fR. This is not considered an error. A process or
  73 thread that subsequently reverts to \fBSCHED_OTHER\fR will not have its
  74 priority affected by such a \fBsetpriority()\fR call.
  75 .sp
  76 .LP
  77 The effect of changing the nice value varies depending on the scheduling policy
  78 in effect.
  79 .sp
  80 .LP
  81 Since \fBgetpriority()\fR can return the value -1 on successful completion, it
  82 is necessary to set \fBerrno\fR to 0 prior to a call to \fBgetpriority()\fR. If
  83 \fBgetpriority()\fR returns the value -1, then \fBerrno\fR can be checked to
  84 see if an error occurred or if the value is a legitimate nice value.
  85 .SH RETURN VALUES
  86 .sp
  87 .LP
  88 Upon successful completion, \fBgetpriority()\fR returns an integer in the range
  89 from -\fBNZERO\fR to \fBNZERO\fR-1.  Otherwise, \fB\(mi1\fR is returned and
  90 \fBerrno\fR is set to indicate the error.
  91 .sp
  92 .LP
  93 Upon successful completion, \fBsetpriority()\fR returns \fB0\fR. Otherwise,
  94 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
  95 .SH ERRORS
  96 .sp
  97 .LP
  98 The \fBgetpriority()\fR and \fBsetpriority()\fR functions will fail if:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBESRCH\fR\fR
 103 .ad
 104 .RS 10n
 105 No process or thread could be located using the \fIwhich\fR and \fIwho\fR
 106 argument values specified.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBEINVAL\fR\fR
 113 .ad
 114 .RS 10n
 115 The value of the \fIwhich\fR argument was not recognized, or the value of the
 116 \fIwho\fR argument is not a valid process ID, process group ID, user ID, group
 117 ID, session ID, thread (lwp) ID, task ID, project ID, or zone ID.
 118 .RE
 119
 120 .sp
 121 .LP
 122 In addition, \fBsetpriority()\fR may fail if:
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBEPERM\fR\fR
 127 .ad
 128 .RS 10n
 129 A process was located, but neither the real nor effective user ID of the
 130 executing process match the effective user ID of the process whose nice value
 131 is being changed.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBEACCES\fR\fR
 138 .ad
 139 .RS 10n
 140 A request was made to change the nice value to a lower numeric value and the
 141 current process does not have appropriate privileges.
 142 .RE
 143
 144 .SH EXAMPLES
 145 .LP
 146 \fBExample 1 \fRExample using \fBgetpriority()\fR
 147 .sp
 148 .LP
 149 The following example returns the current scheduling priority for the process
 150 ID returned by the call to \fBgetpid\fR(2).
 151
 152 .sp
 153 .in +2
 154 .nf
 155 #include <sys/resource.h>
 156 \&...
 157 int which = PRIO_PROCESS;
 158 id_t pid;
 159 int ret;
 160
 161 pid = getpid();
 162 ret = getpriority(which, pid);
 163 .fi
 164 .in -2
 165
 166 .LP
 167 \fBExample 2 \fRExample using \fBsetpriority()\fR
 168 .sp
 169 .LP
 170 The following example sets the nice value for the current process to 0.
 171
 172 .sp
 173 .in +2
 174 .nf
 175 #include <sys/resource.h>
 176 \&...
 177 int which = PRIO_PROCESS;
 178 id_t pid;
 179 int value = -20;
 180 int ret;
 181
 182 pid = getpid();
 183 ret = setpriority(which, pid, value);
 184 .fi
 185 .in -2
 186
 187 .SH USAGE
 188 .sp
 189 .LP
 190 The \fBgetpriority()\fR and \fBsetpriority()\fR functions work with an offset
 191 nice value (\fIvalue\fR-\fBNZERO\fR). The nice value is in the range 0 to
 192 2*\fBNZERO\fR-1, while the return value for \fBgetpriority()\fR and the third
 193 parameter for \fBsetpriority()\fR are in the range -\fBNZERO\fR to
 194 \fBNZERO\fR-1.
 195 .SH ATTRIBUTES
 196 .sp
 197 .LP
 198 See \fBattributes\fR(5) for descriptions of the following attributes:
 199 .sp
 200
 201 .sp
 202 .TS
 203 box;
 204 c | c
 205 l | l .
 206 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 207 _
 208 Interface Stability     Committed
 209 _
 210 Standard        See \fBstandards\fR(5).
 211 .TE
 212
 213 .SH SEE ALSO
 214 .sp
 215 .LP
 216 \fBnice\fR(1), \fBrenice\fR(1), \fBsched_get_priority_max\fR(3C),
 217 \fBsched_setscheduler\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)