MapViewOfFile function (memoryapi.h)
Maps a view of a file mapping into the address space of a calling process.
To specify a suggested base address for the view, use the MapViewOfFileEx function. However, this practice is not recommended.
Syntax
LPVOID MapViewOfFile(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap
);
Parameters
[in] hFileMappingObject
A handle to a file mapping object. The CreateFileMapping and OpenFileMapping functions return this handle.
[in] dwDesiredAccess
The type of access to a file mapping object, which determines the page protection of the pages. This parameter can be one of the following values, or a bitwise OR combination of multiple values where appropriate.
Using bitwise OR, you can combine the values above with these values.
| Value | Meaning |
|---|---|
|
A copy-on-write view of the file is mapped. The file mapping object must have been created with
PAGE_READONLY, PAGE_READ_EXECUTE,
PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY,
PAGE_READWRITE, or PAGE_EXECUTE_READWRITE protection.
When a process writes to a copy-on-write page, the system copies the original page to a new page that is private to the process. The new page is backed by the paging file. The protection of the new page changes from copy-on-write to read/write. When copy-on-write access is specified, the system and process commit charge taken is for the entire view because the calling process can potentially write to every page in the view, making all pages private. The contents of the new page are never written back to the original file and are lost when the view is unmapped. |
|
An executable view of the file is mapped (mapped memory can be run as code). The file mapping object must
have been created with PAGE_EXECUTE_READ,
PAGE_EXECUTE_WRITECOPY, or PAGE_EXECUTE_READWRITE
protection.
Windows Server 2003 and Windows XP: This value is available starting with Windows XP with SP2 and Windows Server 2003 with SP1. |
|
Starting with Windows 10, version 1703, 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 lpBaseAddress, then the value must be a multiple of GetLargePageMinimum. Note: On OS versions before Windows 10, version 1703, the FILE_MAP_LARGE_PAGES flag has no effect. On these releases, the view is automatically mapped using large pages if the section was created with the SEC_LARGE_PAGES flag set. |
|
Sets all the locations in the mapped file as invalid targets for Control Flow Guard (CFG). This flag is similar to PAGE_TARGETS_INVALID. Use this flag in combination with the execute access right FILE_MAP_EXECUTE. Any indirect call to locations in those pages will fail CFG checks, and the process will be terminated. The default behavior for executable pages allocated is to be marked valid call targets for CFG. |
For file mapping objects created with the SEC_IMAGE attribute, the dwDesiredAccess parameter has no effect, and should be set to any valid value such as FILE_MAP_READ.
For more information about access to file mapping objects, see File Mapping Security and Access Rights.
[in] dwFileOffsetHigh
A high-order DWORD of the file offset where the view begins.
[in] dwFileOffsetLow
A low-order DWORD of the file offset where the view is to begin. The combination of the high and low offsets must specify an offset within the file mapping. They must also match the memory allocation granularity of the system. That is, the offset must be a multiple of the allocation granularity. To obtain the memory allocation granularity of the system, use the GetSystemInfo function, which fills in the members of a SYSTEM_INFO structure.
[in] dwNumberOfBytesToMap
The number of bytes of a file mapping to map to the view. All bytes must be within the maximum size specified by CreateFileMapping. If this parameter is 0 (zero), the mapping extends from the specified offset to the end of the file mapping.
Return value
If the function succeeds, the return value is the starting address of the mapped view.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
Mapping a file makes the specified portion of a file visible in the address space of the calling process.
For files that are larger than the address space, you can only map a small portion of the file data at one time. When the first view is complete, you can unmap it and map a new view.
To obtain the size of a view, use the VirtualQuery function.
Multiple views of a file (or a file mapping object and its mapped file) are coherent if they contain identical data at a specified time. This occurs if the file views are derived from any file mapping object that is backed by the same file. A process can duplicate a file mapping object handle into another process by using the DuplicateHandle function, or another process can open a file mapping object by name by using the OpenFileMapping function.
With one important exception, file views derived from any file mapping object that is backed by the same file are coherent or identical at a specific time. Coherency is guaranteed for views within a process and for views that are mapped by different processes.
The exception is related to remote files. Although MapViewOfFile works with remote files, it does not keep them coherent. For example, if two computers both map a file as writable, and both change the same page, each computer only sees its own writes to the page. When the data gets updated on the disk, it is not merged.
A mapped view of a file is not guaranteed to be coherent with a file that is being accessed by the ReadFile or WriteFile function.
Do not store pointers in the memory mapped file; store offsets from the base of the file mapping so that the mapping can be used at any address.
To guard against EXCEPTION_IN_PAGE_ERROR exceptions, use structured exception handling to protect any code that writes to or reads from a memory mapped view of a file other than the page file. For more information, see Reading and Writing From a File View.
When modifying a file through a mapped view, the last modification timestamp may not be updated automatically. If required, the caller should use SetFileTime to set the timestamp.
If a file mapping object is backed by the paging file (CreateFileMapping is called with the hFile parameter set to INVALID_HANDLE_VALUE), the paging file must be large enough to hold the entire mapping. If it is not, MapViewOfFile fails. The initial contents of the pages in a file mapping object backed by the paging file are 0 (zero).
When a file mapping object that is backed by the paging file is created, the caller can specify whether MapViewOfFile should reserve and commit pages at the same time (SEC_COMMIT) or simply reserve pages (SEC_RESERVE). Mapping the file makes the entire mapped virtual address range unavailable to other allocations in the process. After a page from the reserved range is committed, it cannot be freed or decommitted by calling VirtualFree. Reserved and committed pages are released when the view is unmapped and the file mapping object is closed. For details, see the UnmapViewOfFile and CloseHandle functions.
To have a file with executable permissions, an application must call CreateFileMapping with either PAGE_EXECUTE_READWRITE or PAGE_EXECUTE_READ, and then call MapViewOfFile with FILE_MAP_EXECUTE | FILE_MAP_WRITE or FILE_MAP_EXECUTE | FILE_MAP_READ.
In Windows Server 2012, this function is supported by the following technologies.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | Yes |
| SMB 3.0 Transparent Failover (TFO) | Yes |
| SMB 3.0 with Scale-out File Shares (SO) | Yes |
| Cluster Shared Volume File System (CsvFS) | Yes |
| Resilient File System (ReFS) | Yes |
When CsvFs is paused this call might fail with an error indicating that there is a lock conflict.
Examples
For an example, see Creating Named Shared Memory.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | memoryapi.h (include Windows.h, Memoryapi.h) |
| Library | onecore.lib |
| DLL | Kernel32.dll |