Debian Codegraph @

upstream/debian-trixie/man2/nice.2

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