CreateFileForMapping

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates or opens a file that can be used for memory mapping. This funciton is obsolete. Use the CreateFile function instead.

Syntax

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

Parameters

• lpFileName
  [in] Pointer to a null-terminated string that specifies the name of the file to be created and used as a file-mapping object. The maximum length is MAX_PATH characters. Each object type, such as memory maps, semaphores, events, message queues, mutexes, and watchdog timers, has its own separate namespace. Empty strings ("") are handled as named objects. On Windows desktop-based platforms, synchronization objects all share the same namespace.

• dwDesiredAccess
  [in] Specifies the type of access. An application can obtain read-only access to files or query device attributes. The following table shows possible values.

  Value	Description
  GENERIC_READ	Specifies read access to the file. Data can be read from the file, and the file pointer can be moved.
  GENERIC_WRITE	Specifies write access to files.
  Zero	Enables an application to query device attributes without accessing the device.

  The share mode for a file is determined by this parameter. If this parameter is set to GENERIC_READ, the FILE_SHARE_READ share mode is used. This enables other open operations to be performed on the file for read access. Otherwise, the share mode is set to zero, and file sharing is not enabled.

• dwShareMode
  [in] Ignored.

• lpSecurityAttributes
  [in] Not used. Set to NULL.

• dwCreationDisposition
  [in] The following table shows possible values.

  Value	Description
  CREATE_ALWAYS	Creates a new file. The function overwrites the file if it already exists.
  CREATE_NEW	Creates a new file. The function fails if the specified file already exists.
  OPEN_ALWAYS	Opens the file if it exists. If the file does not exist, the function creates the file as if this parameter were set to CREATE_NEW.
  OPEN_EXISTING	Opens the file. The function fails if the file does not exist.
  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
  [in] Specifies attributes and flags for the file.

  Any combination of valid attributes is acceptable. However, all other file attributes override FILE_ATTRIBUTE_NORMAL. The following table shows possible attribute values.

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

  Any combination of the following flags is acceptable. The following table shows possible flag values*.*

  Value	Description
  FILE_FLAG_RANDOM_ACCESS	Indicates that the file is accessed randomly. The OS 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.
  FILE_FLAG_WRITE_THROUGH	Instructs the OS to write through any intermediate cache and go directly to the file. The OS can still cache write operations, but cannot lazily flush them.

• hTemplateFile
  Not used. Ignored.

Return Value

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

Remarks

This function is a special version of CreateFile that is designed for file-mapping objects. It performs a callback into the kernel 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 this function to open any file, including files that are created by CreateFile, for memory mapping. Like CreateFile, you can also create a file with this function.

The handle-closing semantics of this function are different from those of CreateFile. The following is important information about handles received from this function

• The kernel automatically closes the handle that you receive from this function.
  If your process exits without having called this function, as well as CloseHandle, the handle returned by this function is automatically closed.
  This function opens a file and returns a file handle that is passed to the CreateFileMapping function. CreateFileMapping then returns a handle to the file mapping. For Windows Embedded CE, it is only necessary to close the mapping handle because the file handle is automatically closed when you close the mapping handle.

• A memory-mapped file should not be accessed by using the ReadFile or the WriteFile functions. This can result in inconsistencies between the file and the memory-mapped file.

• Two writable handles to the same file cannot be open at the same time to prevent inconsistencies between the file and the mapped view of it. For two processes to share the data in a memory-mapped file, they must both memory-map the file. The FILE_SHARE_WRITE flag is ignored and should not be used.

• The handle returned from this function is used as the hFile parameter in a subsequent call to CreateFileMapping, as shown in the following example:

  // Shows call sequence, use of the handle.
  HANDLE hFile;
  hFile = CreateFileForMapping(...);
  CreateFileMapping(hFile, ...);
  

Requirements

See Also

Reference

File Mapping Functions
CreateFileMapping
MapViewOfFile
UnmapViewOfFile

Other Resources