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