getrlimit(2) getrlimit(2)
NAME
getrlimit, setrlimit, getrlimit64, setrlimit64 - control system
resource usage
SYNOPSIS
#include <sys/resource.h>
int getrlimit(int resource, struct rlimit *rlp);
int setrlimit(int resource, const struct rlimit *rlp);
int getrlimit64(int resource, struct rlimit64 *rlp);
int setrlimit64(int resource, const struct rlimit64 *rlp);
DESCRIPTION
Limits on the consumption of a variety of system resources by a pro-
cess and each process it creates 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 rlimcur member
specifies the current or soft limit and the rlimmax 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 RLIMINFINITY, defined in <sys/resource.h>, is considered to
be larger than any other limit value. If a call to getrlimit() returns
RLIMINFINITY for a resource, it means the implementation does not
enforce limits on that resource. Specifying RLIMINFINITY as any
resource limit value on a successful call to setrlimit() inhibits
enforcement of that resource limit.
When using the getrlimit() function, if a resource limit can be repre-
sented correctly in an object of type rlimt 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
RLIMSAVEDMAX; otherwise the value returned is RLIMSAVEDCUR.
When using the setrlimit() function, if the requested new limit is
RLIMINFINITY the new limit will be "no limit"; otherwise if the
requested new limit is RLIMSAVEDMAX the new limit will be the corre-
sponding saved hard limit; otherwise if the requested new limit is
RLIMSAVEDCUR 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 rlimt then it will be overwritten with the new limit.
Page 1 Reliant UNIX 5.44 Printed 11/98
getrlimit(2) getrlimit(2)
The result of setting a limit to RLIMSAVEDMAX or RLIMSAVEDCUR 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 rlimt is implementation-dependent. For example,
some implementations permit a limit whose value is greater than
RLIMINFINITY and others do not.
The exec family of functions also cause resource limits to be saved
[see exec(2)].
There is no functional difference between getrlimit()/setrlimit() and
getrlimit64()/setrlimit64(), except for the interpretation of
rlimit/rlimit64 [see resource(5)].
The following resources are defined:
RLIMITCORE 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.
RLIMITCPU 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 blocking,
catching or ignoring SIGXCPU, the behavior is unspeci-
fied.
RLIMITDATA 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.
RLIMITFSIZE This is 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. If a write or truncate operation
would cause this limit to be exceeded, SIGXFSZ is gen-
erated for the process. If the process is blocking,
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.
RLIMITNOFILE This is a number one greater than the maximum value
that the system may assign to a newly-created descrip-
tor. If this limit is exceeded, functions that allo-
cate new file descriptors may fail with errno set to
EMFILE. This limit constrains the number of file
descriptors that a process may allocate.
Page 2 Reliant UNIX 5.44 Printed 11/98
getrlimit(2) getrlimit(2)
RLIMITSTACK 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 process. If the process
is blocking or ignoring SIGSEGV, or is catching
SIGSEGV and has not made arrangements to use an alter-
nate stack, the disposition of SIGSEGV will be set to
SIGDFL before it is generated.
RLIMITAS or RLIMITVMEM
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.
Because limit information is stored in the per-process information,
the shell builtin ulimit(1) must directly execute this system call if
it is to affect all future processes created by the shell.
RETURN VALUE
Upon successful completion, getrlimit() and setrlimit() return 0. Oth-
erwise, these functions return -1 and set errno to indicate the error.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
Under the following conditions, the functions getrlimit() and
setrlimit() fail and set errno to:
EINVAL An invalid resource was specified; or in a setrlimit() call,
the new rlimcur exceeds the new rlimmax.
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.
NOTES
If a process attempts to set the hard limit or soft limit for
RLIMITNOFILE to less than the value of POSIXOPENMAX from
<limits.h> unexpected behavior may occur.
Page 3 Reliant UNIX 5.44 Printed 11/98
getrlimit(2) getrlimit(2)
These functions map limits that they cannot represent correctly to and
from RLIMSAVEDMAX and RLIMSAVEDCUR. These values do not require
any special handling by programs. They may be thought of as tokens
that the kernel hands out to programs that cannot handle the real
answer, and that remind the kernel, when the tokens come back from the
user, of what value is really meant.
If setrlimit() fails for any reason (for example, EPERM), the resource
limits and saved resource limits remain unchanged.
Few, if any, programs will need to refer explicitly to RLIMSAVEDMAX
or RLIMSAVEDCUR. Those that do should not use them in C-language
switch cases since they may have the same value in some implementa-
tions.
A limit that can be represented correctly in an object of type rlimt
is either "no limit", which is represented with RLIMINFINITY, or has
a value not equal to any of RLIMINFINITY or RLIMSAVEDMAX or
RLIMSAVEDCUR and which can be represented correctly in an object of
type rlimt and which meets any additional implementation-specific
criteria for correct representation.
SEE ALSO
ulimit(1), brk(2), exec(2), fork(2), open(2), sigaltstack(2),
ulimit(2), getdtablesize(3), malloc(3C), sysconf(3C), lfs(5),
resource(5), signal(5), stropts(5).
Page 4 Reliant UNIX 5.44 Printed 11/98