CreateFileMapping2 function (memoryapi.h)

Creates or opens a named or unnamed file mapping object for a specified file. You can specify a preferred NUMA node for the physical memory as an extended parameter; see the ExtendedParameters parameter.

Syntax

HANDLE CreateFileMapping2(
  HANDLE                 File,
  SECURITY_ATTRIBUTES    *SecurityAttributes,
  ULONG                  DesiredAccess,
  ULONG                  PageProtection,
  ULONG                  AllocationAttributes,
  ULONG64                MaximumSize,
  PCWSTR                 Name,
  MEM_EXTENDED_PARAMETER *ExtendedParameters,
  ULONG                  ParameterCount
);

Parameters

File

Type: _In_ HANDLE

A handle to the file from which to create a file mapping object.

The file must be opened with access rights that are compatible with the protection flags that the flProtect parameter specifies. It is not required, but it is recommended that files you intend to map be opened for exclusive access. For more information, see File security and access rights.

If hFile is INVALID_HANDLE_VALUE, the calling process must also specify a size for the file mapping object in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. In this scenario, CreateFileMapping creates a file mapping object of a specified size that is backed by the system paging file instead of by a file in the file system.

SecurityAttributes

Type: _In_opt_ SECURITY_ATTRIBUTES*

A pointer to a SECURITY_ATTRIBUTES structure that determines whether a returned handle can be inherited by child processes. The lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure specifies a security descriptor for a new file mapping object.

If lpAttributes is NULL, the handle cannot be inherited and the file mapping object gets a default security descriptor. The access control lists (ACL) in the default security descriptor for a file mapping object come from the primary or impersonation token of the creator. For more information, see File Mapping Security and Access Rights.

DesiredAccess

Type: _In_ ULONG

The desired access mask for the returned file mapping handle. For a list of access rights, see File-mapping security and access rights.

PageProtection

Type: _In_ ULONG

Specifies the page protection of the file mapping object. All mapped views of the object must be compatible with this protection.

This parameter can be one of the following values.

AllocationAttributes

Type: _In_ ULONG

You can specify one or more of the following attributes for the file mapping object. Also see the PageProtection parameter.

MaximumSize

Type: _In_ ULONG64

The maximum size of the file mapping object.

If this parameter is 0 (zero), then the maximum size of the file mapping object is equal to the current size of the file that hFile identifies.

An attempt to map a file with a length of 0 (zero) fails with an error code of ERROR_FILE_INVALID. You should test for files with a length of 0 (zero), and reject those files.

Name

Type: _In_opt_ PCWSTR

The name of the file mapping object.

If this parameter matches the name of an existing mapping object, then the function requests access to the object with the protection that flProtect specifies.

If this parameter is NULL, then the file mapping object is created without a name.

If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or job object, the function fails, and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same namespace.

The name can have a "Global" or "Local" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\). Creating a file mapping object in the global namespace from a session other than session zero requires the SeCreateGlobalPrivilege privilege. For more information, see Kernel Object Namespaces.

Fast user switching is implemented by using Terminal Services sessions. The first user to log on uses session 0 (zero), the next user to log on uses session 1 (one), and so on. Kernel object names must follow the guidelines that are outlined for Terminal Services so that applications can support multiple users.

ExtendedParameters

Type: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*

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).

ParameterCount

In ULONG ParameterCount

The number of extended parameters pointed to by ExtendedParameters.

Return value

If the function succeeds, the return value is a handle to the newly created file mapping object.

If the object exists before the function call, the function returns a handle to the existing object (with its current size, not the specified size), and GetLastError returns ERROR_ALREADY_EXISTS.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

See the Remarks for CreateFileMapping.

Examples

For an example, see Creating named shared memory, or Creating a file mapping using large pages.

Requirements

See also

CloseHandle

CreateFileMappingNuma

Creating a file mapping object

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

Memory management functions

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile