The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

getrlimit, setrlimit - control maximum resource consumption

 SYNOPSIS



#include <sys/resource.h>

int getrlimit(int resource, struct rlimit *rlp);
int setrlimit(int resource, const struct rlimit *rlp);

 DESCRIPTION

Limits on the consumption of a variety of resources by the calling process may be obtained with getrlimit() and set with setrlimit().

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 represented by an rlimit structure. The rlim_cur member specifies the current or soft limit and the rlim_max member specifies the maximum or 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 appropriate privileges 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.

The value RLIM_INFINITY, defined in <sys/resource.h>, is considered to be larger than any other limit value. If a call to getrlimit() returns RLIM_INFINITY for a resource, it means the implementation does not enforce limits on that resource. Specifying RLIM_INFINITY as any resource limit value on a successful call to setrlimit() inhibits enforcement of that resource limit.

The following resources are defined:

RLIMIT_CORE
This is 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. If this limit is exceeded, the writing of a core file will terminate at this size.
RLIMIT_CPU
This is the maximum amount of CPU time in seconds used by a process. If this limit is exceeded, SIGXCPU is generated for the process. If the process is catching or ignoring SIGXCPU, or all threads belonging to that process are blocking SIGXCPU, the behaviour is unspecified.
RLIMIT_DATA
This is the maximum size of a process' data segment in bytes. If this limit is exceeded, the brk(), malloc() and sbrk() functions will fail with errno set to [ENOMEM].
RLIMIT_FSIZE
This is the maximum size of a file in bytes that may be created by a process. If a write or truncate operation would cause this limit to be exceeded, SIGXFSZ is generated for the thread. If the thread is blocking, or the process is catching or ignoring SIGXFSZ, continued attempts to increase the size of a file from end-of-file to beyond the limit will fail with errno set to [EFBIG].
RLIMIT_NOFILE
This is a number one greater than the maximum value that the system may assign to a newly-created descriptor. If this limit is exceeded, functions that allocate new file descriptors may fail with errno set to [EMFILE]. This limit constrains the number of file descriptors that a process may allocate.
RLIMIT_STACK
This is the maximum size of a process' stack in bytes. The implementation will not automatically grow the stack beyond this limit. If this limit is exceeded, SIGSEGV is generated for the thread. If the thread is blocking SIGSEGV, or the process is ignoring or catching SIGSEGV and has not made arrangements to use an alternate stack, the disposition of SIGSEGV will be set to SIG_DFL before it is generated.
RLIMIT_AS
This is the maximum size of a process' total available memory, in bytes. If this limit is exceeded, the brk(), malloc(), mmap() and sbrk() functions will fail with errno set to [ENOMEM]. In addition, the automatic stack growth will fail with the effects outlined above.

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.

The determination of whether a limit can be correctly represented in an object of type rlim_t is implementation-dependent. For example, some implementations permit a limit whose value is greater than RLIM_INFINITY and others do not.

The exec family of functions also cause resource limits to be saved.

 RETURN VALUE

Upon successful completion, getrlimit() and setrlimit() return 0. Otherwise, these functions return -1 and set errno to indicate the error.

 ERRORS

The getrlimit() and setrlimit() functions will fail if:
[EINVAL]
An invalid resource was specified; or in a setrlimit() call, the new rlim_cur exceeds the new rlim_max.
[EPERM]
The limit specified to setrlimit() would have raised the maximum limit value, and the calling process does not have appropriate privileges.

The setrlimit() function may fail if:

[EINVAL]
The limit specified cannot be lowered because current usage is already higher than the limit.

 EXAMPLES

None.

 APPLICATION USAGE

If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE to less than the value of _POSIX_OPEN_MAX from <limits.h>, unexpected behaviour may occur.

 FUTURE DIRECTIONS

None.

 SEE ALSO

brk(), exec, fork(), malloc(), open(), sbrk(), sigaltstack(), sysconf(), ulimit(), <stropts.h>, <sys/resource.h>.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]