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