Sun Microsystems, Inc. gratefully acknowledges The Open Group for
permission to reproduce portions of its copyrighted documentation.
Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.
The Institute of Electrical and Electronics Engineers and The Open
Group, have given us permission to reprint portions of their
documentation.
In the following statement, the phrase ``this text'' refers to portions
of the system documentation.
Portions of this text are reprinted and reproduced in electronic form
in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6,
Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy
between these versions and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html.
This notice shall appear on any product containing this material.
The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
Copyright 1989 AT&T
Portions Copyright (c) 1994, X/Open Company Limited. All Rights Reserved.
Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
#include <sys/resource.h> int getrlimit(int resource, struct rlimit *rlp);
int setrlimit(int resource, const struct rlimit *rlp);
Limits on the consumption of a variety of system resources by a process and each process it creates may be obtained with the getrlimit() and set with setrlimit() functions.
Each call to either getrlimit() or setrlimit() identifies a specific resource to be operated upon as well as a resource limit. A resource limit is a pair of values: one specifying the current (soft) limit, the other a maximum (hard) limit. Soft limits may be changed by a process to any value that is less than or equal to the hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or equal to the soft limit. Only a process with {PRIV_SYS_RESOURCE} asserted in the effective set can raise a hard limit. Both hard and soft limits can be changed in a single call to setrlimit() subject to the constraints described above. Limits may have an "infinite" value of RLIM_INFINITY. The rlp argument is a pointer to struct rlimit that includes the following members:
rlim_t rlim_cur; /* current (soft) limit */ rlim_t rlim_max; /* hard limit */
The type rlim_t is an arithmetic data type to which objects of type int, size_t, and off_t can be cast without loss of information.
The possible resources, their descriptions, and the actions taken when the current limit is exceeded are summarized as follows: RLIMIT_CORE
The maximum size of a core file in bytes that may be created by a process. A limit of 0 will prevent the creation of a core file. The writing of a core file will terminate at this size.
The maximum amount of CPU time in seconds used by a process. This is a soft limit only. The SIGXCPU signal is sent to the process. If the process is holding or ignoring SIGXCPU, the behavior is scheduling class defined.
The maximum size of a process's heap in bytes. The brk(2) function will fail with errno set to ENOMEM.
The maximum size of a file in bytes that may be created by a process. A limit of 0 will prevent the creation of a file. The SIGXFSZ signal is sent to the process. If the process is holding or ignoring SIGXFSZ, continued attempts to increase the size of a file beyond the limit will fail with errno set to EFBIG.
One more than the maximum value that the system may assign to a newly created descriptor. This limit constrains the number of file descriptors that a process may create.
The maximum size of a process's stack in bytes. The system will not automatically grow the stack beyond this limit. Within a process, setrlimit() will increase the limit on the size of your stack, but will not move current memory segments to allow for that growth. To guarantee that the process stack can grow to the limit, the limit must be altered prior to the execution of the process in which the new stack size is to be used. Within a multithreaded process, setrlimit() has no impact on the stack size limit for the calling thread if the calling thread is not the main thread. A call to setrlimit() for RLIMIT_STACK impacts only the main thread's stack, and should be made only from the main thread, if at all. The SIGSEGV signal is sent to the process. If the process is holding or ignoring SIGSEGV, or is catching SIGSEGV and has not made arrangements to use an alternate stack (see sigaltstack(2)), the disposition of SIGSEGV will be set to SIG_DFL before it is sent.
The maximum size of a process's mapped address space in bytes. If this limit is exceeded, the brk(2) and mmap(2) functions will fail with errno set to ENOMEM. In addition, the automatic stack growth will fail with the effects outlined above.
This is the maximum size of a process's total available memory, in bytes. If this limit is exceeded, the brk(2), malloc(3C), mmap(2) and sbrk(2) functions will fail with errno set to ENOMEM. In addition, the automatic stack growth will fail with the effects outlined above.
Because limit information is stored in the per-process information, the shell builtin ulimit command must directly execute this system call if it is to affect all future processes created by the shell.
The value of the current limit of the following resources affect these implementation defined parameters:
| Limit Implementation Defined Constant |
| RLIMIT_FSIZE FCHR_MAX |
| RLIMIT_NOFILE OPEN_MAX |
When using the getrlimit() function, if a resource limit can be represented correctly in an object of type rlim_t, then its representation is returned; otherwise, if the value of the resource limit is equal to that of the corresponding saved hard limit, the value returned is RLIM_SAVED_MAX; otherwise the value returned is RLIM_SAVED_CUR.
When using the setrlimit() function, if the requested new limit is RLIM_INFINITY, the new limit will be "no limit"; otherwise if the requested new limit is RLIM_SAVED_MAX, the new limit will be the corresponding saved hard limit; otherwise, if the requested new limit is RLIM_SAVED_CUR, the new limit will be the corresponding saved soft limit; otherwise, the new limit will be the requested value. In addition, if the corresponding saved limit can be represented correctly in an object of type rlim_t, then it will be overwritten with the new limit.
The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is unspecified unless a previous call to getrlimit() returned that value as the soft or hard limit for the corresponding resource limit.
A limit whose value is greater than RLIM_INFINITY is permitted.
The exec family of functions also cause resource limits to be saved. See exec(2).
Upon successful completion, getrlimit() and setrlimit() return 0. Otherwise, these functions return -1 and set errno to indicate the error.
The getrlimit() and setrlimit() functions will fail if: EFAULT
The rlp argument points to an illegal address.
An invalid resource was specified; or in a setrlimit() call, the new rlim_cur exceeds the new rlim_max.
The limit specified to setrlimit() would have raised the maximum limit value and {PRIV_SYS_RESOURCE} is not asserted in the effective set of the current process.
The setrlimit() function may fail if: EINVAL
The limit specified cannot be lowered because current usage is already higher than the limit.
The getrlimit() and setrlimit() functions have transitional interfaces for 64-bit file offsets. See lf64(5).
The rlimit functionality is now provided by the more general resource control facility described on the setrctl(2) manual page. The actions associated with the resource limits described above are true at system boot, but an administrator can modify the local configuration to modify signal delivery or type. Application authors that utilize rlimits for the purposes of resource awareness should investigate the resource controls facility.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Standard |
rctladm(1M), brk(2), exec(2), fork(2), open(2), setrctl(2), sigaltstack(2), ulimit(2), getdtablesize(3C), malloc(3C), signal(3C), signal.h(3HEAD), sysconf(3C), attributes(5), lf64(5), privileges(5), resource_controls(5), standards(5)