GETRLIMIT(3P)                                       POSIX Programmer's Manual                                      GETRLIMIT(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 enforce-
       ment 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 process' data segment, 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 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.

       RLIMIT_AS
              This is the maximum size of a process' total available memory, 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; oth-
       erwise, if the requested new limit is RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft  limit;  other-
       wise,  the  new limit shall be the requested value. In addition, if the corresponding saved limit can be represented cor-
       rectly 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
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec(),  fork(),  malloc(),  open(),  sigaltstack()   ,   sysconf(),   ulimit(),   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <stropts.h>, <sys/resource.h>

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,  Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                 GETRLIMIT(3P)