CreateFileForMapping

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function creates a file that can be used for memory mapping.

HANDLE CreateFileForMapping( LPCTSTR
lpFileName,
DWORD
dwDesiredAccess, 
DWORD
dwShareMode,
LPSECURITY_ATTRIBUTES
lpSecurityAttributes,
DWORD
dwCreationDisposition,
DWORD
dwFlagsAndAttributes,
HANDLE
hTemplateFile
);

Parameters

lpFileName

Pointer to a null-terminated string that specifies the name of the file that is to be created and used as a file-mapping object. The maximum length is MAX_PATH characters.

dwDesiredAccess

Specifies the type of access. An application can obtain read-only access to files, or query device attributes. You can use the following flag constants to build a value for this parameter.

Value	Description
0	Allows an application to query device attributes without actually accessing the device.
GENERIC_READ	Specifies read access to the file. Data can be read from the file and the file pointer can be moved.
GENERIC_WRITE	For Windows CE versions 2.10 and later, this flag specifies write access to the file.

dwShareMode

Specifies how this file can be shared. This parameter must be some combination of the following values:

Value	Description
0	Prevents the file from being shared.
FILE_SHARE_READ	Other open operations can be performed on the file for read access. If CreateFileis opening the client end of a mailslot, this flag is specified.
FILE_SHARE_WRITE	Other open operations can be performed on the file for write access. The file should be opened only one time using this setting. See the Remarks section for details.

lpSecurityAttributes

Not used; set to NULL.

dwCreationDisposition

This parameter is one of the following values:

Value	Description
CREATE_NEW	Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS	Creates a new file. The function overwrites the file if it exists.
OPEN_EXISTING	Opens the file. The function fails if the file does not exist.
OPEN_ALWAYS	Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDistributionwere CREATE_NEW.
TRUNCATE_EXISTING	Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes

Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable, except all other file attributes override FILE_ATTRIBUTE_NORMAL.

Value	Description
FILE_ATTRIBUTE_ARCHIVE	The file is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_NORMAL	The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_HIDDEN	The file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_READONLY	The file is read only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM	The file is part of or is used exclusively by the operating system.

Any combination of the following flags is acceptable:

Value	Description
FILE_FLAG_WRITE_THROUGH	Instructs the operating system to write through any intermediate cache and go directly to the file. The operating system can still cache write operations, but cannot lazily flush them.
FILE_FLAG_RANDOM_ACCESS	Indicates that the file is accessed randomly. Windows uses this flag to optimize file caching. Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

hTemplateFile

Not used; ignored.

Return Values

An open handle to the specified file-mapping object indicates success. If the specified object exists before the function call and dwCreationDistributionis CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastErrorreturns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file-mapping object does not exist before the call, GetLastErrorreturns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateFileForMappingfunction is a special version of CreateFilethat is designed for file-mapping objects. It performs a callback into the kernel's address space so that the specified file is created by the kernel. This ensures that the file is available to processes other than the creating process.

You can use CreateFileForMappingto open any file, including files that are created by CreateFile, for memory mapping. Like CreateFile, you can also create a file with CreateFileForMapping.

The handle returned from CreateFileForMappingis used as the hFileparameter in a subsequent call to CreateFileMapping, as shown in the following psuedo-code:

// psuedocode fragment to show call sequence, use
of the handle HANDLE hFile; hFile = CreateFileForMapping(...);
CreateFileMapping(hFile, ...);

If your process exits without having called CreateFileMapping,the handle returned by CreateFileForMappingis automatically closed.

When an application passes a file handle returned from a call to the CreateFileForMappingfunction to the CreateFileMappingfunction, then the CloseHandlefunction will always return false. The handle specified with the hFileparameter is closed automatically by the kernel.

A file can be opened once if dwShareModeis set to FILE_SHARE_WRITE. Opening the file more then once and mapping each file handle can introduce inconsistencies between mappings. Doing this also wastes virtual memory. If a single file must be shared between applications, then only one application should call CreateFileForMapping. All other applications should attempt to map the file with CreateFileMapping.

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.