mprotect (BPX1MPR, BPX4MPR) — Set protection of memory mapping

Function

The mprotect callable service changes the access protection of a memory mapping for the caller's address space.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, PSW Key 2 or PSW Key 8
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1MPR):	31-bit
AMODE (BPX4MPR):	64-bit
ASC mode:	Primary address space control (ASC) mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

The syntax format is as follows:

CALL BPX1MPR,(Map_address,
              Map_length,
              Protect_options,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MPR with the same parameters. The Map_address and Map_length parameters are doublewords.

Parameters

Map_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains the starting address in the address space at which the access protection of the mapping is to be changed. The value of Map_address must be a multiple of the page size.

Map_length

Supplied parameter

Type:: Integer
Length:: Fullword (doubleword)

The name of the fullword (doubleword) that contains the size (in bytes) of the mapping that is to have its access protection modified. The length can be the size of the whole mapping, or a part of it. If the specified length is not in multiples of the page size, it is rounded up to a page boundary.

Protect_options

Supplied parameter

Type:: Integer
Length:: Fullword

The name of the fullword that contains the new value of the access protection flags for the specified mapping. The access protection flags can be changed to either PROT_NONE or a combination (for example, by using an inclusive OR) of one or more of the other flags (such as PROT_READ, PROT_WRITE, or PROT_EXEC). These flags are defined in the BPXYCONS macro. (See BPXYCONS — Constants used by services.)

Constant	Description
PROT_READ	Mapped data can be read.
PROT_WRITE	Mapped data can be written and read.
PROT_EXEC	Mapped data can be executed. PROT_EXEC is treated in the same way as PROT_READ.
PROT_NONE	Mapped data cannot be accessed.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the mprotect service returns the value of 0 if the request is successful, or -1 if it is not successful.

Upon successful completion, the mprotect service has changed the access protections on the mapping specified by the range (map_address, map_address + map_length) to those specified by the protect_options parameter.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the mprotect service stores the return code. The mprotect service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values.

The mprotect service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The access protection value is incorrect; it violates the access permission of the process to the underlying file. The following condition occurred: The original file is not open for write, and PROT_WRITE is specified for a MAP_SHARED type mapping.
EAGAIN	The caller is not running in either PSW Key 2 or PSW Key 8. (JRUnsupportedKey)
EINVAL	One of the following conditions occurred: The value of map_address is not a multiple of the page size. (JRNotPage) The input address or length is negative. (JRNegativeValueInvalid) The protection options specified are not valid. (JROptNotSupp) The caller's PSW key does not match the key of the memory mapped storage segment that is being operated against. (JrKeyMismatch) In 64-bit mode, the value of map_address specified was greater than X'7FFFFFFFF' (JrAddressNotAvailable). In 64-bit mode, the value of map+length was greater than X'7FFFFFFFF' (Jr_InvParmLength).
ENOMEM	One of the following conditions occurred: Addresses in the range (map_address, map_address + map_length) are not valid for the address space. (JRAddressNotAvailable) One or more specified pages are not mapped. (JRNotMapped)

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the mprotect service stores the reason code. The mprotect 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

Access protection only acts on full pages. If the map_length parameter contains a value that is not a multiple of the page size, the length is rounded up to a full page.
The protection level that is established by the mprotect service is address-space wide in scope, not just process specific. The scope is system-wide when the protection is changed for a MAP_MEGA map. All active maps to the same file-offset range are affected by the request.
Constants used for this callable service are defined in the BPXYCONS macro. See BPXYCONS — Constants used by services.

Related services

Characteristics and restrictions

The range specified (map_address, map_address + map_length) must not contain any areas that are not currently memory mapped. It may, however, contain areas that have been unmapped, in which case no action will be taken against the unmapped areas.

Examples

For an example using this callable service, see BPX1MPR (mprotect) example.