CreateFileMapping

HANDLE CreateFileMapping(hFile, lpsa, fdwProtect, dwMaximumSizeHigh, dwMaximumSizeLow, lpszMapName)
HANDLE hFile;	/* handle to file to map	*/
LPSECURITY_ATTRIBUTES lpsa;	/* optional security attributes	*/
DWORD fdwProtect;	/* desired protection for mapping object	*/
DWORD dwMaximumSizeHigh;	/* high 32 bits of object size	*/
DWORD dwMaximumSizeLow;	/* low 32 bits of object size	*/
LPTSTR lpszMapName;	/* name of mapping object	*/

The CreateFileMapping function creates a named or unnamed file mapping object for the specified file.

Parameters

hFile

Identifies the file for which to create a mapping object. The file must be opened with an access mode that is compatible with the protection flags specified by fdwProtect.

If hFile is (HANDLE)0xFFFFFFFF, the caller must also specify a mapping object size via the dwMaximumSizeHigh and dwMaximumSizeLow parameters. The function will create a file mapping object of the specified size that is backed by the system paging file rather than by a named file in the file system. The file mapping object can be shared through duplication, inheritance, or by name.

lpsa

Points to a SECURITY_ATTRIBUTES data structure that specifies the security attributes for the mapping object.

The SECURITY_ATTRIBUTES structure has the following format:

typedef struct _SECURITY_ATTRIBUTES { /* sa */

DWORD nLength;

LPVOID lpSecurityDescriptor;

BOOL bInheritHandle;

} SECURITY_ATTRIBUTES;

If the parameter is not specified, the mapping object is created without a security descriptor, and the resulting handle cannot be inherited.

fdwProtect

Specifies the protection desired for the mapping object when the file is mapped. This parameter can be one of the following values:

Value

Meaning

PAGE_READONLY	Read access to the committed region of pages is allowed. An attempt to write or execute the committed region results in an access violation. The file specified by hFile must have been created with GENERIC_READ access.
PAGE_READWRITE	Read and write access to the committed region of pages is allowed. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.

dwMaximumSizeHigh

Specifies the high-order 32 bits of the maximum size of the file mapping object.

dwMaximumSizeLow

Specifies the low-order 32 bits of the maximum size of the file mapping object. If dwMaximumSizeLow and dwMaximumSizeHigh are zero, the maximum size of the file mapping object is equal to the current size of the file identified by hFile.

lpszMapName

Points to a null-terminated string specifying the name of the mapping object. The name may contain any character except the pathname separator character '\'.

If lpszMapName matches the name of an existing named object, this function requests access to the existing mapping object with the protection specified by fdwProtect.

If lpszMapName is NULL, the mapping object is created without a name.

Return Value

If the function is successful, the return value is a handle to the mapping object. If the mapping object existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. If the mapping object did not exist, GetLastError returns zero.

If the function fails, the return value is NULL. Use the GetLastError function to obtain extended error information.

Comments

Once a file mapping object is created, the size of the file must not exceed the size of the file mapping object.

The handle that CreateFileMapping returns has full access to the new file mapping object. It may be used with any function that requires a handle to a file mapping object. File mapping objects may be shared either through process creation, handle duplication, or by name. For information on duplicating handles, see the DuplicateHandle function reference page. For information on opening a file mapping object by name, see the OpenFileMapping function reference page.

Creating a file mapping object creates the potential for mapping a view of the file, but does map the view. The MapViewOfFile and MapViewOfFileEx functions map a view of a file into a process' address space.

It is recommended, though not required, that files you intend to map be opened for exclusive access.

Win32 does not require that a mapped file and a file accessed via the input/output primitive functions (ReadFile and WriteFile) are coherent (contain identical data at a given time). Win32 does guarantee that all views of a single mapping object are coherent. This means that if multiple processes have a handle to a given file mapping object, they will see a coherent view of the data when they map a view of the object.

The CreateFileMapping function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

Example

To implement a mapping-object creation function that fails if the object already exists, an application can use the following code:

hMap = CreateFileMapping(...);

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

CloseHandle(hMap);

hMap = NULL;

}

return hMap;