setrlimit(), setrlimit64()

Set the limit on a system resource

Synopsis:

#include <sys/resource.h>

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

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

Arguments:

resource
The resource whose limit you want to set. For a list of the possible resources, their descriptions, and the actions taken when the current limit is exceeded, see below.
rlp
A pointer to a rlimit or rlimit64 structure that specifies the limit that you want to set for the resource. The rlimit and rlimit64 structures include at least the following members:
rlim_t rlim_cur; /* current (soft) limit */
rlim_t rlim_max; /* hard limit */
  

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

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The setrlimit() and setrlimit64() functions set the limits on the consumption of a variety of system resources by a process and each process it creates. The setrlimit64() function is a large-file support version of setrlimit().

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see "Classification" in What's in a Function Description?

Each call to 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.

A process can change soft limits to any value that's less than or equal to the hard limit. A process may (irreversibly) lower its hard limit to any value that's greater than or equal to the soft limit. Only a process with the PROCMGR_AID_RLIMIT ability enabled (see procmgr_ability()) 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. Limits may have an "infinite" value of RLIM_INFINITY.

Note: RLIM_INFINITY is a special value, and its actual numerical value doesn't represent a valid size of virtual memory or the address space.

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

Resource Classification Description Action
RLIMIT_AS POSIX The maximum size, in bytes, of a process's mapped address space. If the limit is exceeded, mmap() fails with errno set to ENOMEM. In addition, the automatic stack growth fails with the effects outlined above.
RLIMIT_CORE POSIX The maximum size, in bytes, of a core file that a process may create. A limit of 0 prevents the creation of a core file. The writing of a core file terminates at this size.
RLIMIT_CPU POSIX The maximum amount of CPU time, in seconds, that a process may use. This is a soft limit only. SIGXCPU is sent to the process. If the process is holding or ignoring SIGXCPU, the behavior is defined by the scheduling class.
RLIMIT_DATA POSIX The maximum size, in bytes, that a process's heap may be. In QNX Neutrino, RLIMIT_DATA covers all mappings made by the process that are MAP_ANON | MAP_PRIVATE that aren't MAP_STACK, which corresponds typically to heap allocations. If the limit is exceeded, mmap() fails with errno set to ENOMEM.
RLIMIT_FREEMEM Unix The limit on total memory usage, in tenths of a per cent of the total system memory. For example, a limit of 500 on a system with 1000 MB of memory would be 500 MB. This limit is shared with all other processes; a memory allocation by this process fails if it would cause the total system memory usage of all processes to exceed this process's limit.

The intention is to allow the memory pool to be crudely partitioned. For example, important system processes could be given an RLIMIT_FREEMEM value of RLIM_INFINITY, and all others a value of 800. That would partition memory into an 80% chunk that's shared by everybody and a 20% chunk that's shared by important system processes.

RLIMIT_NOFILE POSIX One more than the maximum value that the system may assign to a newly created descriptor. This limit constrains the number of file descriptors that a process may create.  
RLIMIT_NPROC Unix The maximum number of processes. Attempts to create new processes fail.
RLIMIT_NTHR Unix The maximum number of threads. Attempts to create threads (e.g., by calling pthread_create()) fail.
RLIMIT_OFILE Unix Same as RLIMIT_NOFILE.  
RLIMIT_RSS Unix The maximum resident set size for a process; the same as RLIMIT_AS. Same as RLIMIT_AS.
RLIMIT_STACK POSIX The maximum size, in bytes, that a process's stack may be. The system will not automatically grow the stack beyond this limit.

Within a process, setrlimit() increases the limit on the size of your stack, but doesn't 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 isn't 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 process is holding or ignoring SIGSEGV, or is catching SIGSEGV and hasn't made arrangements to use an alternate stack, the disposition of SIGSEGV is set to SIG_DFL before it's sent.
RLIMIT_VMEM Unix Same as RLIMIT_AS. Same as RLIMIT_AS.

Because limit information is stored in the per-process information, the shell builtin ulimit command (see the entry for ksh in the Utilities Reference) must directly execute this system call if it's to affect all future processes created by the shell.

The values of the current limit of the following resources affect these parameters:

Resource Parameter
RLIMIT_NOFILE OPEN_MAX

When you're using the setrlimit() function, if the requested new limit is RLIM_INFINITY, there's no new limit; otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit is the corresponding saved hard limit; otherwise, if the requested new limit is RLIM_SAVED_CUR, the new limit is the corresponding saved soft limit; otherwise, the new limit is the requested value. In addition, if the corresponding saved limit can be represented correctly in an object of type rlim_t, then it's overwritten with the new limit.

The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is undefined 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 permitted.

The exec* family of functions also cause resource limits to be saved.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EFAULT
The rlp argument points to an illegal address.
EINVAL
An invalid resource was specified, the new rlim_cur exceeds the new rlim_max, or the limit specified can't be lowered because current usage is already higher than the limit.
EPERM
The limit specified to setrlimit() would have raised the maximum limit value, and the calling process doesn't have the required permission; see procmgr_ability().

Classification:

setrlimit() is POSIX 1003.1; setrlimit64() is Large-file support

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes