Debian Codegraph @

upstream/debian-unstable/man2/nice.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH nice 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 nice \- change process priority
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <unistd.h>
15 .P
16 .BI "int nice(int " inc );
17 .fi
18 .P
19 .RS -4
20 Feature Test Macro Requirements for glibc (see
21 .BR feature_test_macros (7)):
22 .RE
23 .P
24 .BR nice ():
25 .nf
26 _XOPEN_SOURCE
27 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
28 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
29 .fi
30 .SH DESCRIPTION
31 .BR nice ()
32 adds
33 .I inc
34 to the nice value for the calling thread.
35 (A higher nice value means a lower priority.)
36 .P
37 The range of the nice value is +19 (low priority) to \-20 (high priority).
38 Attempts to set a nice value outside the range are clamped to the range.
39 .P
40 Traditionally, only a privileged process could lower the nice value
41 (i.e., set a higher priority).
42 However, since Linux 2.6.12,
43 an unprivileged process can decrease
44 the nice value of a target process that has a suitable
45 .B RLIMIT_NICE
46 soft limit;
47 see
48 .BR getrlimit (2)
49 for details.
50 .SH RETURN VALUE
51 On success, the new nice value is returned (but see VERSIONS below).
52 On error, \-1 is returned, and
53 .I errno
54 is set to indicate the error.
55 .P
56 A successful call can legitimately return \-1.
57 To detect an error, set
58 .I errno
59 to 0 before the call, and check whether it is nonzero after
60 .BR nice ()
61 returns \-1.
62 .SH ERRORS
63 .TP
64 .B EPERM
65 The calling process attempted to increase its priority by
66 supplying a negative
67 .I inc
68 but has insufficient privileges.
69 Under Linux, the
70 .B CAP_SYS_NICE
71 capability is required.
72 (But see the discussion of the
73 .B RLIMIT_NICE
74 resource limit in
75 .BR setrlimit (2).)
76 .SH VERSIONS
77 .SS C library/kernel differences
78 POSIX.1 specifies that
79 .BR nice ()
80 should return the new nice value.
81 However, the raw Linux system call returns 0 on success.
82 Likewise, the
83 .BR nice ()
84 wrapper function provided in glibc 2.2.3 and earlier returns 0 on success.
85 .P
86 Since glibc 2.2.4, the
87 .BR nice ()
88 wrapper function provided by glibc provides conformance to POSIX.1 by calling
89 .BR getpriority (2)
90 to obtain the new nice value, which is then returned to the caller.
91 .SH STANDARDS
92 POSIX.1-2024.
93 .SH HISTORY
94 POSIX.1-2001, SVr4, 4.3BSD.
95 .\" SVr4 documents an additional
96 .\" .B EINVAL
97 .\" error code.
98 .SH NOTES
99 For further details on the nice value, see
100 .BR sched (7).
101 .P
102 .IR Note :
103 the addition of the "autogroup" feature in Linux 2.6.38 means that
104 the nice value no longer has its traditional effect in many circumstances.
105 For details, see
106 .BR sched (7).
107 .SH SEE ALSO
108 .BR nice (1),
109 .BR renice (1),
110 .BR fork (2),
111 .BR getpriority (2),
112 .BR getrlimit (2),
113 .BR setpriority (2),
114 .BR capabilities (7),
115 .BR sched (7)