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

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