1.\" $MirOS: src/lib/libc/sys/getrlimit.2,v 1.3 2005/09/22 20:17:49 tg Exp $ 2.\" $OpenBSD: getrlimit.2,v 1.17 2005/06/05 19:40:22 jmc Exp $ 3.\" $NetBSD: getrlimit.2,v 1.8 1995/10/12 15:40:58 jtc Exp $ 4.\" 5.\" Copyright (c) 1980, 1991, 1993 6.\" The Regents of the University of California. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)getrlimit.2 8.1 (Berkeley) 6/4/93 33.\" 34.Dd June 4, 1993 35.Dt GETRLIMIT 2 36.Os 37.Sh NAME 38.Nm getrlimit , 39.Nm setrlimit 40.Nd control maximum system resource consumption 41.Sh SYNOPSIS 42.Fd #include <sys/types.h> 43.Fd #include <sys/time.h> 44.Fd #include <sys/resource.h> 45.Ft int 46.Fn getrlimit "int resource" "struct rlimit *rlp" 47.Ft int 48.Fn setrlimit "int resource" "const struct rlimit *rlp" 49.Sh DESCRIPTION 50Limits on the consumption of system resources by the current process 51and each process it creates may be obtained with the 52.Fn getrlimit 53call, and set with the 54.Fn setrlimit 55call. 56.Pp 57The 58.Fa resource 59parameter is one of the following: 60.Bl -tag -width RLIMIT_FSIZEAA 61.It Li RLIMIT_CORE 62The largest size (in bytes) 63.Pa core 64file that may be created. 65.It Li RLIMIT_CPU 66The maximum amount of CPU time (in seconds) to be used by 67each process. 68.It Li RLIMIT_TIME 69The maximum amount of human 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 127A value of 128.Ev RLIM_SAVED_CUR 129or 130.Ev RLIM_SAVED_MAX 131will be stored in 132.Fa rlim_cur 133or 134.Fa rlim_max 135respectively by 136.Fn getrlimit 137if the value for the current or maximum resource limit cannot be stored in an 138.Li rlim_t . 139The values 140.Ev RLIM_SAVED_CUR 141and 142.Ev RLIM_SAVED_MAX 143should not be used in a call to 144.Fn setrlimit 145unless they were returned by a previous call to 146.Fn getrlimit . 147.Pp 148Because this information is stored in the per-process information, 149this system call must be executed directly by the shell if it 150is to affect all future processes created by the shell; 151.Ic limit 152is thus a built-in command to 153.Xr csh 1 154and 155.Ic ulimit 156is the 157.Xr sh 1 158equivalent. 159.Pp 160The system refuses to extend the data or stack space when the limits 161would be exceeded in the normal way: a 162.Xr brk 2 163call fails if the data space limit is reached. 164When the stack limit is reached, the process receives 165a segmentation fault 166.Pq Dv SIGSEGV ; 167if this signal is not 168caught by a handler using the signal stack, this signal 169will kill the process. 170.Pp 171A file I/O operation that would create a file larger than the process' 172soft limit will cause the write to fail and a signal 173.Dv SIGXFSZ 174to be 175generated; this normally terminates the process, but may be caught. 176When the soft CPU time limit is exceeded, a signal 177.Dv SIGXCPU 178is sent to the 179offending process. 180.Sh RETURN VALUES 181A 0 return value indicates that the call succeeded, changing 182or returning the resource limit. 183A return value of \-1 indicates that an error occurred, and an error code 184is stored in the global variable 185.Va errno . 186.Sh ERRORS 187.Fn getrlimit 188and 189.Fn setrlimit 190will fail if: 191.Bl -tag -width Er 192.It Bq Er EFAULT 193The address specified for 194.Fa rlp 195is invalid. 196.It Bq Er EPERM 197The limit specified to 198.Fn setrlimit 199would have raised the maximum limit value, and the caller is not the superuser. 200.El 201.Sh SEE ALSO 202.Xr csh 1 , 203.Xr sh 1 , 204.Xr quotactl 2 , 205.Xr sigaction 2 , 206.Xr sigaltstack 2 , 207.Xr sysctl 3 208.Sh STANDARDS 209The 210.Fn getrlimit 211and 212.Fn setrlimit 213function calls are expected to conform to 214.St -p1003.1-2004 . 215.Sh HISTORY 216The 217.Fn getrlimit 218function call appeared in 219.Bx 4.2 . 220