msync (BPX1MSY, BPX4MSY) — Synchronize memory with physical storage

Function

The msync callable service writes all modified pages over the requested range to their permanent storage locations on disk. It also deletes any in-memory cached pages over the requested range, resetting the contents of those pages to that which resides on disk.

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 (BPX1MSY):	31-bit
AMODE (BPX4MSY):	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 BPX1MSY,(Map_address,
              Map_length,
              Sync_Options,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MSY 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 the mapping from which the modified pages are to be written to their permanent storage locations on disk, or invalidated. 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 all updated pages written out to disk, or invalidated. The length can be the size of the whole mapping, or a part of it. If the specified length is not a multiple of the page size, it is rounded up to a page boundary.

Sync_Options

Supplied parameter

Type:: Integer
Length:: Fullword

The name of the fullword that contains the option flags for the service. The specified value can be a combination (for example, using an exclusive OR) of one or more of the following flags, with the limitation that MS_ASYNC and MS_SYNC are mutually exclusive. These constants are defined in the BPXYCONS macro.

Constant	Description
MS_ASYNC	Performs asynchronous writes. MS_ASYNC returns immediately when all write operations are scheduled. If the requestor's intent is to write consistent data to the disk, do not use this option.
MS_SYNC	Performs synchronous writes. MS_SYNC will return after all write operations are completed.
MS_INVALIDATE	Invalidates the cached memory—mapped pages. After the cached copy of the data in memory has been invalidated for a MAP_SHARED mapping, any further references to these pages will be obtained by the system from their permanent storage locations on disk. For a MAP_PRIVATE mapping, only updated (private) pages are invalidated. Any further references to these pages will be obtained from the shared cache.

Notes:

If MS_INVALIDATE is the only flag specified, the requested cached memory—mapped pages are invalidated without any modified pages first being written to disk.
If MS_INVALIDATE is specified with either MS_SYNC or MS_ASYNC, all the modified pages in the requested address range are written to disk before the cached copy of data in memory is invalidated.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

Upon successful completion, the msync service writes all modified pages over the range (map_address, map_address+map_length) to their permanent storage locations on disk, invalidates the cached mmap pages, or does both.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the msync service stores the return code. The msync 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 msync 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 a multiple of the page size. (JRNotPage) The value in the Sync_Options parameter is incorrect. (JROPtNotSupp) The input address or length is negative. (JRNegativeValueInvalid) 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, 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).
EIO	An I/O error occurred while writing to the file system (file system JR). This return code is set only if MS_SYNC is set in the Sync_Options parameter. I/O errors during asynchronous write operations are not reported to the application.
ENOMEM	One of the following conditions occurred: Some or all of the 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 msync service stores the reason code. The msync 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

The msync service is used by programs that require a file to be in a known state (such as in building transaction-oriented programs).
When a request is made to write the cached pages by a process that has mapped the area with the MAP_SHARED option, updates made by all processes sharing the specified file-offset range are written, not just the updates made by the msync requesting process. The same is true for invalidate requests.
Only full pages are processed. If the map_length parameter contains a value that is not a multiple of the page size, the length will be rounded up to a full page.
In relation to advisory locking mechanisms, there is no difference between sharing a file using the mmap services, and sharing a file using the read/write services. Specifically, before a series of bytes are accessed using either method, a byte range lock is required to ensure the consistency of the data being accessed. It logically follows that if the intent is to write consistent data to the disk when a file is shared using memory map services, an advisory lock should be held on the pages being acted upon, before calling the msync service (with the MS_SYNC option).
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 that is 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 is taken against the unmapped areas.
To successfully write or invalidate MAP_SHARED mappings, the range that is specified must have the PROT_WRITE access level. If any portion of the specified range has either the PROT_NONE or PROT_READ access levels at the time of the msync request, that portion will not be written or invalidated, and no error condition will be raised.
Because memory map is implemented using a cached copy of the original data that resides on disk, concurrent updates made using the write callable service to a file that is being memory mapped will produce undefined results. If this type of activity is desired, explicit serialization must be implemented between a process invoking the msync service with the invalidate option, and another process invoking the write service (page-multiple advisory lock).
When the msync service is called for MAP_PRIVATE mappings, any data that is modified by that process is not written to the file, and such data is not visible to other processes. The only supported action is to invalidate the pages that were cached exclusively for the use of the requesting process (this has no impact on the MAP_SHARED cache). For the invalidate request to be successful, the range that is specified must have the PROT_WRITE access level. If another process mapping the same file-offset range with the MAP_SHARED option invalidates the shared cache, then, from the perspective of the MAP_PRIVATE process, only the pages that were not updated by the MAP_PRIVATE process (still shared) are invalidated. The modified (and now private) pages remain intact in the cache. This type of activity could cause inconsistencies within the MAP_PRIVATE mapping.

Examples

For an example using this callable service, see BPX1MSY (msync) example.