CreateFileMapping

This function creates a named or unnamed file-mapping object for the specified file.

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

Parameters

  • hFile
    Handle to the file from which to create a mapping object. The file must be opened with an access mode compatible with the protection flags specified by the flProtect parameter. It is recommended, though not required, that files you intend to map be opened for exclusive access.

    If hFile is (HANDLE)INVALID_HANDLE_VALUE, the calling process must also specify a mapping object size in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. The function creates a file-mapping object of the specified size backed by physical memory rather than by a named file in the file system. The file-mapping object can be shared by name. In Windows CE, memory utilized for the mapping object is not part of the 32 MB virtual process space.

  • lpFileMappingAttributes
    Ignored. Must be NULL.

  • flProtect
    Specifies the protection desired for the file view, when the file is mapped. This parameter can be one of the following values:

    Value Description
    PAGE_READONLY Gives read-only access to the committed region of pages. An attempt to write to or execute the committed region results in an access violation. The file specified by the hFile parameter must have been created with GENERIC_READ access. You cannot specify PAGE_READONLY without a file handle.
    PAGE_READWRITE Gives read-write access to the committed region of pages. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.
    PAGE_WRITECOPY Not supported.

    In addition, an application can specify certain section attributes by combining (using the bitwise OR operator) one or more of the following section attribute values with one of the preceding page protection values:

    Value Description
    SEC_COMMIT Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting.
    SEC_IMAGE Not supported.
    SEC_NOCACHE Not supported.
    SEC_RESERVE Not supported.
  • 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 this parameter and dwMaximumSizeHigh are zero, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.

  • lpName
    Long pointer to a null-terminated string specifying the name of the mapping object. The name can contain any character except the backslash character (\).

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

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

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

Return Values

A handle to the file-mapping object indicates success. If the object existed 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. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If you call CreateFileMapping with a handle from CreateFileForMapping and it fails for any reason, the handle is closed. For instance, any attempt to use the CloseHandle function on a file handle that was returned from CreateFileForMapping and then used in a failed call to CreateFileMapping will automatically return false. Instead, the kernel automatically closes the handle specified in the hFile parameter.

This function will not work on a Windows CE–based platform that does not support Page-In.

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object; if it does, not all of the files contents will be available for sharing.

If an application specifies a size for the file-mapping object that is larger than the size of the actual named file on disk, the file on disk is grown to match the specified size of the file-mapping object. If the file cannot be grown, this results in a failure to create the file-mapping object. GetLastError will return ERROR_DISK_FULL.

The handle that CreateFileMapping returns has full access to the new file-mapping object. It can be used with any function that requires a handle to a file-mapping object. File-mapping objects can be shared through process creation.

File handles that have been used to create file-mapping objects must not be used in subsequent calls to file I/O functions, such as ReadFile and WriteFile. In general, if a file handle has been used in a successful call to the CreateFileMapping function, do not use that handle unless you first close the corresponding file-mapping object.

Creating a file-mapping object creates the potential for mapping a view of the file but does not map the view. The MapViewOfFile function maps a view of a file into the address space of a process.

With one important exception, file views derived from a single file-mapping object are coherent, or identical, at a given time. If multiple processes have handles of the same file-mapping object, they see a coherent view of the data when they map a view of the file.

The exception has to do with remote files. Although CreateFileMapping works with remote files, it does not keep them coherent. For example, if two computers both map a file as writeable, and both change the same page, each computer will only see its own writes to the page. When the data gets updated on the disk, it is not merged.

A mapped file and a file accessed by means of the input and output (I/O) functions (ReadFile and WriteFile) are not necessarily coherent.

To fully close a file mapping object, an application must unmap all mapped views of the file mapping object by calling UnmapViewOfFile, and close the file mapping object handle by calling CloseHandle. The order in which these functions are called does not matter. The call to UnmapViewOfFile is necessary because mapped views of a file mapping object maintain internal open handles to the object, and a file mapping object will not close until all open handles to it are closed.

Note To guard against an access violation, use structured exception handling to protect any code that writes to or reads from a memory mapped view.

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 = INVALID_HANDLE_VALUE; 
} 
return hMap; 

Requirements

Runs On Versions Defined in Include Link to
Windows CE OS 1.01 and later Winbase.h   Coredll.lib, Nk.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CloseHandle, CreateFileForMapping, MapViewOfFile, ReadFile, UnmapViewOfFile, VirtualAlloc, WriteFile

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.