setrlimit (BPX1SRL, BPX4SRL) — Set resource limits

Function

The setrlimit callable service sets resource limits for the calling process. A resource limit is a pair of values; one specifies the current (soft) limit and the other the maximum (hard) limit.

Requirements

Parameters

Resource

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a value that indicates the resource for which to set the hard and soft limits. This parameter can specify one of the resources in the following table:

Table 1. Resources that can be limited by setrlimit

Resource	Description	Action when soft limit is exceeded
RLIMIT_MEMLIMIT	Maximum amount of usable storage above the bar (in 1-MB segments) that can be allocated at one time.	Any attempt to allocate or extend the usable amount of virtual storage above the 2-MB addressing range fails.
RLIMIT_CORE	Maximum core file size (in bytes) created by a process. A value of 0 prevents core file creation.	Core file writing terminates at this size.
RLIMIT_CPU	Maximum amount of CPU time (in seconds) used by a process.	SIGXCPU is sent to the process, and the process is granted a small extension to allow for signal generation and delivery. If the extension is used up, the process is terminated with a SIGKILL.
RLIMIT_FSIZE	Maximum file size (in bytes) created by a process. A value of 0 prevents the creation of new files and the expansion of existing files.	SIGXFSZ is sent to the process. If the process is blocking, catching, or ignoring SIGXFSZ, continued attempts to increase the size of a file beyond the limit fail with a return code of EFBIG.
RLIMIT_NOFILE	Maximum number of open file descriptors for a process. This number is one greater than the maximum value that may be assigned to a newly-created descriptor.	Functions that create new file descriptors after the limit is reached fail with a return code of EMFILE.
RLIMIT_AS	Maximum address space size (in bytes) for a process.	The mmap and shmat callable services fail with a return code of ENOMEM. User getmain and storage obtain requests fail (for example, runtime library stack and heap expansion fails).

The RLIMIT_ constants are defined in the BPXYCONS macro. See BPXYCONS — Constants used by services.

Rlimit

Supplied parameter

Type:

Structure

Length:

The length of the rlimit structure

The name of an Rlimit structure that contains the values for the hard (maximum) and soft (current) limits for the resource that is identified by the resource parameter. Macro BPXYRLIM defines the Rlimit structure. (See BPXYRLIM — Map the rlimit, rusage, and timeval structures.) Each limit value contains two fullwords. For all resources except RLIMIT_FSIZE, the upper fullword for each limit value is ignored.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setrlimit service returns a value of zero if it is successful, and -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setrlimit service stores the return code. The setrlimit service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The setrlimit service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	The operation is not permitted for one of the following reasons: The resource that was specified is not valid. The soft limit that is to be set exceeds the hard limit to set. The soft limit that is to be set is below the current usage. The hard limit that is to be set exceeds a system–defined limit. One of the file size limits that was specified is a negative value. The following reason codes can accompany the return code: JrInvalidResource, JrSoftExceedsHard, JrSoftBelowUsage, JrFdOpenAboveLimit, JrOpenFileLimitMax, or JrNegFileSizeLimit.
EMVSSAF2ERR	A Security product internal error has occurred. Consult the Reason_code parameter for the exact reason for the error.
EPERM	An attempt was made to raise a hard (maximum) limit, but the calling process did not have superuser authority. The following reason code can accompany the return code: JrRaiseHardLimit.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setrlimit service stores the reason code. The setrlimit service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The soft limit can be modified to any value that is less than or equal to the hard limit. For the RLIMIT_CPU, RLIMIT_NOFILE, and RLIMIT_AS resources, if setrlimit is called with a soft limit that is lower than the current usage, setrlimit fails with an EINVAL return code.

   An exception to this rule occurs when the process is running in an address space that contains multiple processes. When you change the RLIMIT_CPU, you can set a new soft limit that is greater than the time limit of the current process, yet greater than the time consumed by the address space. This allows the setrlimit call to succeed, and a SIGXCPU signal is generated. The alternative is not to run multiple processes in the same address space.

2. The hard limit may be lowered to any value that is greater than or equal to the soft limit.
3. The hard limit can only be raised by a process that has superuser authority.
4. Both the soft limit and the hard limit can be changed with a single call to the setrlimit service.
5. If the setrlimit service is called with a soft limit that is greater than the hard limit, setrlimit returns an EINVAL return code.
6. The resource limit values are propagated across the exec, fork, and spawn services. An exception exists for the exec and spawn services. If a daemon process invokes the exec service and it has previously invoked setuid, or invokes the spawn service specifying that a user ID change is to occur, then the limit values are set based on the values found in the OMVS segment of the target user ID. If the target user's OMVS segment does not specify limit values, then the limit values are set based on the values found in the BPXPRMxx parmlib member.
7. For processes in a multiprocess address space, the RLIMIT_CPU and RLIMIT_AS limits are shared with all the processes within the address space. For RLIMIT_CPU, when the soft limit is exceeded, action is taken on the first process within the address space. If the action is termination, all the processes within the address space are terminated.
8. In addition to the RLIMIT_CORE limit values, CORE dump defaults are set by SYSMDUMP defaults. See z/OS MVS Initialization and Tuning Reference for information on setting up SYSMDUMP defaults via the IEADMR00 parmlib member.
9. Core dumps are taken in 4160-byte increments. Therefore, RLIMIT_CORE values affect the size of core dumps in 4160-byte increments. For example, if the RLIMIT_CORE soft limit value is 0, no core dumps are taken. If the RLIMIT_CORE soft limit value is 8000, the maximum size of a core dump is 8000 * 4160 bytes.
10. Limits may have an infinite value of RLIM_INFINITY. MEMLIMIT cannot exceed 16383G, which is defined RLIM_MEGINFINITY.
11. The hard limit for RLIMIT_NOFILE cannot exceed the system-defined limit of 524287. A value of RLIM_INFINITY for RLIMIT_NOFILE indicates that the current system maximum value should be set.
12. The soft limit for RLIMIT_NOFILE must be set higher than the value of the highest open file descriptor. Attempting to lower the soft limit to a value that is less than or equal to the highest open file descriptor results in an EINVAL return code.
13. Setting a limit of 0 for RLIMIT_FSIZE prevents the creation of new files and the expansion of existing files.
14. When RLIM_INFINITY (X'7FFFFFFF') is passed on a setrlimit request, no limit is enforced by setrlimit. As a result, the maximum allowable limit is set, regardless of the resource. The new service RLIM_MEMLIMIT treats RLIM_INFINITY as a request for 21474836471 1- megabyte pages.
15. When the MEMLIMIT is set by z/OS UNIX, the highest value that is supported is 16383 petabytes, or X'FFFC00000000000000'.
16. Processes can use this service to control CPU resource consumption. For more information, see z/OS MVS Initialization and Tuning Reference.

Related services

• getrlimit (BPX1GRL, BPX4GRL) — Get resource limits
• getrusage (BPX1GRU, BPX4GRU) — Get resource usage

Characteristics and restrictions

None.