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 respectively.  Each resource has an associated soft and hard limit,
25       as defined 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) may make arbitrary changes to either limit
38       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       Lowering the soft limit for a resource below the process's current con‐
316       sumption of that resource will succeed (but will  prevent  the  process
317       from further increasing its consumption of the resource).
318
319       One  can set the resource limits of the shell using the built-in ulimit
320       command (limit in csh(1)).  The shell's resource limits  are  inherited
321       by the processes that it creates to execute commands.
322
323       Since Linux 2.6.24, the resource limits of any process can be inspected
324       via /proc/[pid]/limits; see proc(5).
325
326       Ancient systems provided a vlimit() function with a similar purpose  to
327       setrlimit().  For backward compatibility, glibc also provides vlimit().
328       All new applications should be written using setrlimit().
329
330   C library/kernel ABI differences
331       Since version 2.13, the glibc getrlimit() and setrlimit() wrapper func‐
332       tions  no  longer  invoke  the  corresponding system calls, but instead
333       employ prlimit(), for the reasons described in BUGS.
334
335       The name of the glibc wrapper function  is  prlimit();  the  underlying
336       system call is prlimit64().
337

BUGS

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

EXAMPLE

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

SEE ALSO

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

COLOPHON

463       This page is part of release 4.15 of the Linux  man-pages  project.   A
464       description  of  the project, information about reporting bugs, and the
465       latest    version    of    this    page,    can     be     found     at
466       https://www.kernel.org/doc/man-pages/.
467
468
469
470Linux                             2017-09-15                      GETRLIMIT(2)
Impressum