Creates or opens a named or unnamed file mapping object for a specified file.

To specify the NUMA node for the physical memory, seeCreateFileMappingNuma.

Syntax

HANDLE CreateFileMappingA(  [in]           HANDLE                hFile,  [in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,  [in]           DWORD                 flProtect,  [in]           DWORD                 dwMaximumSizeHigh,  [in]           DWORD                 dwMaximumSizeLow,  [in, optional] LPCSTR                lpName);

Parameters

[in] hFile

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 theflProtect parameter specifies. It is not required, but it is recommended that filesyou intend to map be opened for exclusive access. For more information, seeFile Security and Access Rights.

IfhFile isINVALID_HANDLE_VALUE, the calling processmust also specify a size for the file mapping object in thedwMaximumSizeHigh anddwMaximumSizeLow parameters. In this scenario,CreateFileMapping creates a file mapping objectof a specified size that is backed by the system paging file instead of by a file in the file system.

[in, optional] lpFileMappingAttributes

A pointer to aSECURITY_ATTRIBUTESstructure that determines whether a returned handle can be inherited by child processes. ThelpSecurityDescriptor member of theSECURITY_ATTRIBUTES structure specifies asecurity descriptor for a new file mapping object.

IflpFileMappingAttributes isNULL, the handle cannot be inheritedand the file mapping object gets a default security descriptor. The access control lists (ACL) in the defaultsecurity descriptor for a file mapping object come from the primary or impersonation token of the creator. Formore information, seeFile Mapping Security and Access Rights.

[in] flProtect

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

This parameter can be one of the following values.

An application can specify one or more of the following attributes for the file mapping object by combiningthem with one of the preceding page protection values.

[in] dwMaximumSizeHigh

The high-orderDWORD of the maximum size of the file mapping object.

[in] dwMaximumSizeLow

The low-orderDWORD of the maximum size of the file mapping object.

If this parameter anddwMaximumSizeHigh are 0 (zero), the maximum size of the filemapping object is equal to the current size of the file thathFile identifies.

An attempt to map a file with a length of 0 (zero) fails with an error code ofERROR_FILE_INVALID. Applications should test for files with a length of 0 (zero) andreject those files.

[in, optional] lpName

The name of the file mapping object.

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

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

IflpName matches the name of an existing event, semaphore, mutex, waitable timer, orjob object, the function fails, and theGetLastErrorfunction returnsERROR_INVALID_HANDLE. This occurs because these objects share thesame namespace.

The name can have a "Global" or "Local" prefix to explicitly create theobject in the global or session namespace. The remainder of the name can contain any character except thebackslash character (\). Creating a file mapping object in the global namespace from a session other thansession zero requires theSeCreateGlobalPrivilegeprivilege. For more information, seeKernel Object Namespaces.

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

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 itscurrent size, not the specified size), andGetLastError returnsERROR_ALREADY_EXISTS.

If the function fails, the return value isNULL. To get extended error information,callGetLastError.

Remarks

After a file mapping object is created, the size of the file must not exceed the size of the file mappingobject; if it does, not all of the file contents are available for sharing.

If an application specifies a size for the file mapping object that is larger than the size of the actual namedfile on disk and if the page protection allows write access (that is, theflProtectparameter specifiesPAGE_READWRITE orPAGE_EXECUTE_READWRITE), then the file on disk is increased to match the specified sizeof the file mapping object. If the file is extended, the contents of the file between the old end of the file andthe new end of the file are not guaranteed to be zero; the behavior is defined by the file system. If the fileon disk cannot be increased,CreateFileMapping failsandGetLastError returnsERROR_DISK_FULL.

The initial contents of the pages in a file mapping object backed by the operating system paging file are 0(zero).

The handle thatCreateFileMapping returns hasfull access to a new file mapping object, and can be used with any function that requires a handle to a filemapping object.

Multiple processes can share a view of the same file by either using a single shared file mapping object orcreating separate file mapping objects backed by the same file. A single file mapping object can be shared bymultiple processes through inheriting the handle at process creation, duplicating the handle, or opening the filemapping object by name. For more information, see theCreateProcess,DuplicateHandle andOpenFileMapping functions.

Creating a file mapping object does not actually map the view into a process address space. TheMapViewOfFile andMapViewOfFileEx functions map a view of a file into aprocess address space.

With one important exception, file views derived from any file mapping object that is backed by the same fileare coherent or identical at a specific time. Coherency is guaranteed for views within a process and for viewsthat are mapped by different processes.

The exception is related to remote files. AlthoughCreateFileMapping works with remote files, it doesnot 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 file and a file that is accessed by using the input and output (I/O) functions(ReadFile andWriteFile) are not necessarily coherent.

Mapped views of a file mapping object maintain internal references to the object, and a file mapping objectdoes not close until all references to it are released. Therefore, to fully close a file mapping object, anapplication must unmap all mapped views of the file mapping object by callingUnmapViewOfFile and close the file mapping objecthandle by callingCloseHandle. These functions can becalled in any order.

When modifying a file through a mapped view, the last modification timestamp may not be updated automatically.If required, the caller should useSetFileTime to set thetimestamp.

Creating a file mapping object in the global namespace from a session other than session zero requires theSeCreateGlobalPrivilege privilege.Note that this privilege check is limited to the creation of file mapping objects and does not apply to openingexisting ones. For example, if a service or the system creates a file mapping object in the global namespace, anyprocess running in any session can access that file mapping object provided that the caller has the requiredaccess rights.

Windows XP:  The requirement described in the previous paragraph was introduced with Windows Server 2003and Windows XP with SP2

Use structured exception handling to protect any code that writes to or reads from a file view. For moreinformation, seeReading and Writing From a File View.

To have a mapping with executable permissions, an application must callCreateFileMapping with eitherPAGE_EXECUTE_READWRITE orPAGE_EXECUTE_READ, and thencallMapViewOfFile withFILE_MAP_EXECUTE | FILE_MAP_WRITE orFILE_MAP_EXECUTE | FILE_MAP_READ.

In Windows Server 2012, this function is supported by the following technologies.

Examples

For an example, seeCreating Named Shared Memory orCreating a File Mapping Using Large Pages.

Requirements

See also

CloseHandle

CreateFileMappingNuma

Creating a File Mapping Object

DuplicateHandle

File Mapping Functions

MapViewOfFile

MapViewOfFileEx

Memory Management Functions

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile