munmap (BPX1MUN, BPX4MUN)— Unmap previously mapped addresses

Function

The munmap callable service removes the mapping for pages in the requested range. It should be used only to unmap regions that have been previously mapped by the application with the mmap callable service.

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 (BPX1MUN): 31-bit
AMODE (BPX4MUN): 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

CALL BPX1MUN,(Map_address,
              Map_length,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MUN 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 address of an existing mapping that is to be unmapped. The specified address does not have to be the start of a mapping. The value of map_address must be a multiple of the page size. If the address falls within a MAP_MEGA map, the address that is provided is rounded down to a megabyte multiple so that an entire segment is included in the unmap operation. It is not possible to unmap part of a segment when processing a MAP_MEGA map.

Map_length
Supplied parameter
Type:
Integer
Length:
Fullword (doubleword)

The name of the fullword (doubleword) containing the size (in bytes) of the mappings that are to be unmapped. 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 will be rounded up to a page boundary. If map_address plus map_length falls within a MAP_MEGA map, the length is rounded up so that it includes an entire segment (but not necessarily the entire MAP_MEGA mapping).

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

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

Upon successful completion, the munmap service unmaps all pages in the range (map_address, map_address+map_length).

Return_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the munmap service stores the return code. The munmap 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 munmap service can return one of the following values in the Return_code parameter:
Return_code Explanation
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 multiples of the page size. (JRNotPage)
  • Some or all of the addresses in the range (map_address, map_address + map_length) are not valid for the address space. (JRAddressNotAvailable)
  • The input address is negative, or the input length is zero or negative. (JRZeroOrNegative)
  • The caller's PSW key does not match the key of the memory mapped storage segment that is being unmapped. (JrKeyMismatch)
  • In 64-bit mode, an address greater than 31 bit addr was passed in map_address (JrAddressNotAvailable).
  • In 64-bit mode, a length greater than X'7FFFFFFFF' was passed in map_length (JrInvParmLength).
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the munmap service stores the reason code. The munmap 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. An address of 0 with a length of X'7FFFF000' unmaps all the storage that is associated with this process.
  2. For both private and shared mappings, if the munmap service unmaps a subset of the range of the original mmap request, further references to those pages result in a program check exception. When the entire range of the original mmap request has been unmapped, the memory allocated by the mmap service is freed.
  3. If there are no mappings in the requested address range, the munmap service has no effect. The service returns successfully.
  4. The range that is specified (map_address, map_address + map_length) may contain areas that have been unmapped, in which case no action is taken against the unmapped areas.
  5. If a mapping to be removed is private, any modifications that are made in the specified address range are discarded.
  6. If a mapping to be removed is shared, all modifications that are made in the specified address range since the last msync (if any) are written to disk. If this is not desired, the msync service must be called to invalidate the updates that have been made to the mapped region before the range is unmapped.
  7. If a memory-mapped region is not unmapped before the process terminates, process termination does not automatically write out to disk any modified data in the mapped region. Modified private data in a MAP_PRIVATE region is discarded. If the mapped region is MAP_SHARED, the modified data continues to reside in the cache (if the same file-offset range is being shared), and may ultimately be written out to disk by another process via the msync service. However, if no other processes map the same file-offset range as MAP_SHARED, the modified data is discarded.
  8. Only entire pages are unmapped. 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. For MAP_MEGA maps, only entire segments are unmapped. The map_address and map_length are adjusted to ensure that entire segments are unmapped.
  9. An unmap request may span MAP_MEGA and non-MAP_MEGA ranges.

Related services

Characteristics and restrictions

There are no restrictions on the use of the munmap service.

Examples

For an example using this callable service, see BPX1MUN (munmap) example.

Parent topic: Callable services descriptions