Ubuntu Manpage: This manual page is part of the POSIX Programmer's Manual. The Linux implementation of

Provided by: manpages-posix-dev_2013a-2_all

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.

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

The getrlimit() function shall get, and the setrlimit() function shall set, limits on the
consumption of a variety of resources.

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>, shall be considered to be larger
than any other limit value. If a call to getrlimit() 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 setrlimit() shall
inhibit 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 shall prevent the creation of a core file. If this
limit is exceeded, the writing of a core file shall 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 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.

RLIMIT_DATA This is the maximum size of a data segment of the process, in bytes. If
this limit is exceeded, the malloc() function shall 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 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 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 a file descriptor shall 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 the initial thread's 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.

RLIMIT_AS This is the maximum size of total available memory of the process, in bytes.
If this limit is exceeded, the malloc() and mmap() functions shall fail with
errno set to [ENOMEM]. In addition, the automatic stack growth fails 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 shall be RLIM_SAVED_MAX; otherwise, the value returned shall be RLIM_SAVED_CUR.

When using the setrlimit() 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 rlim_t then it shall 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-defined. For example, some implementations permit a limit whose
value is greater than RLIM_INFINITY and others do not.

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

RETURN VALUE

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

ERRORS

       The getrlimit() and setrlimit() functions shall 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.

       The following sections are informative.

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 behavior may occur.

       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.

RATIONALE

       It  should  be  noted  that  RLIMIT_STACK applies ``at least'' to the stack of the initial
       thread in the process, and not to the sum of all the stacks in the process, as that  would
       be  very  limiting  unless the value is so big as to provide no value at all with a single
       thread.

FUTURE DIRECTIONS

       None.

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .