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 && _FILE_OFFSET_BITS == 64
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              The maximum size of the process's virtual memory (address space)
48              in bytes.  This limit  affects  calls  to  brk(2),  mmap(2)  and
49              mremap(2),  which fail with the error ENOMEM upon exceeding this
50              limit.  Also automatic stack expansion will fail (and generate a
51              SIGSEGV  that  kills  the process if no alternate stack has been
52              made available via sigaltstack(2)).  Since the value is a  long,
53              on  machines  with  a 32-bit long either this limit is at most 2
54              GiB, or this resource is unlimited.
55
56       RLIMIT_CORE
57              Maximum size of core file.  When 0 no core dump files  are  cre‐
58              ated.  When nonzero, larger dumps are truncated to this size.
59
60       RLIMIT_CPU
61              CPU  time  limit  in seconds.  When the process reaches the soft
62              limit, it is sent a SIGXCPU signal.  The default action for this
63              signal  is to terminate the process.  However, the signal can be
64              caught, and the handler can return control to the main  program.
65              If  the  process  continues to consume CPU time, it will be sent
66              SIGXCPU once per second until the  hard  limit  is  reached,  at
67              which  time  it  is  sent SIGKILL.  (This latter point describes
68              Linux behavior.  Implementations vary in  how  they  treat  pro‐
69              cesses  which  continue  to  consume CPU time after reaching the
70              soft limit.  Portable applications that need to catch this  sig‐
71              nal  should perform an orderly termination upon first receipt of
72              SIGXCPU.)
73
74       RLIMIT_DATA
75              The maximum size of  the  process's  data  segment  (initialized
76              data,  uninitialized  data, and heap).  This limit affects calls
77              to brk(2) and sbrk(2), which fail with  the  error  ENOMEM  upon
78              encountering the soft limit of this resource.
79
80       RLIMIT_FSIZE
81              The maximum size of files that the process may create.  Attempts
82              to extend a file beyond this  limit  result  in  delivery  of  a
83              SIGXFSZ  signal.   By default, this signal terminates a process,
84              but a process can catch this signal instead, in which  case  the
85              relevant  system  call  (e.g., write(2), truncate(2)) fails with
86              the error EFBIG.
87
88       RLIMIT_LOCKS (Early Linux 2.4 only)
89              A limit on the combined number of flock(2)  locks  and  fcntl(2)
90              leases that this process may establish.
91
92       RLIMIT_MEMLOCK
93              The  maximum  number  of bytes of memory that may be locked into
94              RAM.  In effect this limit is rounded down to the nearest multi‐
95              ple  of  the  system page size.  This limit affects mlock(2) and
96              mlockall(2) and the mmap(2) MAP_LOCKED operation.   Since  Linux
97              2.6.9 it also affects the shmctl(2) SHM_LOCK operation, where it
98              sets a maximum on the total bytes in shared memory segments (see
99              shmget(2)) that may be locked by the real user ID of the calling
100              process.  The shmctl(2) SHM_LOCK locks are accounted  for  sepa‐
101              rately   from   the  per-process  memory  locks  established  by
102              mlock(2), mlockall(2), and mmap(2)  MAP_LOCKED;  a  process  can
103              lock bytes up to this limit in each of these two categories.  In
104              Linux kernels before 2.6.9, this limit controlled the amount  of
105              memory  that  could  be  locked  by a privileged process.  Since
106              Linux 2.6.9, no limits are placed on the amount of memory that a
107              privileged  process may lock, and this limit instead governs the
108              amount of memory that an unprivileged process may lock.
109
110       RLIMIT_MSGQUEUE (Since Linux 2.6.8)
111              Specifies the limit on the number of bytes that can be allocated
112              for  POSIX  message  queues  for the real user ID of the calling
113              process.  This limit is enforced for mq_open(3).   Each  message
114              queue that the user creates counts (until it is removed) against
115              this limit according to the formula:
116
117                  bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) +
118                          attr.mq_maxmsg * attr.mq_msgsize
119
120              where attr is the mq_attr  structure  specified  as  the  fourth
121              argument to mq_open(3).
122
123              The  first  addend  in the formula, which includes sizeof(struct
124              msg_msg *) (4 bytes on Linux/i386), ensures that the user cannot
125              create  an  unlimited  number of zero-length messages (such mes‐
126              sages nevertheless each consume some system memory for bookkeep‐
127              ing overhead).
128
129       RLIMIT_NICE (since Linux 2.6.12, but see BUGS below)
130              Specifies  a  ceiling  to  which the process's nice value can be
131              raised using setpriority(2) or nice(2).  The actual ceiling  for
132              the  nice  value is calculated as 20 - rlim_cur.  (This strange‐
133              ness occurs because negative  numbers  cannot  be  specified  as
134              resource  limit  values, since they typically have special mean‐
135              ings.  For example, RLIM_INFINITY typically is the same as -1.)
136
137       RLIMIT_NOFILE
138              Specifies a value one greater than the maximum  file  descriptor
139              number  that  can be opened by this process.  Attempts (open(2),
140              pipe(2), dup(2), etc.)  to exceed this  limit  yield  the  error
141              EMFILE.   (Historically,  this  limit  was named RLIMIT_OFILE on
142              BSD.)
143
144       RLIMIT_NPROC
145              The maximum number of processes (or, more  precisely  on  Linux,
146              threads) that can be created for the real user ID of the calling
147              process.  Upon encountering this limit, fork(2) fails  with  the
148              error EAGAIN.
149
150       RLIMIT_RSS
151              Specifies  the  limit  (in  pages) of the process's resident set
152              (the number of virtual pages resident in RAM).  This  limit  has
153              effect only in Linux 2.4.x, x < 30, and there affects only calls
154              to madvise(2) specifying MADV_WILLNEED.
155
156       RLIMIT_RTPRIO (Since Linux 2.6.12, but see BUGS)
157              Specifies a ceiling on the real-time priority that  may  be  set
158              for  this  process  using  sched_setscheduler(2)  and sched_set‐
159              param(2).
160
161       RLIMIT_RTTIME (Since Linux 2.6.25)
162              Specifies a limit (in microseconds) on the amount  of  CPU  time
163              that a process scheduled under a real-time scheduling policy may
164              consume without making a blocking system call.  For the  purpose
165              of this limit, each time a process makes a blocking system call,
166              the count of its consumed CPU time is reset to  zero.   The  CPU
167              time  count  is not reset if the process continues trying to use
168              the CPU but is preempted, its time slice expires,  or  it  calls
169              sched_yield(2).
170
171              Upon reaching the soft limit, the process is sent a SIGXCPU sig‐
172              nal.  If the process catches or ignores this signal and  contin‐
173              ues consuming CPU time, then SIGXCPU will be generated once each
174              second until the hard limit  is  reached,  at  which  point  the
175              process is sent a SIGKILL signal.
176
177              The  intended  use  of this limit is to stop a runaway real-time
178              process from locking up the system.
179
180       RLIMIT_SIGPENDING (Since Linux 2.6.8)
181              Specifies the limit on the number of signals that may be  queued
182              for  the real user ID of the calling process.  Both standard and
183              real-time signals are counted for the purpose of  checking  this
184              limit.   However, the limit is enforced only for sigqueue(3); it
185              is always possible to use kill(2) to queue one instance  of  any
186              of the signals that are not already queued to the process.
187
188       RLIMIT_STACK
189              The  maximum size of the process stack, in bytes.  Upon reaching
190              this limit, a SIGSEGV signal is generated.  To handle this  sig‐
191              nal,  a  process  must employ an alternate signal stack (sigalt‐
192              stack(2)).
193
194              Since Linux 2.6.23, this limit also  determines  the  amount  of
195              space used for the process's command-line arguments and environ‐
196              ment variables; for details, see execve(2).
197
198   prlimit()
199       The Linux-specific prlimit() system call combines and extends the func‐
200       tionality  of  setrlimit() and getrlimit().  It can be used to both set
201       and get the resource limits of an arbitrary process.
202
203       The resource argument has the same meaning as for setrlimit() and getr‐
204       limit().
205
206       If  the  new_limit argument is a not NULL, then the rlimit structure to
207       which it points is used to set new values for the soft and hard  limits
208       for resource.  If the old_limit argument is a not NULL, then a success‐
209       ful call to prlimit() places the previous  soft  and  hard  limits  for
210       resource in the rlimit structure pointed to by old_limit.
211
212       The  pid  argument specifies the ID of the process on which the call is
213       to operate.  If pid is 0, then the call applies to the calling process.
214       To  set or get the resources of a process other than itself, the caller
215       must have the CAP_SYS_RESOURCE capability, or the real, effective,  and
216       saved set user IDs of the target process must match the real user ID of
217       the caller and the real, effective, and saved set group IDs of the tar‐
218       get process must match the real group ID of the caller.
219

RETURN VALUE

221       On success, these system calls return 0.  On error, -1 is returned, and
222       errno is set appropriately.
223

ERRORS

225       EFAULT A pointer argument points to a location outside  the  accessible
226              address space.
227
228       EINVAL The  value  specified  in  resource  is not valid; or, for setr‐
229              limit()  or   prlimit():   rlim->rlim_cur   was   greater   than
230              rlim->rlim_max.
231
232       EPERM  An  unprivileged  process  tried  to  raise  the hard limit; the
233              CAP_SYS_RESOURCE capability is required to  do  this.   Or,  the
234              caller  tried to increase the hard RLIMIT_NOFILE limit above the
235              current kernel maximum (NR_OPEN).  Or, the calling  process  did
236              not  have  permission to set limits for the process specified by
237              pid.
238
239       ESRCH  Could not find a process with the ID specified in pid.
240

VERSIONS

242       The prlimit() system call is available  since  Linux  2.6.36.   Library
243       support is available since glibc 2.13.
244

CONFORMING TO

246       getrlimit(), setrlimit(): SVr4, 4.3BSD, POSIX.1-2001.
247       prlimit(): Linux-specific.
248
249       RLIMIT_MEMLOCK  and  RLIMIT_NPROC derive from BSD and are not specified
250       in POSIX.1-2001; they are present on the BSDs and  Linux,  but  on  few
251       other  implementations.   RLIMIT_RSS derives from BSD and is not speci‐
252       fied in POSIX.1-2001; it is nevertheless present  on  most  implementa‐
253       tions.  RLIMIT_MSGQUEUE, RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_RTTIME, and
254       RLIMIT_SIGPENDING are Linux-specific.
255

NOTES

257       A child process created via fork(2) inherits its parent's resource lim‐
258       its.  Resource limits are preserved across execve(2).
259
260       One  can set the resource limits of the shell using the built-in ulimit
261       command (limit in csh(1)).  The shell's resource limits  are  inherited
262       by the processes that it creates to execute commands.
263
264       Since Linux 2.6.24, the resource limits of any process can be inspected
265       via /proc/[pid]/limits; see proc(5).
266
267       Ancient systems provided a vlimit() function with a similar purpose  to
268       setrlimit().  For backward compatibility, glibc also provides vlimit().
269       All new applications should be written using setrlimit().
270

BUGS

272       In older Linux kernels, the SIGXCPU and SIGKILL signals delivered  when
273       a  process  encountered the soft and hard RLIMIT_CPU limits were deliv‐
274       ered one (CPU) second later than they should have been.  This was fixed
275       in kernel 2.6.8.
276
277       In  2.6.x  kernels  before  2.6.17,  a RLIMIT_CPU limit of 0 is wrongly
278       treated as "no limit" (like RLIM_INFINITY).  Since Linux  2.6.17,  set‐
279       ting  a  limit  of  0 does have an effect, but is actually treated as a
280       limit of 1 second.
281
282       A kernel bug means that RLIMIT_RTPRIO does not work in  kernel  2.6.12;
283       the problem is fixed in kernel 2.6.13.
284
285       In kernel 2.6.12, there was an off-by-one mismatch between the priority
286       ranges returned by getpriority(2) and RLIMIT_NICE.  This had the effect
287       that   the  actual  ceiling  for  the  nice  value  was  calculated  as
288       19 - rlim_cur.  This was fixed in kernel 2.6.13.
289
290       Since Linux 2.6.12, if a process reaches its soft RLIMIT_CPU limit  and
291       has  a handler installed for SIGXCPU, then, in addition to invoking the
292       signal handler, the kernel increases the  soft  limit  by  one  second.
293       This  behavior  repeats  if  the process continues to consume CPU time,
294       until the hard limit is reached, at which point the process is  killed.
295       Other  implementations  do not change the RLIMIT_CPU soft limit in this
296       manner, and the Linux behavior is probably  not  standards  conformant;
297       portable  applications  should  avoid  relying  on  this Linux-specific
298       behavior.  The Linux-specific RLIMIT_RTTIME  limit  exhibits  the  same
299       behavior when the soft limit is encountered.
300
301       Kernels before 2.4.22 did not diagnose the error EINVAL for setrlimit()
302       when rlim->rlim_cur was greater than rlim->rlim_max.
303

EXAMPLE

305       The program below demonstrates the use of prlimit().
306
307       #define _GNU_SOURCE
308       #define _FILE_OFFSET_BITS 64
309       #include <stdio.h>
310       #include <time.h>
311       #include <stdlib.h>
312       #include <unistd.h>
313       #include <sys/resource.h>
314
315       #define errExit(msg)     do { perror(msg); exit(EXIT_FAILURE); \
316                               } while (0)
317
318       int
319       main(int argc, char *argv[])
320       {
321           struct rlimit old, new;
322           struct rlimit *newp;
323           pid_t pid;
324
325           if (!(argc == 2 || argc == 4)) {
326               fprintf(stderr, "Usage: %s <pid> [<new-soft-limit> "
327                       "<new-hard-limit>]\n", argv[0]);
328               exit(EXIT_FAILURE);
329           }
330
331           pid = atoi(argv[1]);        /* PID of target process */
332
333           newp = NULL;
334           if (argc == 4) {
335               new.rlim_cur = atoi(argv[2]);
336               new.rlim_max = atoi(argv[3]);
337               newp = &new;
338           }
339
340           /* Set CPU time limit of target process; retrieve and display
341              previous limit */
342
343           if (prlimit(pid, RLIMIT_CPU, newp, &old) == -1)
344               errExit("prlimit-1");
345           printf("Previous limits: soft=%lld; hard=%lld\n",
346                   (long long) old.rlim_cur, (long long) old.rlim_max);
347
348           /* Retrieve and display new CPU time limit */
349
350           if (prlimit(pid, RLIMIT_CPU, NULL, &old) == -1)
351               errExit("prlimit-2");
352           printf("New limits: soft=%lld; hard=%lld\n",
353                   (long long) old.rlim_cur, (long long) old.rlim_max);
354
355           exit(EXIT_FAILURE);
356       }
357

SEE ALSO

359       prlimit(1), dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2),
360       open(2),   quotactl(2),  sbrk(2),  shmctl(2),  malloc(3),  sigqueue(3),
361       ulimit(3), core(5), capabilities(7), signal(7)
362

COLOPHON

364       This page is part of release 3.53 of the Linux  man-pages  project.   A
365       description  of  the project, and information about reporting bugs, can
366       be found at http://www.kernel.org/doc/man-pages/.
367
368
369
370Linux                             2013-02-11                      GETRLIMIT(2)
Impressum