getrlimit(2)

getrlimit, getrlimit64, setrlimit, setrlimit64 -- control maximum system resource consumption

Synopsis

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

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

   int getrlimit64(int resource, struct rlimit64 *rlp);
   

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

   int setrlimit64(int resource, const struct rlimit64 *rlp);

Description

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

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 appropriate privilege (P_SYSOPS) 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.

For getrlimit, 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, otherwise the value returned is RLIM_SAVED_CUR.

For setrlimit, 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. Otherwise, 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 that can be represented correctly in an object of type rlim_t is either ``no limit'', which is represented with RLIM_INFINITY, or RLIM_SAVED_MAX or RLIM_SAVED_CUR and which can be represented correctly in an object of type rlim_t and which meets any additional implementation-specific criteria for correct representation.

The determination of whether a limit can be correctly represented in an object of type rlim_t is implementation-dependent. For example, some implementations permit a limit whose value is greater than RLIM_INFINITY and others do not.

Limits may have an infinite value of RLIM_INFINITY.

For getrlimit and setrlimit, rlp is a pointer to struct rlimit that includes the following members: 

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

For getrlimit64 and setrlimit64, rlp is a pointer to struct rlimit64 that includes the following members: 

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

In addition, getrlimit64 and setrlimit64 return the following values, which are defined in the sys/resource.h header.


RLIM64_INFINITY
A value of type rlim64_t indicating no limit.

RLIM64_SAVED_MAX
A value of type rlim64_t indicating an unrepresentable saved hard limit.

RLIM64_SAVED_CUR
A value of type rlim64_t indicating an unrepresentable saved soft limit.

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 current limit is exceeded, are summarized in the table below:

Resources Description Action
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. SIGXCPU is sent to the process. If the process is holding or ignoring SIGXCPU, the behavior is scheduling class defined.
RLIMIT_DATA The maximum size of a process's heap in bytes. brk(2) will fail with errno set to ENOMEM. 

 Resources     Description         Action
 RLIMIT_CORE   The maximum size    The writing of a
               of a core file in   core file will
               bytes that may be   terminate at this
               created by a        size.
               process.  A limit
               of 0 will prevent
               the creation of a
               core file.
 RLIMIT_CPU    The maximum         SIGXCPU is sent
               amount of CPU       to the process.
               time in seconds     If the process is
               used by a           holding or
               process.            ignoring SIGXCPU,
                                   the behavior is
                                   scheduling class
                                   defined.
 RLIMIT_DATA   The maximum size    brk(2) will fail
               of a process's      with errno set to
               heap in bytes.      ENOMEM.

Resources Description Action
RLIMIT_FSIZE The maximum size of a file in bytes that may be created by a process. SIGXFSZ 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 The maximum number of open file descriptors that the process can have. Functions that create new file descriptors will fail with errno set to EMFILE.
RLIMIT_STACK The maximum size of a process's single ``autogrow'' stack in bytes. The system will not automatically grow the stack beyond this limit. SIGSEGV is sent to the offending thread. If that thread is holding SIGSEGV or if the containing process is ignoring SIGSEGV or is catching SIGSEGV and the underlying LWP has not made arrangements to use an alternate stack [see sigaltstack(2)], the disposition of SIGSEGV will be set to SIG_DFL before it is sent. Consequently, the containing process is terminated.
RLIMIT_VMEM The maximum size of a process's mapped address space in bytes. brk(2) and mmap(2) functions will fail with errno set to ENOMEM. 

 Resources       Description         Action
 RLIMIT_FSIZE    The maximum size    SIGXFSZ is sent
                 of a file in        to the process.
                 bytes that may be   If the process is
                 created by a        holding or
                 process.            ignoring SIGXFSZ,
                                     continued
                                     attempts to
                                     increase the size
                                     of a file beyond
                                     the limit will
                                     fail with errno
                                     set to EFBIG.
 RLIMIT_NOFILE   The maximum         Functions that
                 number of open      create new file
                 file descriptors    descriptors will
                 that the process    fail with errno
                 can have.           set to EMFILE.
 RLIMIT_STACK    The maximum size    SIGSEGV is sent
                 of a process's      to the offending
                 single              thread.  If that
                 ``autogrow''        thread is holding
                 stack in bytes.     SIGSEGV or if the
                 The system will     containing
                 not automatically   process is
                 grow the stack      ignoring SIGSEGV
                 beyond this         or is catching
                 limit.              SIGSEGV and the
                                     underlying LWP
                                     has not made
                                     arrangements to
                                     use an alternate
                                     stack [see
                                     sigaltstack(2)
                                     the disposition
                                     of SIGSEGV will
                                     be set to SIG_DFL
                                     before it is
                                     sent.
                                     Consequently, the
                                     containing
                                     process is
                                     terminated.
 RLIMIT_VMEM     The maximum size    brk(2) and
                 of a process's      mmap(2) functions
                 mapped address      will fail with
                 space in bytes.     errno set to
                                     ENOMEM.


Because limit information is stored in the per-process information, the shell builtin ulimit 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 constants:

Limit Implementation Defined Constant
RLIMIT_FSIZE FCHR_MAX
RLIMIT_NOFILE OPEN_MAX 

 Limit           Implementation Defined Constant
 RLIMIT_FSIZE    FCHR_MAX
 RLIMIT_NOFILE   OPEN_MAX

Return values

On success, getrlimit returns 0. On failure, getrlimit returns -1 and sets errno to identify the error.

Errors

Under the following conditions, the functions getrlimit and setrlimit fail and set errno to:

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 privilege (P_SYSOPS).

References

intro(2), malloc(3C), open(2), privilege(5), sigaltstack(2), signal(5)

Notices

Considerations for threads programming

These resource limits are an attribute of the containing process and are shared by sibling threads.

Also, see description of RLIMIT_STACK above.

Considerations for large file support

Few, if any, programs will need to refer explicitly to RLIM_SAVED_MAX or RLIM_SAVED_CUR. Those that do should not use them in C language switch cases, because they may have the same value. Typically, they also have the same value as RLIM_INFINITY. See sys/resource.h for their definitions.

Large files (larger than 2GB) are supported in this release. However, file size limits are only discretely settable up to 2GB (more precisely, 2GB - 1 byte). Setting a file size limit greater than or equal to 2GB - 1 has the equivalent effect to setting the file size limit to unlimited. unlimited is currently defined as RLIM_INFINITY (see resource.h).

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004