CreateFileForMapping

  • Article

This function creates or opens 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
    [in] 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
    [in] Specifies the type of access. An application can obtain read-only access to files, or query device attributes. The following table shows 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 Specifies write access to files in Windows CE versions 2.10 and later.

  • dwShareMode
    [in] Specifies how this file can be shared. This parameter must be some combination of appropriate values. The following table shows values for dwShareMode.

    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 CreateFile is opening the client end of a mailslot, this flag is specified.

  • lpSecurityAttributes
    [in] Not used; set to NULL.

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

    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 dwCreationDistribution were 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
    [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 for dwFlagsAndAttributes.

    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 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 Indicates that the file has no other attributes set. This attribute is valid only if used alone.
    FILE_ATTRIBUTE_HIDDEN Indicates that the file is hidden. It is not to be included in an ordinary directory listing.
    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 operating system.

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

    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 dwCreationDistribution is 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

The CreateFileForMapping function is a special version of CreateFile that 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 CreateFileForMapping to 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 CreateFileForMapping is used as the hFile parameter in a subsequent call to CreateFileMapping, as shown in the following example.

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

If your process exits without having called CreateFileMapping as well as CloseHandle, the handle returned by CreateFileForMapping is automatically closed.

When an application passes a file handle returned from a call to the CreateFileForMapping function to the CreateFileMapping function, then the CloseHandle function will always return false. The handle specified with the hFile parameter is closed automatically by the kernel.

The FILE_SHARE_WRITE flag will be ignored and should not be used. Two writeable handles to the same file cannot be open at the same time to prevent inconsistencies between the file and the mapped view of it. In addition, using CreateFileForMapping to open the file more than once at a time, no matter what access flags are used, 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. That application should also give the mapping a name when it calls the CreateFileMapping function. All other applications should map the file with CreateFileMapping, using INVALID_HANDLE_VALUE as the file handle and using the name to identify the mapping.

Requirements

OS Versions: Windows CE 1.01 and later.
Header: Winbase.h.
Link Library: Coredll.lib.

See Also

CreateFileMapping | MapViewOfFile | UnmapViewOfFile

 Last updated on Friday, April 09, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.