1GETRLIMIT(2)               Linux Programmer's Manual              GETRLIMIT(2)
2
3
4

NAME

6       getrlimit, setrlimit, prlimit - get/set resource limits
7

SYNOPSIS

9       #include <sys/time.h>
10       #include <sys/resource.h>
11
12       int getrlimit(int resource, struct rlimit *rlim);
13       int setrlimit(int resource, const struct rlimit *rlim);
14
15       int prlimit(pid_t pid, int resource, const struct rlimit *new_limit,
16                   struct rlimit *old_limit);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       prlimit(): _GNU_SOURCE
21

DESCRIPTION

23       The  getrlimit() and setrlimit() system calls get and set resource lim‐
24       its.  Each resource has an associated soft and hard limit,  as  defined
25       by the rlimit structure:
26
27           struct rlimit {
28               rlim_t rlim_cur;  /* Soft limit */
29               rlim_t rlim_max;  /* Hard limit (ceiling for rlim_cur) */
30           };
31
32       The  soft  limit  is  the value that the kernel enforces for the corre‐
33       sponding resource.  The hard limit acts  as  a  ceiling  for  the  soft
34       limit:  an  unprivileged process may set only its soft limit to a value
35       in the range from 0 up to the hard limit, and (irreversibly) lower  its
36       hard   limit.    A  privileged  process  (under  Linux:  one  with  the
37       CAP_SYS_RESOURCE capability in the initial  user  namespace)  may  make
38       arbitrary changes to either limit value.
39
40       The  value  RLIM_INFINITY  denotes  no limit on a resource (both in the
41       structure returned by getrlimit() and in the structure passed to  setr‐
42       limit()).
43
44       The resource argument must be one of:
45
46       RLIMIT_AS
47              This  is  the  maximum  size  of  the  process's  virtual memory
48              (address space).  The  limit  is  specified  in  bytes,  and  is
49              rounded  down to the system page size.  This limit affects calls
50              to brk(2), mmap(2), and mremap(2), which  fail  with  the  error
51              ENOMEM  upon exceeding this limit.  In addition, automatic stack
52              expansion fails (and generates a SIGSEGV that kills the  process
53              if  no  alternate  stack  has  been  made  available via sigalt‐
54              stack(2)).  Since the value is a long, on machines with a 32-bit
55              long  either  this  limit  is at most 2 GiB, or this resource is
56              unlimited.
57
58       RLIMIT_CORE
59              This is the maximum size of a core file (see core(5))  in  bytes
60              that  the  process may dump.  When 0 no core dump files are cre‐
61              ated.  When nonzero, larger dumps are truncated to this size.
62
63       RLIMIT_CPU
64              This is a limit, in seconds, on the amount of CPU time that  the
65              process  can  consume.  When the process reaches the soft limit,
66              it is sent a SIGXCPU signal.  The default action for this signal
67              is to terminate the process.  However, the signal can be caught,
68              and the handler can return control to the main program.  If  the
69              process  continues  to consume CPU time, it will be sent SIGXCPU
70              once per second until the hard limit is reached, at  which  time
71              it  is  sent SIGKILL.  (This latter point describes Linux behav‐
72              ior.  Implementations vary in how  they  treat  processes  which
73              continue  to  consume  CPU  time  after reaching the soft limit.
74              Portable applications that need to catch this signal should per‐
75              form an orderly termination upon first receipt of SIGXCPU.)
76
77       RLIMIT_DATA
78              This is the maximum size of the process's data segment (initial‐
79              ized data, uninitialized data, and heap).  The limit  is  speci‐
80              fied  in  bytes,  and  is  rounded down to the system page size.
81              This limit affects calls to brk(2), sbrk(2),  and  (since  Linux
82              4.7) mmap(2), which fail with the error ENOMEM upon encountering
83              the soft limit of this resource.
84
85       RLIMIT_FSIZE
86              This is the maximum size in bytes of files that the process  may
87              create.   Attempts  to extend a file beyond this limit result in
88              delivery of a SIGXFSZ signal.  By default,  this  signal  termi‐
89              nates a process, but a process can catch this signal instead, in
90              which case the  relevant  system  call  (e.g.,  write(2),  trun‐
91              cate(2)) fails with the error EFBIG.
92
93       RLIMIT_LOCKS (early Linux 2.4 only)
94              This  is  a  limit  on the combined number of flock(2) locks and
95              fcntl(2) leases that this process may establish.
96
97       RLIMIT_MEMLOCK
98              This is the maximum number of bytes of memory that may be locked
99              into  RAM.   This limit is in effect rounded down to the nearest
100              multiple of the system page size.  This limit affects  mlock(2),
101              mlockall(2),  and the mmap(2) MAP_LOCKED operation.  Since Linux
102              2.6.9, it also affects the shmctl(2) SHM_LOCK  operation,  where
103              it  sets  a maximum on the total bytes in shared memory segments
104              (see shmget(2)) that may be locked by the real user  ID  of  the
105              calling process.  The shmctl(2) SHM_LOCK locks are accounted for
106              separately from the  per-process  memory  locks  established  by
107              mlock(2),  mlockall(2),  and  mmap(2)  MAP_LOCKED; a process can
108              lock bytes up to this limit in each of these two categories.
109
110              In Linux kernels before 2.6.9, this limit controlled the  amount
111              of  memory  that could be locked by a privileged process.  Since
112              Linux 2.6.9, no limits are placed on the amount of memory that a
113              privileged  process may lock, and this limit instead governs the
114              amount of memory that an unprivileged process may lock.
115
116       RLIMIT_MSGQUEUE (since Linux 2.6.8)
117              This is a limit on the number of bytes that can be allocated for
118              POSIX  message  queues  for  the  real  user  ID  of the calling
119              process.  This limit is enforced for mq_open(3).   Each  message
120              queue that the user creates counts (until it is removed) against
121              this limit according to the formula:
122
123                  Since Linux 3.5:
124
125                      bytes = attr.mq_maxmsg * sizeof(struct msg_msg) +
126                              min(attr.mq_maxmsg, MQ_PRIO_MAX) *
127                                    sizeof(struct posix_msg_tree_node)+
128                                              /* For overhead */
129                              attr.mq_maxmsg * attr.mq_msgsize;
130                                              /* For message data */
131
132                  Linux 3.4 and earlier:
133
134                      bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) +
135                                              /* For overhead */
136                              attr.mq_maxmsg * attr.mq_msgsize;
137                                              /* For message data */
138
139              where attr is the mq_attr  structure  specified  as  the  fourth
140              argument  to mq_open(3), and the msg_msg and posix_msg_tree_node
141              structures are kernel-internal structures.
142
143              The "overhead" addend in the formula accounts for overhead bytes
144              required  by the implementation and ensures that the user cannot
145              create an unlimited number of zero-length  messages  (such  mes‐
146              sages nevertheless each consume some system memory for bookkeep‐
147              ing overhead).
148
149       RLIMIT_NICE (since Linux 2.6.12, but see BUGS below)
150              This specifies a ceiling to which the process's nice  value  can
151              be  raised  using setpriority(2) or nice(2).  The actual ceiling
152              for the nice value is calculated as 20 - rlim_cur.   The  useful
153              range  for  this  limit  is thus from 1 (corresponding to a nice
154              value of 19) to 40 (corresponding to a nice value of -20).  This
155              unusual  choice  of range was necessary because negative numbers
156              cannot be specified as resource limit values, since  they  typi‐
157              cally  have  special meanings.  For example, RLIM_INFINITY typi‐
158              cally is the same as -1.  For more detail on the nice value, see
159              sched(7).
160
161       RLIMIT_NOFILE
162              This  specifies  a  value  one  greater  than  the  maximum file
163              descriptor number that can be opened by this process.   Attempts
164              (open(2), pipe(2), dup(2), etc.)  to exceed this limit yield the
165              error EMFILE.  (Historically, this limit was named  RLIMIT_OFILE
166              on BSD.)
167
168              Since  Linux  4.5, this limit also defines the maximum number of
169              file descriptors that an unprivileged process (one  without  the
170              CAP_SYS_RESOURCE  capability) may have "in flight" to other pro‐
171              cesses, by being passed across UNIX domain sockets.  This  limit
172              applies to the sendmsg(2) system call.  For further details, see
173              unix(7).
174
175       RLIMIT_NPROC
176              This is a limit on the number of extant process (or,  more  pre‐
177              cisely  on  Linux,  threads) for the real user ID of the calling
178              process.  So long as the current number of  processes  belonging
179              to  this process's real user ID is greater than or equal to this
180              limit, fork(2) fails with the error EAGAIN.
181
182              The RLIMIT_NPROC limit is not enforced for processes  that  have
183              either the CAP_SYS_ADMIN or the CAP_SYS_RESOURCE capability.
184
185       RLIMIT_RSS
186              This  is  a  limit (in bytes) on the process's resident set (the
187              number of virtual pages resident in RAM).  This limit has effect
188              only  in  Linux  2.4.x,  x < 30, and there affects only calls to
189              madvise(2) specifying MADV_WILLNEED.
190
191       RLIMIT_RTPRIO (since Linux 2.6.12, but see BUGS)
192              This specifies a ceiling on the real-time priority that  may  be
193              set  for this process using sched_setscheduler(2) and sched_set‐
194              param(2).
195
196              For  further  details  on  real-time  scheduling  policies,  see
197              sched(7)
198
199       RLIMIT_RTTIME (since Linux 2.6.25)
200              This is a limit (in microseconds) on the amount of CPU time that
201              a process scheduled under a real-time scheduling policy may con‐
202              sume  without making a blocking system call.  For the purpose of
203              this limit, each time a process makes a  blocking  system  call,
204              the  count  of  its consumed CPU time is reset to zero.  The CPU
205              time count is not reset if the process continues trying  to  use
206              the  CPU  but  is preempted, its time slice expires, or it calls
207              sched_yield(2).
208
209              Upon reaching the soft limit, the process is sent a SIGXCPU sig‐
210              nal.   If the process catches or ignores this signal and contin‐
211              ues consuming CPU time, then SIGXCPU will be generated once each
212              second  until  the  hard  limit  is  reached, at which point the
213              process is sent a SIGKILL signal.
214
215              The intended use of this limit is to stop  a  runaway  real-time
216              process from locking up the system.
217
218              For  further  details  on  real-time  scheduling  policies,  see
219              sched(7)
220
221       RLIMIT_SIGPENDING (since Linux 2.6.8)
222              This is a limit on the number of signals that may be queued  for
223              the  real  user  ID  of  the calling process.  Both standard and
224              real-time signals are counted for the purpose of  checking  this
225              limit.   However, the limit is enforced only for sigqueue(3); it
226              is always possible to use kill(2) to queue one instance  of  any
227              of the signals that are not already queued to the process.
228
229       RLIMIT_STACK
230              This  is  the maximum size of the process stack, in bytes.  Upon
231              reaching this limit, a SIGSEGV signal is generated.   To  handle
232              this  signal,  a  process  must employ an alternate signal stack
233              (sigaltstack(2)).
234
235              Since Linux 2.6.23, this limit also  determines  the  amount  of
236              space used for the process's command-line arguments and environ‐
237              ment variables; for details, see execve(2).
238
239   prlimit()
240       The Linux-specific prlimit() system call combines and extends the func‐
241       tionality  of  setrlimit() and getrlimit().  It can be used to both set
242       and get the resource limits of an arbitrary process.
243
244       The resource argument has the same meaning as for setrlimit() and getr‐
245       limit().
246
247       If  the  new_limit argument is a not NULL, then the rlimit structure to
248       which it points is used to set new values for the soft and hard  limits
249       for resource.  If the old_limit argument is a not NULL, then a success‐
250       ful call to prlimit() places the previous  soft  and  hard  limits  for
251       resource in the rlimit structure pointed to by old_limit.
252
253       The  pid  argument specifies the ID of the process on which the call is
254       to operate.  If pid is 0, then the call applies to the calling process.
255       To  set or get the resources of a process other than itself, the caller
256       must have the CAP_SYS_RESOURCE capability in the user namespace of  the
257       process  whose  resource  limits are being changed, or the real, effec‐
258       tive, and saved set user IDs of the target process must match the  real
259       user  ID of the caller and the real, effective, and saved set group IDs
260       of the target process must match the real group ID of the caller.
261

RETURN VALUE

263       On success, these system calls return 0.  On error, -1 is returned, and
264       errno is set appropriately.
265

ERRORS

267       EFAULT A  pointer  argument points to a location outside the accessible
268              address space.
269
270       EINVAL The value specified in resource is  not  valid;  or,  for  setr‐
271              limit()   or   prlimit():   rlim->rlim_cur   was   greater  than
272              rlim->rlim_max.
273
274       EPERM  An unprivileged process tried  to  raise  the  hard  limit;  the
275              CAP_SYS_RESOURCE capability is required to do this.
276
277       EPERM  The  caller tried to increase the hard RLIMIT_NOFILE limit above
278              the maximum defined by /proc/sys/fs/nr_open (see proc(5))
279
280       EPERM  (prlimit()) The calling process did not have permission  to  set
281              limits for the process specified by pid.
282
283       ESRCH  Could not find a process with the ID specified in pid.
284

VERSIONS

286       The  prlimit()  system  call  is available since Linux 2.6.36.  Library
287       support is available since glibc 2.13.
288

ATTRIBUTES

290       For  an  explanation  of  the  terms  used   in   this   section,   see
291       attributes(7).
292
293       ┌────────────────────────────────────┬───────────────┬─────────┐
294Interface                           Attribute     Value   
295       ├────────────────────────────────────┼───────────────┼─────────┤
296getrlimit(), setrlimit(), prlimit() │ Thread safety │ MT-Safe │
297       └────────────────────────────────────┴───────────────┴─────────┘
298

CONFORMING TO

300       getrlimit(), setrlimit(): POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
301
302       prlimit(): Linux-specific.
303
304       RLIMIT_MEMLOCK  and  RLIMIT_NPROC derive from BSD and are not specified
305       in POSIX.1; they are present on the BSDs and Linux, but  on  few  other
306       implementations.   RLIMIT_RSS  derives from BSD and is not specified in
307       POSIX.1;  it  is  nevertheless   present   on   most   implementations.
308       RLIMIT_MSGQUEUE,   RLIMIT_NICE,   RLIMIT_RTPRIO,   RLIMIT_RTTIME,   and
309       RLIMIT_SIGPENDING are Linux-specific.
310

NOTES

312       A child process created via fork(2) inherits its parent's resource lim‐
313       its.  Resource limits are preserved across execve(2).
314
315       Resource  limits  are  per-process attributes that are shared by all of
316       the threads in a process.
317
318       Lowering the soft limit for a resource below the process's current con‐
319       sumption  of  that  resource will succeed (but will prevent the process
320       from further increasing its consumption of the resource).
321
322       One can set the resource limits of the shell using the built-in  ulimit
323       command  (limit  in csh(1)).  The shell's resource limits are inherited
324       by the processes that it creates to execute commands.
325
326       Since Linux 2.6.24, the resource limits of any process can be inspected
327       via /proc/[pid]/limits; see proc(5).
328
329       Ancient  systems provided a vlimit() function with a similar purpose to
330       setrlimit().  For backward compatibility, glibc also provides vlimit().
331       All new applications should be written using setrlimit().
332
333   C library/kernel ABI differences
334       Since version 2.13, the glibc getrlimit() and setrlimit() wrapper func‐
335       tions no longer invoke the  corresponding  system  calls,  but  instead
336       employ prlimit(), for the reasons described in BUGS.
337
338       The  name  of  the  glibc wrapper function is prlimit(); the underlying
339       system call is prlimit64().
340

BUGS

342       In older Linux kernels, the SIGXCPU and SIGKILL signals delivered  when
343       a  process  encountered the soft and hard RLIMIT_CPU limits were deliv‐
344       ered one (CPU) second later than they should have been.  This was fixed
345       in kernel 2.6.8.
346
347       In  2.6.x  kernels  before  2.6.17,  a RLIMIT_CPU limit of 0 is wrongly
348       treated as "no limit" (like RLIM_INFINITY).  Since Linux  2.6.17,  set‐
349       ting  a  limit  of  0 does have an effect, but is actually treated as a
350       limit of 1 second.
351
352       A kernel bug means that RLIMIT_RTPRIO does not work in  kernel  2.6.12;
353       the problem is fixed in kernel 2.6.13.
354
355       In kernel 2.6.12, there was an off-by-one mismatch between the priority
356       ranges returned by getpriority(2) and RLIMIT_NICE.  This had the effect
357       that   the  actual  ceiling  for  the  nice  value  was  calculated  as
358       19 - rlim_cur.  This was fixed in kernel 2.6.13.
359
360       Since Linux 2.6.12, if a process reaches its soft RLIMIT_CPU limit  and
361       has  a handler installed for SIGXCPU, then, in addition to invoking the
362       signal handler, the kernel increases the  soft  limit  by  one  second.
363       This  behavior  repeats  if  the process continues to consume CPU time,
364       until the hard limit is reached, at which point the process is  killed.
365       Other  implementations  do not change the RLIMIT_CPU soft limit in this
366       manner, and the Linux behavior is probably  not  standards  conformant;
367       portable  applications  should  avoid  relying  on  this Linux-specific
368       behavior.  The Linux-specific RLIMIT_RTTIME  limit  exhibits  the  same
369       behavior when the soft limit is encountered.
370
371       Kernels before 2.4.22 did not diagnose the error EINVAL for setrlimit()
372       when rlim->rlim_cur was greater than rlim->rlim_max.
373
374       Linux doesn't return an error when an attempt  to  set  RLIMIT_CPU  has
375       failed, for compatibility reasons.
376
377   Representation of "large" resource limit values on 32-bit platforms
378       The  glibc  getrlimit()  and setrlimit() wrapper functions use a 64-bit
379       rlim_t data type, even on 32-bit platforms.  However, the  rlim_t  data
380       type used in the getrlimit() and setrlimit() system calls is a (32-bit)
381       unsigned long.  Furthermore, in Linux, the kernel  represents  resource
382       limits  on  32-bit  platforms as unsigned long.  However, a 32-bit data
383       type  is  not  wide  enough.   The  most  pertinent   limit   here   is
384       RLIMIT_FSIZE,  which  specifies  the  maximum  size to which a file can
385       grow: to be useful, this limit must be represented using a type that is
386       as  wide as the type used to represent file offsets—that is, as wide as
387       a 64-bit off_t (assuming a program compiled with _FILE_OFFSET_BITS=64).
388
389       To work around this kernel limitation, if a  program  tried  to  set  a
390       resource  limit  to  a value larger than can be represented in a 32-bit
391       unsigned long, then the glibc  setrlimit()  wrapper  function  silently
392       converted  the  limit  value  to  RLIM_INFINITY.   In  other words, the
393       requested resource limit setting was silently ignored.
394
395       Since version 2.13, glibc works around the  limitations  of  the  getr‐
396       limit()  and  setrlimit()  system calls by implementing setrlimit() and
397       getrlimit() as wrapper functions that call prlimit().
398

EXAMPLE

400       The program below demonstrates the use of prlimit().
401
402       #define _GNU_SOURCE
403       #define _FILE_OFFSET_BITS 64
404       #include <stdio.h>
405       #include <time.h>
406       #include <stdlib.h>
407       #include <unistd.h>
408       #include <sys/resource.h>
409
410       #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
411                               } while (0)
412
413       int
414       main(int argc, char *argv[])
415       {
416           struct rlimit old, new;
417           struct rlimit *newp;
418           pid_t pid;
419
420           if (!(argc == 2 || argc == 4)) {
421               fprintf(stderr, "Usage: %s <pid> [<new-soft-limit> "
422                       "<new-hard-limit>]\n", argv[0]);
423               exit(EXIT_FAILURE);
424           }
425
426           pid = atoi(argv[1]);        /* PID of target process */
427
428           newp = NULL;
429           if (argc == 4) {
430               new.rlim_cur = atoi(argv[2]);
431               new.rlim_max = atoi(argv[3]);
432               newp = &new;
433           }
434
435           /* Set CPU time limit of target process; retrieve and display
436              previous limit */
437
438           if (prlimit(pid, RLIMIT_CPU, newp, &old) == -1)
439               errExit("prlimit-1");
440           printf("Previous limits: soft=%lld; hard=%lld\n",
441                   (long long) old.rlim_cur, (long long) old.rlim_max);
442
443           /* Retrieve and display new CPU time limit */
444
445           if (prlimit(pid, RLIMIT_CPU, NULL, &old) == -1)
446               errExit("prlimit-2");
447           printf("New limits: soft=%lld; hard=%lld\n",
448                   (long long) old.rlim_cur, (long long) old.rlim_max);
449
450           exit(EXIT_SUCCESS);
451       }
452

SEE ALSO

454       prlimit(1), dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2),
455       open(2),   quotactl(2),  sbrk(2),  shmctl(2),  malloc(3),  sigqueue(3),
456       ulimit(3), core(5), capabilities(7), cgroups(7),  credentials(7),  sig‐
457       nal(7)
458

COLOPHON

460       This  page  is  part of release 5.02 of the Linux man-pages project.  A
461       description of the project, information about reporting bugs,  and  the
462       latest     version     of     this    page,    can    be    found    at
463       https://www.kernel.org/doc/man-pages/.
464
465
466
467Linux                             2018-04-30                      GETRLIMIT(2)
Impressum