|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| Yes
| Win32s
| Yes
| Import Library
| kernel32.lib
| Header File
| winbase.h
| Unicode
| WinNT
| Platform Notes
| None
|
|
|
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 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.
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
CloseHandle, DuplicateHandle, MapViewOfFile, MapViewOfFileEx, OpenFileMapping, ReadFile, SECURITY_ATTRIBUTES, UnmapViewOfFile, VirtualAlloc, WriteFile
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
