1.\" $OpenBSD: getrlimit.2,v 1.26 2015/09/10 17:55:21 schwarze 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: September 10 2015 $ 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.In sys/resource.h 42.Ft int 43.Fn getrlimit "int resource" "struct rlimit *rlp" 44.Ft int 45.Fn setrlimit "int resource" "const struct rlimit *rlp" 46.Sh DESCRIPTION 47Limits on the consumption of system resources by the current process 48and each process it creates may be obtained with the 49.Fn getrlimit 50call, and set with the 51.Fn setrlimit 52call. 53.Pp 54The 55.Fa resource 56parameter is one of the following: 57.Bl -tag -width RLIMIT_FSIZEAA 58.It Li RLIMIT_CORE 59The largest size (in bytes) 60.Pa core 61file that may be created. 62.It Li RLIMIT_CPU 63The maximum amount of CPU time (in seconds) to be used by 64each process. 65.It Li RLIMIT_DATA 66The maximum size (in bytes) of the data segment for a process; 67this includes memory allocated via 68.Xr malloc 3 69and all other anonymous memory mapped via 70.Xr mmap 2 . 71.It Li RLIMIT_FSIZE 72The largest size (in bytes) file that may be created. 73.It Li RLIMIT_MEMLOCK 74The maximum size (in bytes) which a process may lock into memory 75using the 76.Xr mlock 2 77function. 78.It Li RLIMIT_NOFILE 79The maximum number of open files for this process. 80.It Li RLIMIT_NPROC 81The maximum number of simultaneous processes for this user id. 82.It Li RLIMIT_RSS 83The maximum size (in bytes) to which a process's resident set size may 84grow. 85This imposes a limit on the amount of physical memory to be given to 86a process; if memory is tight, the system will prefer to take memory 87from processes that are exceeding their declared resident set size. 88.It Li RLIMIT_STACK 89The maximum size (in bytes) of the stack segment for a process, 90which defines how far a process's stack segment may be extended. 91Stack extension is performed automatically by the system, 92and is only used by the main thread of a process. 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.Dv RLIM_SAVED_CUR 125or 126.Dv 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.Dv RLIM_SAVED_CUR 137and 138.Dv 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 177.Rv -std 178.Sh ERRORS 179.Fn getrlimit 180and 181.Fn setrlimit 182will fail if: 183.Bl -tag -width Er 184.It Bq Er EFAULT 185The address specified for 186.Fa rlp 187is invalid. 188.It Bq Er EINVAL 189An unrecognized value for 190.Fa resource 191was specified. 192.El 193.Pp 194In addition, 195.Fn setrlimit 196may return the following errors: 197.Bl -tag -width Er 198.It Bq Er EINVAL 199The new 200.Fa rlim_cur 201is greater than the new 202.Fa rlim_max . 203.It Bq Er EPERM 204The new 205.Fa rlim_max 206is greater than the current maximum limit value, 207and the caller is not the superuser. 208.El 209.Sh SEE ALSO 210.Xr csh 1 , 211.Xr sh 1 , 212.Xr quotactl 2 , 213.Xr sigaction 2 , 214.Xr sigaltstack 2 , 215.Xr sysctl 3 216.Sh STANDARDS 217The 218.Fn getrlimit 219and 220.Fn setrlimit 221functions conform to 222.St -p1003.1-2008 . 223.Pp 224The 225.Dv RLIMIT_MEMLOCK , 226.Dv RLIMIT_NPROC , 227and 228.Dv RLIMIT_RSS 229resources are non-standard extensions. 230.Sh HISTORY 231The 232.Fn getrlimit 233and 234.Fn setrlimit 235system calls first appeared in 236.Bx 4.1c . 237.Sh BUGS 238The 239.Dv RLIMIT_AS 240resource is missing. 241