getpriority#

Return the current scheduling nice value of a process, a process group, or a user.

getpriority is a thin wrapper around the getpriority(2) system call. Nice values run from -20 (most favourable to the process) to 19 (least favourable); a freshly-spawned process inherits its parent’s value, typically 0. Only the superuser can lower a nice value; any user may raise their own.

Synopsis#

getpriority WHICH, WHO

WHICH selects what WHO means:

PRIO_PROCESS — WHO is a process ID (0 means the current process).
PRIO_PGRP — WHO is a process-group ID (0 means the current group).
PRIO_USER — WHO is a numeric user ID (0 means the real UID of the calling process).

The three constants come from POSIX; they are not built-ins and are not exported by default.

use POSIX qw(PRIO_PROCESS PRIO_PGRP PRIO_USER);

What you get back#

The current nice value as an integer in the range -20 .. 19.

There is no distinguished error return: -1 is a perfectly valid nice value. To detect failure, clear $! before the call and inspect it afterwards:

$! = 0;
my $nice = getpriority PRIO_PROCESS, $pid;
die "getpriority: $!" if $!;

On a kernel that implements getpriority(2) but returns an error (typically ESRCH for a non-existent target or EINVAL for a bogus WHICH), the function returns -1 with $! set. On a platform that does not implement the call at all, getpriority raises a fatal exception; catch it with eval if the script must run on such a host.

Global state it touches#

$! — set when the underlying getpriority(2) call fails. Must be cleared before the call to distinguish a legitimate -1 result from an error.

Examples#

Read the current process’s own nice value:

use POSIX qw(PRIO_PROCESS);
my $nice = getpriority PRIO_PROCESS, 0;
print "nice = $nice\n";             # nice = 0

Check another process by PID:

use POSIX qw(PRIO_PROCESS);
my $nice = getpriority PRIO_PROCESS, $pid;

Read the priority of the calling process’s process group:

use POSIX qw(PRIO_PGRP);
my $nice = getpriority PRIO_PGRP, 0;

Read the priority cap associated with a user ID. The value returned is the lowest (most favourable) nice value held by any of that user’s processes:

use POSIX qw(PRIO_USER);
my $nice = getpriority PRIO_USER, $uid;

Safe read that distinguishes -1-as-value from -1-as-error:

use POSIX qw(PRIO_PROCESS);
$! = 0;
my $nice = getpriority PRIO_PROCESS, $pid;
if ($!) {
    warn "cannot read priority of $pid: $!";
} else {
    print "pid $pid: nice=$nice\n";
}

Edge cases#

-1 is a valid return, not an error indicator. Always clear $! before the call and test it after.
WHO == 0 is the “self” shorthand for each WHICH: current PID, current PGID, or real UID. Passing your own PID / PGID / UID explicitly gives the same result.
PRIO_USER with a UID that owns multiple processes returns the numerically lowest nice value across those processes, reflecting the most favourable scheduling that user currently enjoys.
Missing target. A PID, PGID, or UID with no matching process yields -1 and sets $! to ESRCH.
Bad WHICH. A value outside PRIO_PROCESS / PRIO_PGRP / PRIO_USER yields -1 and sets $! to EINVAL.
No getpriority(2) on the host. The call raises a fatal exception rather than returning a value. Guard with eval in portable code.
No POSIX import, no constants. Writing getpriority 0, 0 works by accident because PRIO_PROCESS happens to be 0 on Linux, but it is not portable. Always import and use the named constants.
Raising priority needs root. getpriority itself is unprivileged; the matching setpriority call fails with EACCES when a non-root caller tries to decrease the nice value.

Differences from upstream#

Fully compatible with upstream Perl 5.42.