---
name: "getpriority"
section: "2"
platform: "macos"
package: "xnu"
version: "12377.121.6"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/getpriority"
---

# getpriority(2)

get/set program scheduling priority

## NAME

**getpriority**, **setpriority** – get/set program scheduling priority

## SYNOPSIS

**#include \<sys/resource.h\>**

*int*\

**getpriority**(*int which*, *id\_t who*);

*int*\

**setpriority**(*int which*, *id\_t who*, *int prio*);

## DESCRIPTION

The scheduling priority of the process, process group, or user as indicated by *which* and *who* is obtained with the **getpriority**() call and set with the **setpriority**() call. *Which* is one of PRIO\_PROCESS, PRIO\_PGRP, or PRIO\_USER, and  *who* is interpreted relative to  *which* (a process identifier for PRIO\_PROCESS, process group identifier for PRIO\_PGRP, and a user ID for PRIO\_USER). A zero value of *who* denotes the current process, process group, or user. *prio* is a value in the range -20 to 20.  The default priority is 0; lower priorities cause more favorable scheduling.

The **getpriority**() call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The **setpriority**() call sets the priorities of all of the specified processes to the specified value.  Only the super-user may lower priorities.

Additionally, the current thread or process can be placed in a background state by specifying PRIO\_DARWIN\_THREAD or PRIO\_DARWIN\_PROCESS for *which*. Only a value of zero (the current thread or process) is supported for *who* when setting or getting background state. *prio* is either 0 (to remove current thread from background status) or PRIO\_DARWIN\_BG (to set current thread into background state). When a thread or process is in a background state the scheduling priority is set to the lowest value, disk IO is throttled (with behavior similar to using setiopolicy\_np(3) to set a throttleable policy), and network IO is throttled for any sockets opened after going into background state.  Any previously opened sockets are not affected. The **getpriority**() call returns 0 when current thread or process is not in background state or 1 when the current thread is in background state.  Any thread or process can set itself into background state.

## RETURN VALUES

Since **getpriority**() can legitimately return the value -1, it is necessary to clear the external variable *errno* prior to the call, then check it afterward to determine if a -1 is an error or a legitimate value. The **setpriority**() call returns 0 if there is no error, or -1 if there is.

## ERRORS

**getpriority**() and **setpriority**() will fail if:

- \[EINVAL\]

  *Which* is not one of PRIO\_PROCESS, PRIO\_PGRP, PRIO\_USER, PRIO\_DARWIN\_THREAD, or PRIO\_DARWIN\_PROCESS.

- \[EINVAL\]

  *Who* is not a valid process, process group, or user ID.

- \[EINVAL\]

  *Who* is not 0 when *which* is  PRIO\_DARWIN\_THREAD or PRIO\_DARWIN\_PROCESS.

- \[ESRCH\]

  No process can be located using the  *which* and *who* values specified.

- \[EACCES\]

  A non super-user attempts to lower a process priority.

- \[EPERM\]

  A process is located, but neither its effective nor real user ID matches the effective user ID of the caller.

In addition to the errors indicated above, **setpriority**() will fail if:

## LEGACY SYNOPSIS

**#include \<sys/types.h\>** **#include \<sys/resource.h\>**

The include file ⟨sys/types.h⟩ is necessary.

*int*\
 **getpriority**(*int which*, *int who*);

*int*\
 **setpriority**(*int which*, *int who*, *int value*);

The type of *who* has changed.

## SEE ALSO

[nice(1)](/nice/1.md), [fork(2)](/fork/2.md), setiopolicy\_np(3), [compat(5)](/compat/5.md), [renice(8)](/renice/8.md)

## HISTORY

The **getpriority**() function call appeared in 4.2BSD.