OSDN Git Service

(split) LDP_man-pages: update original to v3.34.
[linuxjm/LDP_man-pages.git] / original / man2 / getrlimit.2
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\"
3 .\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992
4 .\" and Copyright (c) 2002, 2004, 2005, 2008, 2010 Michael Kerrisk
5 .\"
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein.  The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\"
26 .\" Modified by Michael Haardt <michael@moria.de>
27 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
28 .\" Modified 1996-01-13 by Arnt Gulbrandsen <agulbra@troll.no>
29 .\" Modified 1996-01-22 by aeb, following a remark by
30 .\"          Tigran Aivazian <tigran@sco.com>
31 .\" Modified 1996-04-14 by aeb, following a remark by
32 .\"          Robert Bihlmeyer <robbe@orcus.ping.at>
33 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
34 .\" Modified 2001-05-04 by aeb, following a remark by
35 .\"          HÃ¥vard Lygre <hklygre@online.no>
36 .\" Modified 2001-04-17 by Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" Modified 2002-06-13 by Michael Kerrisk <mtk.manpages@gmail.com>
38 .\"     Added note on nonstandard behavior when SIGCHLD is ignored.
39 .\" Modified 2002-07-09 by Michael Kerrisk <mtk.manpages@gmail.com>
40 .\"     Enhanced descriptions of 'resource' values
41 .\" Modified 2003-11-28 by aeb, added RLIMIT_CORE
42 .\" Modified 2004-03-26 by aeb, added RLIMIT_AS
43 .\" Modified 2004-06-16 by Michael Kerrisk <mtk.manpages@gmail.com>
44 .\"     Added notes on CAP_SYS_RESOURCE
45 .\"
46 .\" 2004-11-16 -- mtk: the getrlimit.2 page, which formally included
47 .\" coverage of getrusage(2), has been split, so that the latter
48 .\" is now covered in its own getrusage.2.
49 .\"
50 .\" Modified 2004-11-16, mtk: A few other minor changes
51 .\" Modified 2004-11-23, mtk
52 .\"     Added notes on RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS
53 .\"             to "CONFORMING TO"
54 .\" Modified 2004-11-25, mtk
55 .\"     Rewrote discussion on RLIMIT_MEMLOCK to incorporate kernel
56 .\"             2.6.9 changes.
57 .\"     Added note on RLIMIT_CPU error in older kernels
58 .\" 2004-11-03, mtk, Added RLIMIT_SIGPENDING
59 .\" 2005-07-13, mtk, documented RLIMIT_MSGQUEUE limit.
60 .\" 2005-07-28, mtk, Added descriptions of RLIMIT_NICE and RLIMIT_RTPRIO
61 .\" 2008-05-07, mtk / Peter Zijlstra, Added description of RLIMIT_RTTIME
62 .\" 2010-11-06, mtk: Added documentation of prlimit()
63 .\"
64 .TH GETRLIMIT 2 2011-09-10 "Linux" "Linux Programmer's Manual"
65 .SH NAME
66 getrlimit, setrlimit, prlimit \- get/set resource limits
67 .SH SYNOPSIS
68 .B #include <sys/time.h>
69 .br
70 .B #include <sys/resource.h>
71 .sp
72 .BI "int getrlimit(int " resource ", struct rlimit *" rlim );
73 .br
74 .BI "int setrlimit(int " resource ", const struct rlimit *" rlim );
75 .sp
76 .BI "int prlimit(pid_t "  pid ", int " resource \
77 ", const struct rlimit *" new_limit ,
78 .br
79 .BI "            struct rlimit *" old_limit );
80 .sp
81 .in -4n
82 Feature Test Macro Requirements for glibc (see
83 .BR feature_test_macros (7)):
84 .in
85 .sp
86 .BR prlimit ():
87 _GNU_SOURCE && _FILE_OFFSET_BITS == 64
88 .SH DESCRIPTION
89 The
90 .BR getrlimit ()
91 and
92 .BR setrlimit ()
93 system calls get and set resource limits respectively.
94 Each resource has an associated soft and hard limit, as defined by the
95 .I rlimit
96 structure:
97 .PP
98 .in +4n
99 .nf
100 struct rlimit {
101     rlim_t rlim_cur;  /* Soft limit */
102     rlim_t rlim_max;  /* Hard limit (ceiling for rlim_cur) */
103 };
104
105 .fi
106 .in
107 The soft limit is the value that the kernel enforces for the
108 corresponding resource.
109 The hard limit acts as a ceiling for the soft limit:
110 an unprivileged process may only set its soft limit to a value in the
111 range from 0 up to the hard limit, and (irreversibly) lower its hard limit.
112 A privileged process (under Linux: one with the
113 .B CAP_SYS_RESOURCE
114 capability) may make arbitrary changes to either limit value.
115 .PP
116 The value
117 .B RLIM_INFINITY
118 denotes no limit on a resource (both in the structure returned by
119 .BR getrlimit ()
120 and in the structure passed to
121 .BR setrlimit ()).
122 .PP
123 The
124 .I resource
125 argument must be one of:
126 .TP
127 .B RLIMIT_AS
128 The maximum size of the process's virtual memory (address space) in bytes.
129 .\" since 2.0.27 / 2.1.12
130 This limit affects calls to
131 .BR brk (2),
132 .BR mmap (2)
133 and
134 .BR mremap (2),
135 which fail with the error
136 .B ENOMEM
137 upon exceeding this limit.
138 Also automatic stack expansion will fail
139 (and generate a
140 .B SIGSEGV
141 that kills the process if no alternate stack
142 has been made available via
143 .BR sigaltstack (2)).
144 Since the value is a \fIlong\fP, on machines with a 32-bit \fIlong\fP
145 either this limit is at most 2 GiB, or this resource is unlimited.
146 .TP
147 .B RLIMIT_CORE
148 Maximum size of
149 .I core
150 file.
151 When 0 no core dump files are created.
152 When nonzero, larger dumps are truncated to this size.
153 .TP
154 .B RLIMIT_CPU
155 CPU time limit in seconds.
156 When the process reaches the soft limit, it is sent a
157 .B SIGXCPU
158 signal.
159 The default action for this signal is to terminate the process.
160 However, the signal can be caught, and the handler can return control to
161 the main program.
162 If the process continues to consume CPU time, it will be sent
163 .B SIGXCPU
164 once per second until the hard limit is reached, at which time
165 it is sent
166 .BR SIGKILL .
167 (This latter point describes Linux behavior.
168 Implementations vary in how they treat processes which continue to
169 consume CPU time after reaching the soft limit.
170 Portable applications that need to catch this signal should
171 perform an orderly termination upon first receipt of
172 .BR SIGXCPU .)
173 .TP
174 .B RLIMIT_DATA
175 The maximum size of the process's data segment (initialized data,
176 uninitialized data, and heap).
177 This limit affects calls to
178 .BR brk (2)
179 and
180 .BR sbrk (2),
181 which fail with the error
182 .B ENOMEM
183 upon encountering the soft limit of this resource.
184 .TP
185 .B RLIMIT_FSIZE
186 The maximum size of files that the process may create.
187 Attempts to extend a file beyond this limit result in delivery of a
188 .B SIGXFSZ
189 signal.
190 By default, this signal terminates a process, but a process can
191 catch this signal instead, in which case the relevant system call (e.g.,
192 .BR write (2),
193 .BR truncate (2))
194 fails with the error
195 .BR EFBIG .
196 .TP
197 .BR RLIMIT_LOCKS " (Early Linux 2.4 only)"
198 .\" to be precise: Linux 2.4.0-test9; no longer in 2.4.25 / 2.5.65
199 A limit on the combined number of
200 .BR flock (2)
201 locks and
202 .BR fcntl (2)
203 leases that this process may establish.
204 .TP
205 .B RLIMIT_MEMLOCK
206 The maximum number of bytes of memory that may be locked
207 into RAM.
208 In effect this limit is rounded down to the nearest multiple
209 of the system page size.
210 This limit affects
211 .BR mlock (2)
212 and
213 .BR mlockall (2)
214 and the
215 .BR mmap (2)
216 .B MAP_LOCKED
217 operation.
218 Since Linux 2.6.9 it also affects the
219 .BR shmctl (2)
220 .B SHM_LOCK
221 operation, where it sets a maximum on the total bytes in
222 shared memory segments (see
223 .BR shmget (2))
224 that may be locked by the real user ID of the calling process.
225 The
226 .BR shmctl (2)
227 .B SHM_LOCK
228 locks are accounted for separately from the per-process memory
229 locks established by
230 .BR mlock (2),
231 .BR mlockall (2),
232 and
233 .BR mmap (2)
234 .BR MAP_LOCKED ;
235 a process can lock bytes up to this limit in each of these
236 two categories.
237 In Linux kernels before 2.6.9, this limit controlled the amount of
238 memory that could be locked by a privileged process.
239 Since Linux 2.6.9, no limits are placed on the amount of memory
240 that a privileged process may lock, and this limit instead governs
241 the amount of memory that an unprivileged process may lock.
242 .TP
243 .BR RLIMIT_MSGQUEUE " (Since Linux 2.6.8)"
244 Specifies the limit on the number of bytes that can be allocated
245 for POSIX message queues for the real user ID of the calling process.
246 This limit is enforced for
247 .BR mq_open (3).
248 Each message queue that the user creates counts (until it is removed)
249 against this limit according to the formula:
250 .nf
251
252     bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) +
253             attr.mq_maxmsg * attr.mq_msgsize
254
255 .fi
256 where
257 .I attr
258 is the
259 .I mq_attr
260 structure specified as the fourth argument to
261 .BR mq_open (3).
262
263 The first addend in the formula, which includes
264 .I "sizeof(struct msg_msg *)"
265 (4 bytes on Linux/i386), ensures that the user cannot
266 create an unlimited number of zero-length messages (such messages
267 nevertheless each consume some system memory for bookkeeping overhead).
268 .TP
269 .BR RLIMIT_NICE " (since Linux 2.6.12, but see BUGS below)"
270 Specifies a ceiling to which the process's nice value can be raised using
271 .BR setpriority (2)
272 or
273 .BR nice (2).
274 The actual ceiling for the nice value is calculated as
275 .IR "20\ \-\ rlim_cur" .
276 (This strangeness occurs because negative numbers cannot be specified
277 as resource limit values, since they typically have special meanings.
278 For example,
279 .B RLIM_INFINITY
280 typically is the same as \-1.)
281 .TP
282 .B RLIMIT_NOFILE
283 Specifies a value one greater than the maximum file descriptor number
284 that can be opened by this process.
285 Attempts
286 .RB ( open (2),
287 .BR pipe (2),
288 .BR dup (2),
289 etc.)
290 to exceed this limit yield the error
291 .BR EMFILE .
292 (Historically, this limit was named
293 .B RLIMIT_OFILE
294 on BSD.)
295 .TP
296 .B RLIMIT_NPROC
297 The maximum number of processes (or, more precisely on Linux, threads)
298 that can be created for the real user ID of the calling process.
299 Upon encountering this limit,
300 .BR fork (2)
301 fails with the error
302 .BR EAGAIN .
303 .TP
304 .B RLIMIT_RSS
305 Specifies the limit (in pages) of the process's resident set
306 (the number of virtual pages resident in RAM).
307 This limit only has effect in Linux 2.4.x, x < 30, and there only
308 affects calls to
309 .BR madvise (2)
310 specifying
311 .BR MADV_WILLNEED .
312 .\" As at kernel 2.6.12, this limit still does nothing in 2.6 though
313 .\" talk of making it do something has surfaced from time to time in LKML
314 .\"       -- MTK, Jul 05
315 .TP
316 .BR RLIMIT_RTPRIO " (Since Linux 2.6.12, but see BUGS)"
317 Specifies a ceiling on the real-time priority that may be set for
318 this process using
319 .BR sched_setscheduler (2)
320 and
321 .BR sched_setparam (2).
322 .TP
323 .BR RLIMIT_RTTIME " (Since Linux 2.6.25)"
324 Specifies a limit (in microseconds)
325 on the amount of CPU time that a process scheduled
326 under a real-time scheduling policy may consume without making a blocking
327 system call.
328 For the purpose of this limit,
329 each time a process makes a blocking system call,
330 the count of its consumed CPU time is reset to zero.
331 The CPU time count is not reset if the process continues trying to
332 use the CPU but is preempted, its time slice expires, or it calls
333 .BR sched_yield (2).
334
335 Upon reaching the soft limit, the process is sent a
336 .B SIGXCPU
337 signal.
338 If the process catches or ignores this signal and
339 continues consuming CPU time, then
340 .B SIGXCPU
341 will be generated once each second until the hard limit is reached,
342 at which point the process is sent a
343 .B SIGKILL
344 signal.
345
346 The intended use of this limit is to stop a runaway
347 real-time process from locking up the system.
348 .TP
349 .BR RLIMIT_SIGPENDING " (Since Linux 2.6.8)"
350 Specifies the limit on the number of signals
351 that may be queued for the real user ID of the calling process.
352 Both standard and real-time signals are counted for the purpose of
353 checking this limit.
354 However, the limit is only enforced for
355 .BR sigqueue (3);
356 it is always possible to use
357 .BR kill (2)
358 to queue one instance of any of the signals that are not already
359 queued to the process.
360 .\" This replaces the /proc/sys/kernel/rtsig-max system-wide limit
361 .\" that was present in kernels <= 2.6.7.  MTK Dec 04
362 .TP
363 .B RLIMIT_STACK
364 The maximum size of the process stack, in bytes.
365 Upon reaching this limit, a
366 .B SIGSEGV
367 signal is generated.
368 To handle this signal, a process must employ an alternate signal stack
369 .RB ( sigaltstack (2)).
370
371 Since Linux 2.6.23,
372 this limit also determines the amount of space used for the process's
373 command-line arguments and environment variables; for details, see
374 .BR execve (2).
375 .SS prlimit()
376 .\" commit c022a0acad534fd5f5d5f17280f6d4d135e74e81
377 .\" Author: Jiri Slaby <jslaby@suse.cz>
378 .\" Date:   Tue May 4 18:03:50 2010 +0200
379 The Linux-specific
380 .BR prlimit ()
381 system call combines and extends the functionality of
382 .BR setrlimit ()
383 and
384 .BR getrlimit ().
385 It can be used to both set and get the resource limits of an arbitrary process.
386
387 The
388 .I resource
389 argument has the same meaning as for
390 .BR setrlimit ()
391 and
392 .BR getrlimit ().
393
394 If the
395 .IR new_limit
396 argument is a not NULL, then the
397 .I rlimit
398 structure to which it points is used to set new values for
399 the soft and hard limits for
400 .IR resource .
401 If the
402 .IR old_limit
403 argument is a not NULL, then a successful call to
404 .BR prlimit ()
405 places the previous soft and hard limits for
406 .I resource
407 in the
408 .I rlimit
409 structure pointed to by
410 .IR old_limit .
411
412 The
413 .I pid
414 argument specifies the ID of the process on which the call is to operate.
415 If
416 .I pid
417 is 0, then the call applies to the calling process.
418 To set or get the resources of a process other than itself,
419 the caller must have the
420 .B CAP_SYS_RESOURCE
421 capability, or the
422 real, effective, and saved set user IDs of the target process
423 must match the real user ID of the caller
424 .I and
425 the real, effective, and saved set group IDs of the target process
426 must match the real group ID of the caller.
427 .\" FIXME this permission check is strange
428 .\" Asked about this on LKML, 7 Nov 2010
429 .\"     "Inconsistent credential checking in prlimit() syscall"
430 .SH RETURN VALUE
431 On success, these system calls return 0.
432 On error, \-1 is returned, and
433 .I errno
434 is set appropriately.
435 .SH ERRORS
436 .TP
437 .B EFAULT
438 A pointer argument points to a location
439 outside the accessible address space.
440 .TP
441 .B EINVAL
442 The value specified in
443 .I resource
444 is not valid;
445 or, for
446 .BR setrlimit ()
447 or
448 .BR prlimit ():
449 .I rlim\->rlim_cur
450 was greater than
451 .IR rlim\->rlim_max .
452 .TP
453 .B EPERM
454 An unprivileged process tried to raise the hard limit; the
455 .B CAP_SYS_RESOURCE
456 capability is required to do this.
457 Or, the caller tried to increase the hard
458 .B RLIMIT_NOFILE
459 limit above the current kernel maximum
460 .RB ( NR_OPEN ).
461 Or, the calling process did not have permission to set limits
462 for the process specified by
463 .IR pid .
464 .TP
465 .B ESRCH
466 Could not find a process with the ID specified in
467 .IR pid .
468 .SH VERSIONS
469 The
470 .BR prlimit ()
471 system call is available since Linux 2.6.36.
472 Library support is available since glibc 2.13.
473 .SH CONFORMING TO
474 .BR getrlimit (),
475 .BR setrlimit ():
476 SVr4, 4.3BSD, POSIX.1-2001.
477 .br
478 .BR prlimit ():
479 Linux-specific.
480
481 .B RLIMIT_MEMLOCK
482 and
483 .B RLIMIT_NPROC
484 derive from BSD and are not specified in POSIX.1-2001;
485 they are present on the BSDs and Linux, but on few other implementations.
486 .B RLIMIT_RSS
487 derives from BSD and is not specified in POSIX.1-2001;
488 it is nevertheless present on most implementations.
489 .BR RLIMIT_MSGQUEUE ,
490 .BR RLIMIT_NICE ,
491 .BR RLIMIT_RTPRIO ,
492 .BR RLIMIT_RTTIME ,
493 and
494 .B RLIMIT_SIGPENDING
495 are Linux-specific.
496 .SH NOTES
497 A child process created via
498 .BR fork (2)
499 inherits its parent's resource limits.
500 Resource limits are preserved across
501 .BR execve (2).
502
503 One can set the resource limits of the shell using the built-in
504 .IR ulimit
505 command
506 .RI ( limit
507 in
508 .BR csh (1)).
509 The shell's resource limits are inherited by the processes that
510 it creates to execute commands.
511
512 Ancient systems provided a
513 .BR vlimit ()
514 function with a similar purpose to
515 .BR setrlimit ().
516 For backward compatibility, glibc also provides
517 .BR vlimit ().
518 All new applications should be written using
519 .BR setrlimit ().
520 .SH EXAMPLE
521 The program below demonstrates the use of
522 .BR prlimit ().
523 .PP
524 .nf
525 #define _GNU_SOURCE
526 #define _FILE_OFFSET_BITS 64
527 #include <stdio.h>
528 #include <time.h>
529 #include <stdlib.h>
530 #include <unistd.h>
531 #include <sys/resource.h>
532
533 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
534                         } while (0)
535
536 int
537 main(int argc, char *argv[])
538 {
539     struct rlimit old, new;
540     struct rlimit *newp;
541     pid_t pid;
542
543     if (!(argc == 2 || argc == 4)) {
544         fprintf(stderr, "Usage: %s <pid> [<new\-soft\-limit> "
545                 "<new\-hard\-limit>]\\n", argv[0]);
546         exit(EXIT_FAILURE);
547     }
548
549     pid = atoi(argv[1]);        /* PID of target process */
550
551     newp = NULL;
552     if (argc == 4) {
553         new.rlim_cur = atoi(argv[2]);
554         new.rlim_max = atoi(argv[3]);
555         newp = &new;
556     }
557
558     /* Set CPU time limit of target process; retrieve and display
559        previous limit */
560
561     if (prlimit(pid, RLIMIT_CPU, newp, &old) == \-1)
562         errExit("prlimit\-1");
563     printf("Previous limits: soft=%lld; hard=%lld\\n",
564             (long long) old.rlim_cur, (long long) old.rlim_max);
565
566     /* Retrieve and display new CPU time limit */
567
568     if (prlimit(pid, RLIMIT_CPU, NULL, &old) == \-1)
569         errExit("prlimit\-2");
570     printf("New limits: soft=%lld; hard=%lld\\n",
571             (long long) old.rlim_cur, (long long) old.rlim_max);
572
573     exit(EXIT_FAILURE);
574 }
575 .fi
576 .SH BUGS
577 .\" FIXME prlimit() does not suffer
578 .\" https://bugzilla.kernel.org/show_bug.cgi?id=5042
579 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12201
580 In older Linux kernels, the
581 .B SIGXCPU
582 and
583 .B SIGKILL
584 signals delivered when a process encountered the soft and hard
585 .B RLIMIT_CPU
586 limits were delivered one (CPU) second later than they should have been.
587 This was fixed in kernel 2.6.8.
588
589 In 2.6.x kernels before 2.6.17, a
590 .B RLIMIT_CPU
591 limit of 0 is wrongly treated as "no limit" (like
592 .BR RLIM_INFINITY ).
593 Since Linux 2.6.17, setting a limit of 0 does have an effect,
594 but is actually treated as a limit of 1 second.
595 .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2
596
597 A kernel bug means that
598 .B RLIMIT_RTPRIO
599 does not work in kernel 2.6.12; the problem is fixed in kernel 2.6.13.
600
601 In kernel 2.6.12, there was an off-by-one mismatch
602 between the priority ranges returned by
603 .BR getpriority (2)
604 and
605 .BR RLIMIT_NICE .
606 This had the effect that the actual ceiling for the nice value
607 was calculated as
608 .IR "19\ \-\ rlim_cur" .
609 This was fixed in kernel 2.6.13.
610 .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2
611
612 Kernels before 2.4.22 did not diagnose the error
613 .B EINVAL
614 for
615 .BR setrlimit ()
616 when
617 .I rlim\->rlim_cur
618 was greater than
619 .IR rlim\->rlim_max .
620 .SH "SEE ALSO"
621 .BR dup (2),
622 .BR fcntl (2),
623 .BR fork (2),
624 .BR getrusage (2),
625 .BR mlock (2),
626 .BR mmap (2),
627 .BR open (2),
628 .BR quotactl (2),
629 .BR sbrk (2),
630 .BR shmctl (2),
631 .BR malloc (3),
632 .BR sigqueue (3),
633 .BR ulimit (3),
634 .BR core (5),
635 .BR capabilities (7),
636 .BR signal (7)