.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "GETRLIMIT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" getrlimit 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
getrlimit, setrlimit \- control maximum resource consumption
.SH SYNOPSIS
.LP
\fB#include <sys/resource.h>
.br
.sp
int getrlimit(int\fP \fIresource\fP\fB, struct rlimit *\fP\fIrlp\fP\fB);
.br
int setrlimit(int\fP \fIresource\fP\fB, const struct rlimit *\fP\fIrlp\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIgetrlimit\fP() function shall get, and the \fIsetrlimit\fP()
function shall set, limits on the consumption of a variety
of resources.
.LP
Each call to either \fIgetrlimit\fP() or \fIsetrlimit\fP() identifies
a specific resource to be operated upon as well as a
resource limit. A resource limit is represented by an \fBrlimit\fP
structure. The \fIrlim_cur\fP member specifies the current or
soft limit and the \fIrlim_max\fP 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 \fIsetrlimit\fP() subject to the constraints
described above.
.LP
The value RLIM_INFINITY, defined in \fI<sys/resource.h>\fP, shall
be
considered to be larger than any other limit value. If a call to \fIgetrlimit\fP()
returns RLIM_INFINITY for a resource, it means
the implementation shall not enforce limits on that resource. Specifying
RLIM_INFINITY as any resource limit value on a successful
call to \fIsetrlimit\fP() shall inhibit enforcement of that resource
limit.
.LP
The following resources are defined:
.TP 7
RLIMIT_CORE
This is the maximum size of a \fBcore\fP file, in bytes, that may
be created by a process. A limit of 0 shall prevent the
creation of a \fBcore\fP file. If this limit is exceeded, the writing
of a \fBcore\fP file shall terminate at this size.
.TP 7
RLIMIT_CPU
This is the maximum amount of CPU time, in seconds, used by a process.
If this limit is exceeded, SIGXCPU shall be generated
for the process. If the process is catching or ignoring SIGXCPU, or
all threads belonging to that process are blocking SIGXCPU, the
behavior is unspecified.
.TP 7
RLIMIT_DATA
This is the maximum size of a process' data segment, in bytes. If
this limit is exceeded, the \fImalloc\fP() function shall fail with
\fIerrno\fP set to [ENOMEM].
.TP 7
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 shall be 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 shall fail with
\fIerrno\fP set to [EFBIG].
.TP 7
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 a file descriptor shall fail with
\fIerrno\fP set to [EMFILE]. This limit constrains the number
of file descriptors that a process may allocate.
.TP 7
RLIMIT_STACK
This is the maximum size of a process' stack, in bytes. The implementation
does not automatically grow the stack beyond this
limit. If this limit is exceeded, SIGSEGV shall be 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 shall be set to
SIG_DFL before it is generated.
.TP 7
RLIMIT_AS
This is the maximum size of a process' total available memory, in
bytes. If this limit is exceeded, the \fImalloc\fP() and \fImmap\fP()
functions shall fail with
\fIerrno\fP set to [ENOMEM]. In addition, the automatic stack growth
fails with the effects outlined above.
.sp
.LP
When using the \fIgetrlimit\fP() function, if a resource limit can
be represented correctly in an object of type \fBrlim_t\fP,
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 shall be RLIM_SAVED_MAX; otherwise, the
value returned shall be RLIM_SAVED_CUR.
.LP
When using the \fIsetrlimit\fP() function, if the requested new limit
is RLIM_INFINITY, the new limit shall be "no limit'';
otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit
shall be the corresponding saved hard limit; otherwise, if
the requested new limit is RLIM_SAVED_CUR, the new limit shall be
the corresponding saved soft limit; otherwise, the new limit
shall be the requested value. In addition, if the corresponding saved
limit can be represented correctly in an object of type
\fBrlim_t\fP then it shall be overwritten with the new limit.
.LP
The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR
is unspecified unless a previous call to \fIgetrlimit\fP()
returned that value as the soft or hard limit for the corresponding
resource limit.
.LP
The determination of whether a limit can be correctly represented
in an object of type \fBrlim_t\fP is implementation-defined.
For example, some implementations permit a limit whose value is greater
than RLIM_INFINITY and others do not.
.LP
The \fIexec\fP family of functions shall cause resource limits to
be saved.
.SH RETURN VALUE
.LP
Upon successful completion, \fIgetrlimit\fP() and \fIsetrlimit\fP()
shall return 0. Otherwise, these functions shall return -1
and set \fIerrno\fP to indicate the error.
.SH ERRORS
.LP
The \fIgetrlimit\fP() and \fIsetrlimit\fP() functions shall fail if:
.TP 7
.B EINVAL
An invalid \fIresource\fP was specified; or in a \fIsetrlimit\fP()
call, the new \fIrlim_cur\fP exceeds the new
\fIrlim_max\fP.
.TP 7
.B EPERM
The limit specified to \fIsetrlimit\fP() would have raised the maximum
limit value, and the calling process does not have
appropriate privileges.
.sp
.LP
The \fIsetrlimit\fP() function may fail if:
.TP 7
.B EINVAL
The limit specified cannot be lowered because current usage is already
higher than the limit.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
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 \fI<limits.h>\fP,
unexpected behavior may occur.
.LP
If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE
to less than the highest currently open file
descriptor +1, unexpected behavior may occur.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIexec\fP(), \fIfork\fP(), \fImalloc\fP(), \fIopen\fP(), \fIsigaltstack\fP()
,
\fIsysconf\fP(), \fIulimit\fP(), the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP, \fI<sys/resource.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version 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 .