1.\" $NetBSD: getrlimit.2,v 1.21 2002/02/08 01:28:18 ross Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getrlimit.2 8.1 (Berkeley) 6/4/93 35.\" 36.Dd November 23, 2001 37.Dt GETRLIMIT 2 38.Os 39.Sh NAME 40.Nm getrlimit , 41.Nm setrlimit 42.Nd control maximum system resource consumption 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.Fd #include \*[Lt]sys/resource.h\*[Gt] 47.Ft int 48.Fn getrlimit "int resource" "struct rlimit *rlp" 49.Ft int 50.Fn setrlimit "int resource" "const struct rlimit *rlp" 51.Sh DESCRIPTION 52Limits on the consumption of system resources by the current process 53and each process it creates may be obtained with the 54.Fn getrlimit 55call, and set with the 56.Fn setrlimit 57call. Resources of an arbitrary process can be obtained/changed using 58.Xr sysctl 3 . 59.. 60.Pp 61The 62.Fa resource 63parameter is one of the following: 64.Bl -tag -width RLIMIT_FSIZEAA 65.It Li RLIMIT_CORE 66The largest size (in bytes) 67.Pa core 68file that may be created. 69.It Li RLIMIT_CPU 70The maximum amount of cpu time (in seconds) to be used by 71each process. 72.It Li RLIMIT_DATA 73The maximum size (in bytes) of the data segment for a process; 74this defines how far a program may extend its break with the 75.Xr sbrk 2 76system call. 77.It Li RLIMIT_FSIZE 78The largest size (in bytes) file that may be created. 79.It Li RLIMIT_MEMLOCK 80The maximum size (in bytes) which a process may lock into memory 81using the 82.Xr mlock 2 83function. 84.It Li RLIMIT_NOFILE 85The maximum number of open files for this process. 86.It Li RLIMIT_NPROC 87The maximum number of simultaneous processes for this user id. 88.It Li RLIMIT_RSS 89The maximum size (in bytes) to which a process's resident set size may 90grow. 91This imposes a limit on the amount of physical memory to be given to 92a process; if memory is tight, the system will prefer to take memory 93from processes that are exceeding their declared resident set size. 94.It Li RLIMIT_STACK 95The maximum size (in bytes) of the stack segment for a process; 96this defines how far a program's stack segment may be extended. 97Stack extension is performed automatically by the system. 98.El 99.Pp 100A resource limit is specified as a soft limit and a hard limit. When a 101soft limit is exceeded a process may receive a signal (for example, if 102the cpu time or file size is exceeded), but it will be allowed to 103continue execution until it reaches the hard limit (or modifies 104its resource limit). The 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 super-user may raise the maximum limits. Other users 115may 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. 130Thus, shells provide built-in commands to change the limits 131.Ic ( limit 132for 133.Xr csh 1 , 134or 135.Ic ulimit 136for 137.Xr sh 1 ) . 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. When 155the 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. Otherwise, -1 is returned 162and the global variable 163.Va errno 164is set to indicate the error. 165.Sh ERRORS 166The 167.Fn getrlimit 168and 169.Fn setrlimit 170will fail if: 171.Bl -tag -width Er 172.It Bq Er EFAULT 173The address specified for 174.Fa rlp 175is invalid. 176.It Bq Er EINVAL 177Specified 178.Fa resource 179was invalid. 180.It Bq Er EINVAL 181In the 182.Fn setrlimit 183call, the specified 184.Fa rlim_cur 185exceeds the specified 186.Fa rlim_max . 187.It Bq Er EPERM 188The limit specified to 189.Fn setrlimit 190would have 191raised the maximum limit value, and the caller is not the super-user. 192.El 193.Pp 194The 195.Fn setrlimit 196function may fail if: 197.Bl -tag -width Er 198.It Bq Er EINVAL 199The limit specified to 200.Fn setrlimit 201cannot be lowered, because current usage is already higher than the limit. 202.El 203.Sh SEE ALSO 204.Xr csh 1 , 205.Xr sh 1 , 206.Xr quotactl 2 , 207.Xr sigaction 2 , 208.Xr sigaltstack 2 , 209.Xr sysctl 3 210.\" Sh STANDARDS 211.\" With exception of 212.\" .Li RLIMIT_AS 213.\" (which is not currently supported), the 214.\" .Fn getrlimit 215.\" and 216.\" .Fn setrlimit 217.\" functions conform to 218.\" .St -susv2 . 219.Sh HISTORY 220The 221.Fn getrlimit 222function call appeared in 223.Bx 4.2 . 224