---
name: getpriority
signature: 'getpriority WHICH, WHO'
since: 5.0
status: documented
categories: ["Processes"]
---

```{index} single: getpriority; Perl built-in
```

*[Processes](../perlfunc-by-category)*

# 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

```perl
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`](../../POSIX); they are not
built-ins and are not exported by default.

```perl
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 [`$!`](../perlvar) before the
call and inspect it afterwards:

```perl
$! = 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 [`$!`](../perlvar) set. On a
platform that does not implement the call at all, `getpriority` raises
a fatal exception; catch it with [`eval`](eval) if the script must run
on such a host.

## Global state it touches

- [`$!`](../perlvar) — 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:

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

Check another process by PID:

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

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

```perl
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:

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

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

```perl
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
  [`$!`](../perlvar) 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 [`$!`](../perlvar) to `ESRCH`.
- **Bad `WHICH`.** A value outside
  `PRIO_PROCESS` / `PRIO_PGRP` / `PRIO_USER` yields `-1` and sets
  [`$!`](../perlvar) to `EINVAL`.
- **No `getpriority(2)` on the host.** The call raises a fatal
  exception rather than returning a value. Guard with
  [`eval`](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`](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.

## See also

- [`setpriority`](setpriority) — write side of the same syscall pair;
  same `WHICH` constants, same caveats about `-1`
- [`POSIX`](../../POSIX) — source of `PRIO_PROCESS`, `PRIO_PGRP`, and
  `PRIO_USER`; none of them are built-in
- [`getpgrp`](getpgrp) — process-group ID you would pass as `WHO`
  under `PRIO_PGRP`
- [`fork`](fork) — child inherits the parent's nice value; read it
  back with `getpriority` after the fork if you need to confirm
- [`$!`](../perlvar) — the only channel for distinguishing a real
  `-1` priority from a failed call