CreateFileMapping Function (Memory Management)

CreateFileMapping Function

The CreateFileMapping function creates or opens a named or unnamed file mapping object.

Return value
If the function succeeds, the return value is a handle to the file mapping object. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Syntax


HANDLE CreateFileMapping(
  HANDLE hFile,
  LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  DWORD  flProtect,
  DWORD  dwMaximumSizeHigh,
  DWORD  dwMaximumSizeLow,
  LPCTSTR lpName
);

Parameters

Parameter	Description
`hFile`	A handle to the file that will be used to initialize the mapping. If this handle is valid, it must have been created with `GENERIC_READ` access. If this handle is `INVALID_HANDLE_VALUE`, the file mapping is not initialized from a file. If this handle is `NULL`, the file mapping is backed by the system paging file.
`lpFileMappingAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that specifies whether the returned handle can be inherited by child processes. If this parameter is NULL, the handle cannot be inherited.
`flProtect`	The memory protection for the file mapping object. This parameter can be one of the following values: `PAGE_READONLY` `PAGE_READWRITE` `PAGE_WRITECOPY` `PAGE_EXECUTE` `PAGE_EXECUTE_READ` `PAGE_EXECUTE_READWRITE` `PAGE_EXECUTE_WRITECOPY` `PAGE_NOACCESS` For more details, see Memory Protection Constants.
`dwMaximumSizeHigh`	The 32 most significant bits of the maximum size of the file mapping object, in bytes. This parameter can be NULL if `dwMaximumSizeLow` is 0.
`dwMaximumSizeLow`	The 32 least significant bits of the maximum size of the file mapping object, in bytes. This parameter can be NULL if `dwMaximumSizeHigh` is 0.
`lpName`	The name of the file mapping object. If this parameter is NULL, the file mapping object has no name.

Remarks

A file mapping object provides a way to create a potentially large file that is backed by the system paging file, instead of a physical file on disk.

To commit pages to the file mapping object, use the MapViewOfFile function.

Note: When creating a file mapping object backed by the system paging file (i.e., hFile is NULL), the size of the mapping must be specified.

Tip: For sharing memory between processes, ensure that the lpName parameter is consistent across all processes that need to access the mapping.

Examples

Here's a simple example of how to create a file mapping object for a file:


#include <windows.h>
#include <iostream>

int main() {
    HANDLE hFile = CreateFile(
        L"my_shared_file.txt",
        GENERIC_READ | GENERIC_WRITE,
        0,
        NULL,
        CREATE_ALWAYS,
        FILE_ATTRIBUTE_NORMAL,
        NULL
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        std::cerr << "Failed to create or open file. Error: " << GetLastError() << std::endl;
        return 1;
    }

    HANDLE hMapFile = CreateFileMapping(
        hFile,
        NULL,          // Default security attributes
        PAGE_READWRITE, // Read/write permission
        0,             // Maximum size high order DWORD
        1024,          // Maximum size low order DWORD (1 KB)
        L"MyFileMappingObject" // Name of the mapping object
    );

    if (hMapFile == NULL) {
        std::cerr << "Could not create file mapping object. Error: " << GetLastError() << std::endl;
        CloseHandle(hFile);
        return 1;
    }

    std::cout << "File mapping created successfully." << std::endl;

    // You would typically call MapViewOfFile here to access the memory.

    CloseHandle(hMapFile);
    CloseHandle(hFile);

    return 0;
}

Microsoft Learn