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 (consult the correspond-
       ing 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 privi-
       leges 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 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() func-
	      tions 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  addi-
       tion,  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  indi-
       cate 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 Technol-
       ogy -- 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 .

IEEE
/The Open Group						       2003							     GETRLIMIT(3P)