getrlimit(2)




NAME

     getrlimit, setrlimit - control maximum system resource  con-
     sumption


SYNOPSIS

     #include <sys/resource.h>

     int getrlimit(int resource, struct rlimit *rlp);

     int setrlimit(int resource, const struct rlimit *rlp);


DESCRIPTION

     Limits on the consumption of a variety of  system  resources
     by  a  process  and  each process it creates may be obtained
     with the getrlimit() and set with setrlimit() functions.

     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 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 ID of super-user 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. Lim-
     its  may  have an "infinite" value of RLIM_INFINITY. The rlp
     argument is a pointer to struct  rlimit  that  includes  the
     following members:

     rlim_t    rlim_cur;     /* current (soft) limit */
     rlim_t    rlim_max;     /* hard limit */

     The type rlim_t is an arithmetic data type to which  objects
     of  type int, size_t, and  off_t can be cast without loss of
     information.

     The possible resources, their descriptions, and the  actions
     taken  when  the current limit is exceeded are summarized as
     follows:

     RLIMIT_CORE
           The maximum size of a core file in bytes that  may  be
           created  by  a process. A limit of  0 will prevent the
           creation of a core file. The writing of  a  core  file
           will terminate at this size.

     RLIMIT_CPU
           The maximum amount of CPU time in seconds  used  by  a
           process.  This  is  a  soft  limit  only.  The SIGXCPU
           signal is sent to the process. If the process is hold-
           ing or ignoring
            SIGXCPU, the behavior is scheduling class defined.

     RLIMIT_DATA
           The maximum size of a process's heap  in  bytes.   The
           brk(2) function will fail with  errno set to  ENOMEM.

     RLIMIT_FSIZE
           The maximum size of  a  file  in  bytes  that  may  be
           created  by  a process. A limit of  0 will prevent the
           creation of a file.  The SIGXFSZ signal is sent to the
           process.   If  the  process  is  holding  or  ignoring
           SIGXFSZ, continued attempts to increase the size of  a
           file  beyond  the  limit  will fail with  errno set to
           EFBIG.

     RLIMIT_NOFILE
           One more than the maximum value that  the  system  may
           assign  to a newly created descriptor. This limit con-
           strains the number of file descriptors that a  process
           may create.

     RLIMIT_STACK
           The maximum size of a process's stack  in  bytes.  The
           system  will  not  automatically grow the stack beyond
           this limit.

           Within a process, setrlimit() will increase the  limit
           on  the  size of your stack, but will not move current
           memory segments to allow for that growth. To guarantee
           that  the  process  stack  can  grow to the limit, the
           limit must be altered prior to the  execution  of  the
           process in which the new stack size is to be used.

           Within a multithreaded  process,  setrlimit()  has  no
           impact  on the stack size limit for the calling thread
           if the calling thread is not the main thread.  A  call
           to  setrlimit() for RLIMIT_STACK impacts only the main
           thread's stack, and should be made only from the  main
           thread, if at all.

           The SIGSEGV signal is sent to the process. If the pro-
           cess  is  holding or ignoring  SIGSEGV, or is catching
           SIGSEGV and has not made arrangements to use an alter-
           nate  stack  (see  sigaltstack(2)), the disposition of
           SIGSEGV will be set to  SIG_DFL before it is sent.

     RLIMIT_VMEM
           The maximum size of a process's mapped  address  space
           in  bytes.   If this limit is exceeded, the brk(2) and
           mmap(2)  functions  will  fail  with   errno  set   to
           ENOMEM.  In  addition, the automatic stack growth will
           fail with the effects outlined above.

     RLIMIT_AS
           This is the maximum size of a process's  total  avail-
           able memory, in bytes.  If this limit is exceeded, the
           brk(2), malloc(3C), mmap(2) and sbrk(2) functions will
           fail  with  errno  set  to  ENOMEM.  In  addition, the
           automatic stack growth will fail with the effects out-
           lined above.

     Because limit  information  is  stored  in  the  per-process
     information,  the shell builtin ulimit command must directly
     execute this system call if  it  is  to  affect  all  future
     processes created by the shell.

     The value of the current limit of  the  following  resources
     affect these implementation defined parameters:

                Limit              Implementation Defined Constant
     RLIMIT_FSIZE                             FCHR_MAX
     RLIMIT_NOFILE                            OPEN_MAX

     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 is RLIM_SAVED_MAX; oth-
     erwise the value returned is RLIM_SAVED_CUR.

     When using the setrlimit() function, if  the  requested  new
     limit  is  RLIM_INFINITY,  the new limit will be "no limit";
     otherwise if the requested new limit is RLIM_SAVED_MAX,  the
     new limit will be the corresponding saved hard limit; other-
     wise, if the requested new limit is RLIM_SAVED_CUR, the  new
     limit will be the corresponding saved soft limit; otherwise,
     the new limit will be the requested value. In  addition,  if
     the  corresponding  saved limit can be represented correctly
     in an object of type  rlim_t, then it  will  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.

     A limit whose value is greater than RLIM_INFINITY is permit-
     ted.

     The exec family of functions also cause resource  limits  to
     be saved.  See exec(2).


RETURN VALUES

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


ERRORS

     The getrlimit() and setrlimit() functions will fail if:

     EFAULT
           The rlp argument points to an illegal address.

     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 effective user of the
           calling process is not super-user.

     The setrlimit() function may fail if:

     EINVAL
           The limit specified cannot be lowered because  current
           usage is already higher than the limit.


USAGE

     The getrlimit() and setrlimit() functions have  transitional
     interfaces for 64-bit file offsets.  See lf64(5).

     The rlimit functionality is now provided by the more general
     resource control facility described on the setrctl(2) manual
     page.  The  actions  associated  with  the  resource  limits
     described  above are true at system boot, but an administra-
     tor can modify the  local  configuration  to  modify  signal
     delivery  or  type. Application authors that utilize rlimits
     for the purposes of resource  awareness  should  investigate
     the resource controls facility.


SEE ALSO

     brk(2),    exec(2),    fork(2),     open(2),     setrctl(2),
     sigaltstack(2),  ulimit(2),  getdtablesize(3C),  malloc(3C),
     signal(3C), signal(3HEAD), sysconf(3C), lf64(5)


Man(1) output converted with man2html