getpriority, setpriority, or nice Subroutine

Purpose

Gets or sets the nice value.

Libraries

getpriority, setpriority: Standard C Library (libc.a)

nice: Standard C Library (libc.a)

Berkeley Compatibility Library (libbsd.a)

Syntax

#include <sys/resource.h>

int getpriority( Which, Who) int Which; int Who;

int setpriority(Which, Who, Priority) int Which; int Who; int Priority;

#include <unistd.h>

int nice( Increment) int Increment;

Description

The nice value of the process, process group, or user, as indicated by the Which and Who parameters is obtained with the getpriority subroutine and set with the setpriority subroutine.

The getpriority subroutine returns the highest priority nice value (lowest numerical value) pertaining to any of the specified processes. The setpriority subroutine sets the nice values of all of the specified processes to the specified value. If the specified value is less than -20, a value of -20 is used; if it is greater than 20, a value of 20 is used. Only processes that have root user authority can lower nice values.

The nice subroutine increments the nice value by the value of the Increment parameter.

Note: Nice values are only used for the scheduling policy SCHED_OTHER, where they are combined with a calculation of recent cpu usage to determine the priority value.

To provide upward compatibility with older programs, the nice interface, originally found in AT&T System V, is supported.

Note: Process priorities in AT&T System V are defined in the range of 0 to 39, rather than -20 to 20 as in BSD, and the nice library routine is supported by both. Accordingly, two versions of the nice are supported by AIX® Version 3. The default version behaves like the AT&T System V version, with the Increment parameter treated as the modifier of a value in the range of 0 to 39 (0 corresponds to -20, 39 corresponds to 9, and priority 20 is not reachable with this interface).

If the behavior of the BSD version is desired, compile with the Berkeley Compatibility Library (libbsd.a). The Increment parameter is treated as the modifier of a value in the range -20 to 20.

Parameters

Item	Description
Which	Specifies one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER.
Who	Interpreted relative to the Which parameter (a process identifier, process group identifier, and a user ID, respectively). A zero value for the Who parameter denotes the current process, process group, or user.
Priority	Specifies a value in the range -20 to 20. Negative nice values cause more favorable scheduling.
Increment	Specifies a value that is added to the current process nice value. Negative values can be specified, although values exceeding either the high or low limit are truncated.

Return Values

On successful completion, the getpriority subroutine returns an integer in the range -20 to 20. A return value of -1 can also indicate an error, and in this case the errno global variable is set.

On successful completion, the setpriority subroutine returns 0. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

On successful completion, the nice subroutine returns the new nice value minus {NZERO}. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Note: A value of -1 can also be returned. In that case, the calling process should also check the errno global variable.

Error Codes

The getpriority and setpriority subroutines are unsuccessful if one of the following is true:

Item	Description
ESRCH	No process was located using the Which and Who parameter values specified.
EINVAL	The Which parameter was not recognized.

In addition to the errors indicated above, the setpriority subroutine is unsuccessful if one of the following is true:

Item	Description
EPERM	A process was located, but neither the effective nor real user ID of the caller of the process executing the setpriority subroutine has root user authority.
EACCES	The call to setpriority would have changed the priority of a process to a value lower than its current value, and the effective user ID of the process executing the call did not have root user authority.

The nice subroutine is unsuccessful if the following is true:

Item	Description
EPERM	The Increment parameter is negative and the calling process does not have appropriate privileges.