1.\" $OpenBSD: getrlimit.2,v 1.18 2007/05/31 19:19:32 jmc Exp $ 2.\" $NetBSD: getrlimit.2,v 1.8 1995/10/12 15:40:58 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)getrlimit.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: May 31 2007 $ 34.Dt GETRLIMIT 2 35.Os 36.Sh NAME 37.Nm getrlimit , 38.Nm setrlimit 39.Nd control maximum system resource consumption 40.Sh SYNOPSIS 41.Fd #include <sys/types.h> 42.Fd #include <sys/time.h> 43.Fd #include <sys/resource.h> 44.Ft int 45.Fn getrlimit "int resource" "struct rlimit *rlp" 46.Ft int 47.Fn setrlimit "int resource" "const struct rlimit *rlp" 48.Sh DESCRIPTION 49Limits on the consumption of system resources by the current process 50and each process it creates may be obtained with the 51.Fn getrlimit 52call, and set with the 53.Fn setrlimit 54call. 55.Pp 56The 57.Fa resource 58parameter is one of the following: 59.Bl -tag -width RLIMIT_FSIZEAA 60.It Li RLIMIT_CORE 61The largest size (in bytes) 62.Pa core 63file that may be created. 64.It Li RLIMIT_CPU 65The maximum amount of CPU time (in seconds) to be used by 66each process. 67.It Li RLIMIT_DATA 68The maximum size (in bytes) of the data segment for a process; 69this defines how far a program may extend its break with the 70.Xr sbrk 2 71system call. 72.It Li RLIMIT_FSIZE 73The largest size (in bytes) file that may be created. 74.It Li RLIMIT_MEMLOCK 75The maximum size (in bytes) which a process may lock into memory 76using the 77.Xr mlock 2 78function. 79.It Li RLIMIT_NOFILE 80The maximum number of open files for this process. 81.It Li RLIMIT_NPROC 82The maximum number of simultaneous processes for this user id. 83.It Li RLIMIT_RSS 84The maximum size (in bytes) to which a process's resident set size may 85grow. 86This imposes a limit on the amount of physical memory to be given to 87a process; if memory is tight, the system will prefer to take memory 88from processes that are exceeding their declared resident set size. 89.It Li RLIMIT_STACK 90The maximum size (in bytes) of the stack segment for a process; 91this defines how far a program's stack segment may be extended. 92Stack extension is performed automatically by the system. 93.El 94.Pp 95A resource limit is specified as a soft limit and a hard limit. 96When a soft limit is exceeded a process may receive a signal (for example, 97if the CPU time or file size is exceeded), but it will be allowed to 98continue execution until it reaches the hard limit (or modifies 99its resource limit). 100The 101.Em rlimit 102structure is used to specify the hard and soft limits on a resource, 103.Bd -literal -offset indent 104struct rlimit { 105 rlim_t rlim_cur; /* current (soft) limit */ 106 rlim_t rlim_max; /* hard limit */ 107}; 108.Ed 109.Pp 110Only the superuser may raise the maximum limits. 111Other users may only alter 112.Fa rlim_cur 113within the range from 0 to 114.Fa rlim_max 115or (irreversibly) lower 116.Fa rlim_max . 117.Pp 118An 119.Dq infinite 120value for a limit is defined as 121.Dv RLIM_INFINITY . 122.Pp 123A value of 124.Ev RLIM_SAVED_CUR 125or 126.Ev RLIM_SAVED_MAX 127will be stored in 128.Fa rlim_cur 129or 130.Fa rlim_max 131respectively by 132.Fn getrlimit 133if the value for the current or maximum resource limit cannot be stored in an 134.Li rlim_t . 135The values 136.Ev RLIM_SAVED_CUR 137and 138.Ev RLIM_SAVED_MAX 139should not be used in a call to 140.Fn setrlimit 141unless they were returned by a previous call to 142.Fn getrlimit . 143.Pp 144Because this information is stored in the per-process information, 145this system call must be executed directly by the shell if it 146is to affect all future processes created by the shell; 147.Ic limit 148is thus a built-in command to 149.Xr csh 1 150and 151.Ic ulimit 152is the 153.Xr sh 1 154equivalent. 155.Pp 156The system refuses to extend the data or stack space when the limits 157would be exceeded in the normal way: a 158.Xr brk 2 159call fails if the data space limit is reached. 160When the stack limit is reached, the process receives 161a segmentation fault 162.Pq Dv SIGSEGV ; 163if this signal is not 164caught by a handler using the signal stack, this signal 165will kill the process. 166.Pp 167A file I/O operation that would create a file larger than the process' 168soft limit will cause the write to fail and a signal 169.Dv SIGXFSZ 170to be 171generated; this normally terminates the process, but may be caught. 172When the soft CPU time limit is exceeded, a signal 173.Dv SIGXCPU 174is sent to the 175offending process. 176.Sh RETURN VALUES 177A 0 return value indicates that the call succeeded, changing 178or returning the resource limit. 179A return value of \-1 indicates that an error occurred, and an error code 180is stored in the global variable 181.Va errno . 182.Sh ERRORS 183.Fn getrlimit 184and 185.Fn setrlimit 186will fail if: 187.Bl -tag -width Er 188.It Bq Er EFAULT 189The address specified for 190.Fa rlp 191is invalid. 192.It Bq Er EPERM 193The limit specified to 194.Fn setrlimit 195would have raised the maximum limit value, and the caller is not the superuser. 196.El 197.Sh SEE ALSO 198.Xr csh 1 , 199.Xr sh 1 , 200.Xr quotactl 2 , 201.Xr sigaction 2 , 202.Xr sigaltstack 2 , 203.Xr sysctl 3 204.Sh STANDARDS 205The 206.Fn getrlimit 207and 208.Fn setrlimit 209function calls are expected to conform to 210.St -p1003.1-2004 . 211.Sh HISTORY 212The 213.Fn getrlimit 214function call appeared in 215.Bx 4.2 . 216