1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getrlimit.2 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt GETRLIMIT 2 10.Os BSD 4 11.Sh NAME 12.Nm getrlimit , 13.Nm setrlimit 14.Nd control maximum system resource consumption 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/time.h> 18.Fd #include <sys/resource.h> 19.Ft int 20.Fn getrlimit "int resource" "struct rlimit *rlp" 21.Ft int 22.Fn setrlimit "int resource" "struct rlimit *rlp" 23.Sh DESCRIPTION 24Limits on the consumption of system resources by the current process 25and each process it creates may be obtained with the 26.Fn getrlimit 27call, and set with the 28.Fn setrlimit 29call. 30.Pp 31The 32.Fa resource 33parameter is one of the following: 34.Bl -tag -width RLIMIT_FSIZEAA 35.It Li RLIMIT_CORE 36The largest size (in bytes) 37.Xr core 38file that may be created. 39.It Li RLIMIT_CPU 40The maximum amount of cpu time (in seconds) to be used by 41each process. 42.It Li RLIMIT_DATA 43The maximum size (in bytes) of the data segment for a process; 44this defines how far a program may extend its break with the 45.Xr sbrk 2 46system call. 47.It Li RLIMIT_FSIZE 48The largest size (in bytes) file that may be created. 49.It Li RLIMIT_MEMLOCK 50The maximum size (in bytes) which a process may lock into memory 51using the 52.Xr mlock 2 53function. 54.It Li RLIMIT_NOFILE 55The maximum number of open files for this process. 56.It Li RLIMIT_NPROC 57The maximum number of simultaneous processes for this user id. 58.It Li RLIMIT_RSS 59The maximum size (in bytes) to which a process's resident set size may 60grow. 61This imposes a limit on the amount of physical memory to be given to 62a process; if memory is tight, the system will prefer to take memory 63from processes that are exceeding their declared resident set size. 64.It Li RLIMIT_STACK 65The maximum size (in bytes) of the stack segment for a process; 66this defines how far a program's stack segment may be extended. 67Stack extension is performed automatically by the system. 68.El 69.Pp 70A resource limit is specified as a soft limit and a hard limit. When a 71soft limit is exceeded a process may receive a signal (for example, if 72the cpu time or file size is exceeded), but it will be allowed to 73continue execution until it reaches the hard limit (or modifies 74its resource limit). The 75.Em rlimit 76structure is used to specify the hard and soft limits on a resource, 77.Bd -literal -offset indent 78struct rlimit { 79 quad_t rlim_cur; /* current (soft) limit */ 80 quad_t rlim_max; /* hard limit */ 81}; 82.Ed 83.Pp 84Only the super-user may raise the maximum limits. Other users 85may only alter 86.Fa rlim_cur 87within the range from 0 to 88.Fa rlim_max 89or (irreversibly) lower 90.Fa rlim_max . 91.Pp 92An 93.Dq infinite 94value for a limit is defined as 95.Dv RLIM_INFINITY . 96.Pp 97Because this information is stored in the per-process information, 98this system call must be executed directly by the shell if it 99is to affect all future processes created by the shell; 100.Ic limit 101is thus a built-in command to 102.Xr csh 1 . 103.Pp 104The system refuses to extend the data or stack space when the limits 105would be exceeded in the normal way: a 106.Xr break 107call fails if the data space limit is reached. 108When the stack limit is reached, the process receives 109a segmentation fault 110.Pq Dv SIGSEGV ; 111if this signal is not 112caught by a handler using the signal stack, this signal 113will kill the process. 114.Pp 115A file I/O operation that would create a file larger that the process' 116soft limit will cause the write to fail and a signal 117.Dv SIGXFSZ 118to be 119generated; this normally terminates the process, but may be caught. When 120the soft cpu time limit is exceeded, a signal 121.Dv SIGXCPU 122is sent to the 123offending process. 124.Sh RETURN VALUES 125A 0 return value indicates that the call succeeded, changing 126or returning the resource limit. A return value of -1 indicates 127that an error occurred, and an error code is stored in the global 128location 129.Va errno . 130.Sh ERRORS 131.Fn Getrlimit 132and 133.Fn setrlimit 134will fail if: 135.Bl -tag -width Er 136.It Bq Er EFAULT 137The address specified for 138.Fa rlp 139is invalid. 140.It Bq Er EPERM 141The limit specified to 142.Fn setrlimit 143would have 144raised the maximum limit value, and the caller is not the super-user. 145.El 146.Sh SEE ALSO 147.Xr csh 1 , 148.Xr quota 2 , 149.Xr sigaltstack 2 , 150.Xr sigvec 2 , 151.Xr sysctl 3 152.Sh BUGS 153There should be 154.Ic limit 155and 156.Ic unlimit 157commands in 158.Xr sh 1 159as well as in 160.Xr csh . 161.Sh HISTORY 162The 163.Nm 164function call appeared in 165.Bx 4.2 . 166