MapViewOfFile3 function (memoryapi.h)
Maps a view of a file or a pagefile-backed section into the address space of the specified process.
Syntax
PVOID MapViewOfFile3(
[in] HANDLE FileMapping,
[in] HANDLE Process,
[in, optional] PVOID BaseAddress,
[in] ULONG64 Offset,
[in] SIZE_T ViewSize,
[in] ULONG AllocationType,
[in] ULONG PageProtection,
[in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
[in] ULONG ParameterCount
);
Parameters
[in] FileMapping
A HANDLE to a section that is to be mapped into the address space of the specified process.
[in] Process
A HANDLE to a process into which the section will be mapped.
[in, optional] BaseAddress
The desired base address of the view (the address is rounded down to the nearest 64k boundary).
If this parameter is NULL, the system picks the base address.
If BaseAddress is not NULL, then any provided MEM_ADDRESS_REQUIREMENTS must consist of all zeroes.
[in] Offset
The offset from the beginning of the section.
The offset must be 64k aligned.
[in] ViewSize
The number of bytes to map. A value of zero (0) specifies that the entire section is to be mapped.
The size must always be a multiple of the page size.
[in] AllocationType
The type of memory allocation. This parameter can be zero (0) or one of the following values.
Value | Meaning |
---|---|
|
Maps a reserved view. |
|
Replaces a placeholder with a mapped view. Only data/pf-backed section views are supported (no images, physical memory, etc.). When you replace a placeholder, BaseAddress and ViewSize must exactly match those of the placeholder,
and any provided MEM_ADDRESS_REQUIREMENTS structure must consist of all zeroes.
After you replace a placeholder with a mapped view, to free that mapped view back to a placeholder, see the UnmapFlags parameter of UnmapViewOfFileEx and UnmapViewOfFile2. A placeholder is a type of reserved memory region. The 64k alignment requirements on Offset and BaseAddress do not apply when this flag is specified. |
|
Maps a large page view. This flag specifies that the view should be mapped using large page support. The size of the view must be a multiple of the size of a large page reported by the GetLargePageMinimum function, and the file-mapping object must have been created using the SEC_LARGE_PAGES option. If you provide a non-null value for the BaseAddress parameter, then the value must be a multiple of GetLargePageMinimum. |
[in] PageProtection
The desired page protection.
For file-mapping objects created with the SEC_IMAGE attribute, the PageProtection parameter has no effect, and should be set to any valid value such as PAGE_READONLY.
[in, out, optional] ExtendedParameters
An optional pointer to one or more extended parameters of type MEM_EXTENDED_PARAMETER. Each of those extended parameter values can itself have a Type field of either MemExtendedParameterAddressRequirements or MemExtendedParameterNumaNode. If no MemExtendedParameterNumaNode extended parameter is provided, then the behavior is the same as for the VirtualAlloc/MapViewOfFile functions (that is, the preferred NUMA node for the physical pages is determined based on the ideal processor of the thread that first accesses the memory).
[in] ParameterCount
The number of extended parameters pointed to by ExtendedParameters.
Return value
Returns the base address of the mapped view, if successful. Otherwise, returns NULL and extended error status is available using GetLastError.
Remarks
This API helps support high-performance games, and server applications, which have particular requirements around managing their virtual address space. For example, mapping memory on top of a previously reserved region; this is useful for implementing an automatically wrapping ring buffer. And allocating memory with specific alignment; for example, to enable your application to commit large/huge page-mapped regions on demand.
Using this function for new allocations, you can:
- specify a range of virtual address space and a power-of-2 alignment restriction
- specify an arbitrary number of extended parameters
- specify a preferred NUMA node for the physical memory as an extended parameter
- specify a placeholder operation (specifically, replacement).
To specify the NUMA node, see the ExtendedParameters parameter.
Examples
For a code example, see Scenario 1 in VirtualAlloc2.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 10, version 1803 [desktop apps only] |
Minimum supported server | Windows Server 2016 [desktop apps only] |
Target Platform | Windows |
Header | memoryapi.h (include Windows.h) |
Library | onecore.lib |
DLL | Kernel32.dll |