'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g2.getrlimit @(#)getrlimit	40.12 of 10/10/89
.\" Copyright 1989 AT&T
.\" ident	"@(#)svid_ba:ba_os/getrlimit	1.15"
.\" @(#)getrlimit 1.4 88/09/26 SMI; from UCB 4.3
'\" macro stdmacro
.\" Sun's getrlimit.2
.nr X
.if \nX=0 .ds x} getrlimit 2 "" "\&"
.if \nX=1 .ds x} getrlimit 2 ""
.if \nX=2 .ds x} getrlimit 2 "" "\&"
.if \nX=3 .ds x} getrlimit "" "" "\&"
.TH \*(x}
.SH NAME
\f4getrlimit\f1, \f4setrlimit\f1 \- control maximum system resource consumption
.SH SYNOPSIS
.ft 4
.nf
#include <sys/time.h>
#include <sys/resource.h>
.sp .5
int getrlimit(int resource, struct rlimit *rlp);
.sp .5
int setrlimit(int resource, const struct rlimit *rlp);
.fi
.ft 1
.SH DESCRIPTION
Limits on the consumption of a variety of system resources by a process
and each process it creates may be obtained with
\f4getrlimit\f1
and set with
\f4setrlimit\f1.
.P
Each call to either
\f4getrlimit\f1
or
\f4setrlimit\f1
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 an effective user
.SM ID
or superuser can raise a
hard
limit.
Both
hard
and
soft
limits can be changed in a single call to
\f4setrlimit\f1
subject to the constraints described above.
Limits may have an \(lqinfinite\(rq value of
\f4RLIM_INFINITY\f1.
\f2rlp\f1
is a pointer to
\f4struct\f1
\f4rlimit\f1
that includes the following members:
.sp .5
.ft 4
.ta .5i 1.25i 2.25i
.nf
	rlim_t	rlim_cur;	/* current (soft) limit */
	rlim_t	rlim_max;	/* hard limit */
.ft 1
.fi
.P
\f4rlim_t\f1 is an arithmetic data type to which objects of type
\f4int\f1, \f4size_t\f1, and \f4off_t\f1 can be cast without loss of information.
.P
The possible resources, their descriptions, and the actions taken
when current limit is exceeded, are summarized in the table below:
.TS
c c c
lfCW lw(1.5i) lw(1.5i) .
Resources	Description	Action
_
RLIMIT_CORE	T{
The maximum size of a core file in bytes
that may be created by a process.
A limit of \f40\f1 will prevent the creation of
a core file.
T}	T{
The writing of a core file
will terminate at this size.
T}
.sp .5
RLIMIT_CPU	T{
The maximum amount of CPU
time in seconds used by a process.
T}	T{
\f4SIGXCPU\f1 is sent to the process.
If the process is holding or ignoring
\f4SIGXCPU\f1, the behavior is scheduling
class defined.
T}
.sp .5
RLIMIT_DATA	T{
The maximum size of a process's heap in
bytes.
T}	T{
\f4brk\fP(2) will fail
with errno set to \f4ENOMEM\f1.
T}
.TE
.TS
c c c
lfCW lw(1.5i) lw(1.5i) .
Resources	Description	Action
_
RLIMIT_FSIZE	T{
The maximum size of a file in bytes that
may be created by a process.
A limit of \f40\f1 will prevent the
creation of a file.
T}	T{
\f4SIGXFSZ\f1 is sent to the
process.
If the process is holding or ignoring
\f4SIGXFSZ\f1, continued attempts
to increase the size of a file beyond
the limit will fail with errno set
to \f4EFBIG\f1.
T}
.sp .5
RLIMIT_NOFILE	T{
The maximum number of open
file descriptors that the
process can have.
T}	T{
Functions that create new
file descriptors will fail with errno set
to \f4EMFILE\f1.
T}
.sp .5
RLIMIT_STACK	T{
The maximum size of a process's
stack in bytes.
The system will not automatically grow
the stack beyond this limit.
T}	T{
\f4SIGSEGV\f1 is sent to the process.
If the process is holding or ignoring \f4SIGSEGV\f1, or is
catching \f4SIGSEGV\f1 and has not made
arrangements to use an alternate stack
[see \f4sigaltstack\fP(2)],
the disposition of \f4SIGSEGV\f1 will be set to \f4SIG_DFL\f1
before it is sent.
T}
.sp .5
RLIMIT_VMEM	T{
The maximum size of a process's mapped
address space in bytes.
T}	T{
\f4brk\fP(2) and \f4mmap\fP(2) functions will fail
with errno set to \f4ENOMEM\f1.
In addition, the automatic stack
growth will fail with the effects
outlined above.
T}
.TE
.br
.ne 3
.P
Because limit information is stored in the per-process information,
the shell builtin \f4ulimit\f1 must directly execute this system
call if it is to affect all future processes created by the shell.
.P
The value of the current limit of the following resources
affect these implementation defined constants:
.TS
center;
l l
lfCW lfCW.
Limit	Implementation Defined Constant
_
RLIMIT_FSIZE	FCHR_MAX
RLIMIT_NOFILE	OPEN_MAX
.TE
.SH RETURN VALUE
Upon successful completion, the function
\f4getrlimit\f1 returns a value of \f40\f1;
otherwise, it returns a value of \f4\-1\f1 and sets
\f4errno\f1 to indicate an error. 
.SH ERRORS
Under the following conditions, the functions 
\f4getrlimit\f1 and \f4setrlimit\f1 fail and 
set \f4errno\f1 to:
.TP .75i
\f4EINVAL\f1
if an invalid \f2resource\f1
was specified; or in a
\f4setrlimit\f1
call, the new
\f4rlim_cur\f1
exceeds the new
\f4rlim_max\f1.
.TP
\f4EPERM\f1
if the limit specified to
\f4setrlimit\f1
would have raised the maximum limit value,
and the caller is the superuser
.SH "SEE ALSO"
.\" Suns brk.2 and signal.2
.na
\f4malloc\fP(3C),
\f4open\fP(2),
\f4sigaltstack\fP(2),
\f4signal\fP(5).
.ad
