HANDLE CreateFileMapping(
HANDLE hFile,
LPSECURITY_ATTRIBUTES lpAttributes,
DWORD flProtect,
DWORD dwMaximumSizeHigh,
DWORD dwMaximumSizeLow,
LPCTSTR lpName
);
Creates or opens a named or unnamed file mapping object.
| Parameter | Description |
|---|---|
hFile |
A handle to the file to be used for the mapping. The file must be created with the GENERIC_READ and GENERIC_WRITE access flags.
If this handle is INVALID_HANDLE_VALUE, the function creates a paging file-backed file mapping object.
|
lpAttributes |
A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the file mapping object.
If NULL, the object is created without a default security descriptor.
|
flProtect |
The type of protection for the memory protection of the file mapping object. This parameter can be one of the following values:
PAGE_READWRITE with SEC_COMMIT to commit the memory region at creation.
|
dwMaximumSizeHigh |
The high-order 32 bits of the maximum size of the file mapping object.
If dwMaximumSizeLow is zero and this parameter is zero, the size of the mapping is the size of the file specified by hFile.
|
dwMaximumSizeLow |
The low-order 32 bits of the maximum size of the file mapping object.
If dwMaximumSizeHigh and dwMaximumSizeLow are both zero, the size of the mapping is the current size of the file specified by hFile.
|
lpName |
The name of the file mapping object. This name is used by other processes to open the file mapping object.
If NULL, the file mapping object is created without a name.
|
| Value | Description |
|---|---|
| A handle to the newly created file mapping object. | If the function succeeds. |
NULL
|
If the function fails. To get extended error information, call GetLastError.
|
CreateFileMapping creates a file mapping object that can be shared between processes. This is a common mechanism for inter-process communication (IPC).
If hFile is INVALID_HANDLE_VALUE, the function creates a paging file-backed file mapping object. This is useful for creating shared memory regions that do not correspond to a physical file.
The size of the file mapping object is specified by dwMaximumSizeHigh and dwMaximumSizeLow. If both are zero, the size is determined by the size of the file.
The lpAttributes parameter allows you to control the security permissions of the file mapping object, determining which processes can access it.
The flProtect parameter specifies the desired memory protection. It must be compatible with the protection of the underlying file.
The following example demonstrates how to create a read-write file mapping object backed by a paging file.
#include <windows.h>
#include <stdio.h>
int main() {
HANDLE hMapFile;
LPVOID pBuf;
TCHAR szMsg[] = TEXT("Hello, shared memory!");
SIZE_T cbMsg = (lstrlen(szMsg) + 1) * sizeof(TCHAR);
// Create a file mapping object backed by the paging file.
// Size is set to the size of the message.
hMapFile = CreateFileMapping(
INVALID_HANDLE_VALUE, // Use paging file
NULL, // Default security attributes
PAGE_READWRITE, // Read/write protection
0, // High-order DWORD of size
cbMsg, // Low-order DWORD of size
TEXT("MySharedMemory")); // Name of the mapping object
if (hMapFile == NULL) {
printf("Could not create file mapping object (%lu).\n", GetLastError());
return 1;
}
// Map the file mapping object into the address space of the calling process.
pBuf = MapViewOfFile(
hMapFile,
FILE_MAP_ALL_ACCESS, // Read/write access
0, // High-order DWORD of offset
0, // Low-order DWORD of offset
cbMsg); // Number of bytes to map
if (pBuf == NULL) {
printf("Could not map view of file (%lu).\n", GetLastError());
CloseHandle(hMapFile); // Clean up the file mapping object
return 1;
}
// Write the message to the shared memory.
CopyMemory(pBuf, szMsg, cbMsg);
printf("Message written to shared memory: %s\n", (TCHAR*)pBuf);
// Unmap the view of the file.
UnmapViewOfFile(pBuf);
// Close the file mapping object handle.
CloseHandle(hMapFile);
printf("Shared memory operations completed.\n");
return 0;
}