Tribblix: manual page: getrlimit.2

GETRLIMIT(2) System Calls GETRLIMIT(2)

NAME

getrlimit, setrlimit - control maximum system 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 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.

RLIMIT_CPU
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.

RLIMIT_DATA
The maximum size of a process's heap in bytes. The
brk(2) function will fail with errno set to
ENOMEM.

RLIMIT_FSIZE
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.

RLIMIT_NOFILE
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.

RLIMIT_STACK
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.

RLIMIT_VMEM
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.

RLIMIT_AS
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).

RETURN VALUES

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:

EFAULT
The rlp argument points to an illegal address.

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 {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.

USAGE

The getrlimit() and setrlimit() functions have transitional
interfaces for 64-bit file offsets. See lf64(7).

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.

ATTRIBUTES