Seth Woolley's Man Viewer

getrlimit(2) - getrlimit, getrusage, setrlimit, getrlimit, getrusage, setrlimit - get/set resource limits and usage - man 2 getrlimit

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

GETRLIMIT(2)               Linux Programmer's Manual              GETRLIMIT(2)



NAME
       getrlimit, getrusage, setrlimit - get/set(7,n,1 builtins) resource limits and usage

SYNOPSIS
       #include <sys/time.h>
       #include <sys/resource.h>
       #include <unistd.h>

       int getrlimit(int resource, struct rlimit *rlim);
       int getrusage(int who, struct rusage *usage);
       int setrlimit(int resource, const struct rlimit *rlim);

DESCRIPTION
       getrlimit and setrlimit get and set(7,n,1 builtins) resource limits respectively.  Each
       resource has an associated soft and  hard  limit,  as  defined  by  the
       rlimit  structure  (the  rlim  argument  to  both getrlimit() and setr-
       limit()):

            struct rlimit {
                rlim_t rlim_cur;   /* Soft limit */
                rlim_t rlim_max;   /* Hard limit (ceiling
                                      for rlim_cur) */
            };

       The soft limit is the value that the kernel  enforces  for  the  corre-
       sponding  resource.   The  hard  limit  acts  as a ceiling for the soft
       limit: an unprivileged process may only set(7,n,1 builtins) its soft limit to  a  value
       in(1,8)  the range from 0 up to the hard limit, and (irreversibly) lower its
       hard  limit.   A  privileged  process  (under  Linux:  one   with   the
       CAP_SYS_RESOURCE capability) may make arbitrary changes to either limit
       value.

       The value RLIM_INFINITY denotes no limit on a  resource  (both  in(1,8)  the
       structure  returned by getrlimit() and in(1,8) the structure passed to setr-
       limit()).

       resource must be one of:

       RLIMIT_AS
              The maximum size of the process's virtual(5,8) memory (address space)
              in(1,8)  bytes.   This  limit  affects  calls  to brk(2), mmap(2) and
              mremap(2), which fail with the error(8,n) ENOMEM upon exceeding  this
              limit.  Also automatic stack expansion will fail (and generate a
              SIGSEGV that kills the process when no alternate stack has  been
              made  available).  Since the value is a long, on machines with a
              32-bit long either this limit is at most 2 GiB, or this resource
              is unlimited.

       RLIMIT_CORE
              Maximum  size  of  core file. When 0 no core dump files are cre-
              ated.  When nonzero, larger dumps are truncated to this size.

       RLIMIT_CPU
              CPU time(1,2,n) limit in(1,8) seconds.  When the process  reaches  the  soft
              limit, it is sent a SIGXCPU signal.  The default action for this
              signal(2,7) is to terminate the process.  However, the signal(2,7) can  be
              caught,  and the handler can return control to the main program.
              If the process continues to consume CPU time(1,2,n), it  will  be  sent
              SIGXCPU  once  per  second  until  the hard limit is reached, at
              which time(1,2,n) it is sent SIGKILL.   (This  latter  point  describes
              Linux  2.2  and 2.4 behaviour.  Implementations vary in(1,8) how they
              treat processes which continue to consume CPU time(1,2,n) after  reach-
              ing  the  soft  limit.  Portable applications that need to catch
              this signal(2,7) should perform an  orderly  termination  upon  first
              receipt of SIGXCPU.)

       RLIMIT_DATA
              The  maximum  size  of  the  process's data segment (initialized
              data, uninitialized data, and heap).  This limit  affects  calls
              to  brk()  and  sbrk(),  which  fail  with the error(8,n) ENOMEM upon
              encountering the soft limit of this resource.

       RLIMIT_FSIZE
              The maximum size of files that the process may create.  Attempts
              to  extend  a  file(1,n)  beyond  this  limit result in(1,8) delivery of a
              SIGXFSZ signal.  By default, this signal(2,7) terminates  a  process,
              but  a  process can catch this signal(2,7) instead, in(1,8) which case the
              relevant system call (e.g., write(1,2)(), truncate(2,7)()) fails with  the
              error(8,n) EFBIG.

       RLIMIT_LOCKS
              A  limit  on  the  combined  number of flock(1,2)() locks and fcntl()
              leases that this process may establish.  (Early Linux 2.4 only.)

       RLIMIT_MEMLOCK
              The maximum number of bytes of virtual(5,8) memory that may be locked
              into RAM using mlock() and mlockall().

       RLIMIT_NOFILE
              Specifies a value one greater than the maximum  file(1,n)  descriptor
              number  that  can  be opened by this process.  Attempts (open(2,3,n)(),
              pipe(2,8)(), dup(), etc.)  to  exceed  this  limit  yield  the  error(8,n)
              EMFILE.

       RLIMIT_NPROC
              The maximum number of processes that can be created for the real
              user ID of the calling process.  Upon encountering  this  limit,
              fork() fails with the error(8,n) EAGAIN.

       RLIMIT_RSS
              Specifies  the  limit  (in(1,8)  pages) of the process's resident set(7,n,1 builtins)
              (the number of virtual(5,8) pages resident in(1,8) RAM).  This limit  only
              has  effect  in(1,8) Linux 2.4 onwatrds, and there only affects calls
              to madvise() specifying MADVISE_WILLNEED.

       RLIMIT_STACK
              The maximum size of the process stack, in(1,8) bytes.  Upon  reaching
              this  limit, a SIGSEGV signal(2,7) is generated.  To handle this sig-
              nal(2,7), a process must employ an alternate  signal(2,7)  stack  (sigalt-
              stack(2)).

       RLIMIT_OFILE is the BSD name for RLIMIT_NOFILE.

       getrusage  returns  the  current  resource  usages, for a who of either
       RUSAGE_SELF or RUSAGE_CHILDREN.  The former asks for resources used  by
       the  current  process,  the  latter  for resources used by those of its
       children that have terminated and have been waited for.

            struct rusage {
                struct timeval ru_utime; /* user time(1,2,n) used */
                struct timeval ru_stime; /* system time(1,2,n) used */
                long   ru_maxrss;        /* maximum resident set(7,n,1 builtins) size */
                long   ru_ixrss;         /* integral shared memory size */
                long   ru_idrss;         /* integral unshared data size */
                long   ru_isrss;         /* integral unshared stack size */
                long   ru_minflt;        /* page reclaims */
                long   ru_majflt;        /* page faults */
                long   ru_nswap;         /* swaps */
                long   ru_inblock;       /* block input operations */
                long   ru_oublock;       /* block output operations */
                long   ru_msgsnd;        /* messages sent */
                long   ru_msgrcv;        /* messages received */
                long   ru_nsignals;      /* signals received */
                long   ru_nvcsw;         /* voluntary context switches */
                long   ru_nivcsw;        /* involuntary context switches */
            };

RETURN VALUE
       On success, zero is returned.  On error(8,n), -1 is returned, and  errno  is
       set(7,n,1 builtins) appropriately.

ERRORS
       EFAULT rlim or usage points outside the accessible address space.

       EINVAL getrlimit  or  setrlimit  is  called  with  a  bad  resource, or
              getrusage is called with a bad who.

       EPERM  An unprivileged process tried to use setrlimit() to  increase  a
              soft   or   hard   limit  above  the  current  hard  limit;  the
              CAP_SYS_RESOURCE capability is required to  do  this.   Or,  the
              process  tried  to  use setrlimit() to increase the soft or hard
              RLIMIT_NOFILE limit above the current kernel maximum  (NR_OPEN).

CONFORMING TO
       SVr4, BSD 4.3

NOTE
       Including <sys/time.h> is not required these days, but increases porta-
       bility.  (Indeed, struct timeval is defined in(1,8) <sys/time.h>.)

       On Linux, if(3,n) the disposition of SIGCHLD is  set(7,n,1 builtins)  to  SIG_IGN  then  the
       resource  usages  of  child processes are automatically included in(1,8) the
       value returned by RUSAGE_CHILDREN, although POSIX  1003.1-2001  explic-
       itly prohibits this.

       The above struct was taken from BSD 4.3 Reno.  Not all fields are mean-
       ingful under Linux.   Right  now  (Linux  2.4,  2.6)  only  the  fields
       ru_utime,  ru_stime, ru_minflt, ru_majflt, and ru_nswap are maintained.

SEE ALSO
       dup(2), fcntl(2), fork(2),  mlock(2),  mlockall(2),  mmap(2),  open(2,3,n)(2),
       quotactl(2),  sbrk(2),  wait3(2), wait4(2), malloc(3), ulimit(3), capa-
       bilities(7), signal(2,7)(7)



Linux                             2004-06-16                      GETRLIMIT(2)

References for this manual (incoming links)