CreateFileMapping
The CreateFileMapping
function creates a named or unnamed file-mapping object for the specified file.
HANDLE CreateFileMapping(
|
HANDLE hFile, |
// handle to file
to map |
|
LPSECURITY_ATTRIBUTES lpFileMappingAttributes, |
// optional
security attributes |
|
DWORD flProtect, |
// protection for
mapping object |
|
DWORD dwMaximumSizeHigh, |
// high-order 32
bits of object size |
|
DWORD dwMaximumSizeLow, |
// low-order 32
bits of object size |
|
LPCTSTR lpName |
// name of
file-mapping object |
|
); |
|
Parameters
hFile
Identifies
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)0xFFFFFFFF, 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 the operating-system paging file rather than by a named file in the
file system. The file-mapping object can be shared through duplication, through
inheritance, or by name.
lpFileMappingAttributes
Pointer to a SECURITY_ATTRIBUTES structure that determines
whether the returned handle can be inherited by child processes. If lpFileMappingAttributes
is NULL, the handle cannot be inherited.
Windows NT:
The lpSecurityDescriptor member of the structure specifies a security
descriptor for the new file-mapping object. If lpFileMappingAttributes
is NULL, the file-mapping object gets a default security descriptor.
Windows 95:
The lpSecurityDescriptor member of the structure is ignored.
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. |
|
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 |
Gives copy
on write access to the committed region of pages. The files specified by the hFile
parameter must have been created with GENERIC_READ and GENERIC_WRITE access. |
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 |
The file
specified for a section s file mapping is an executable image file. Because
the mapping information and file protection are taken from the image file, no
other attributes are valid with SEC_IMAGE. |
|
SEC_NOCACHE |
All pages
of a section are to be set as non-cacheable. This attribute is intended for
architectures requiring various locking structures to be in memory that is
never fetched into the processor s. On 80x86 and MIPS machines, using the
cache for these structures only slows down the performance as the hardware
keeps the caches coherent. Some device drivers require noncached data so that
programs can write through to the physical memory. SEC_NOCACHE requires
either the SEC_RESERVE or SEC_COMMIT to also be set. |
|
SEC_RESERVE |
Reserves
all pages of a section without allocating physical storage. The reserved
range of pages cannot be used by any other allocation operations until it is
released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function. This attribute
is valid only if the hFile parameter is (HANDLE)0xFFFFFFFF; that is, a
file mapping object backed by the operating sytem paging file. |
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 dwMaximumSizeHig are zero, the maximum size of the
file-mapping object is equal to the current size of the file identified by hFile.
lpName
Points 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.
Return Values
If the
function succeeds, the return value is a handle to the file-mapping object. If
the object existed before the function call, the GetLastError function returns
ERROR_ALREADY_EXISTS, and the return value is a valid handle to the existing
file-mapping object (with its current size, not the new specified size. If the
mapping object did not exist, GetLastError returns zero.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
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 file s 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.
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 either through process
creation, through handle duplication, or by name. For information on
duplicating handles, see DuplicateHandle. For information on opening a file-mapping
object by name, see OpenFileMapping.
Windows
95: 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 and MapViewOfFileEx functions map a view of a
file into a process s address space.
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 writable, 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 UnmapViewOfFile18O.GTQ, 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.
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;
See Also