man2/nice.2

   1 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified by Michael Haardt <michael@moria.de>
   6 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
   7 .\" Modified 1996-11-04 by Eric S. Raymond <esr@thyrsus.com>
   8 .\" Modified 2001-06-04 by aeb
   9 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\"
  11 .TH NICE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  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 .PP
  21 .BI "int nice(int " inc );
  22 .fi
  23 .PP
  24 .RS -4
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .RE
  28 .PP
  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 .PP
  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 .PP
  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 .PP
  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 STANDARDS
  80 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
  81 However, the raw system call and (g)libc
  82 (earlier than glibc 2.2.4) return value is nonstandard, see below.
  83 .\" SVr4 documents an additional
  84 .\" .B EINVAL
  85 .\" error code.
  86 .SH NOTES
  87 For further details on the nice value, see
  88 .BR sched (7).
  89 .PP
  90 .IR Note :
  91 the addition of the "autogroup" feature in Linux 2.6.38 means that
  92 the nice value no longer has its traditional effect in many circumstances.
  93 For details, see
  94 .BR sched (7).
  95 .\"
  96 .SS C library/kernel differences
  97 POSIX.1 specifies that
  98 .BR nice ()
  99 should return the new nice value.
 100 However, the raw Linux system call returns 0 on success.
 101 Likewise, the
 102 .BR nice ()
 103 wrapper function provided in glibc 2.2.3 and earlier returns 0 on success.
 104 .PP
 105 Since glibc 2.2.4, the
 106 .BR nice ()
 107 wrapper function provided by glibc provides conformance to POSIX.1 by calling
 108 .BR getpriority (2)
 109 to obtain the new nice value, which is then returned to the caller.
 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)