1getrlimit(2)                  System Calls Manual                 getrlimit(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

267       On success, these system calls return 0.  On error, -1 is returned, and
268       errno is set to indicate the error.
269

ERRORS

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

ATTRIBUTES

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

STANDARDS

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

HISTORY

315       getrlimit()
316       setrlimit()
317              POSIX.1-2001, SVr4, 4.3BSD.
318
319       prlimit()
320              Linux 2.6.36, glibc 2.13.
321

NOTES

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

BUGS

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

EXAMPLES

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

SEE ALSO

463       prlimit(1), dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2),
464       open(2),  quotactl(2),  sbrk(2),  shmctl(2),  malloc(3),   sigqueue(3),
465       ulimit(3),  core(5),  capabilities(7), cgroups(7), credentials(7), sig‐
466       nal(7)
467
468
469
470Linux man-pages 6.05              2023-07-20                      getrlimit(2)
Impressum