The main purpose of the CreateFileMapping function is to ensure that enough physical storage is
available for the file-mapping object. These two parameters tell the system the maximum size of the file in bytes. Two 32-bit
values are required because Windows supports file sizes that can be expressed using a 64-bit value; the
dwMaximumSizeHigh parameter specifies the high 32 bits, and the dwMaximumSizeLow parameter specifies the low 32
bits. For files that are less than 4 GB, dwMaximumSizeHigh will always be 0.
Using a 64-bit value means that Windows can process files as large as 16 EB (exabytes). If you want to create the
file-mapping object so that it reflects the current size of the file, you can pass 0 for both parameters. If you intend only to
read from the file or to access the file without changing its size, pass 0 for both parameters. If you intend to append data to
the file, you will want to choose a maximum file size that leaves you some breathing room. If the file on disk currently
contains 0 bytes, you can't pass two zeros to CreateFileMapping's dwMaximumSizeHigh and dwMaximumSizeLow
parameters. Doing so tells the system that you want a file-mapping object with 0 bytes of storage in it. This is an error and
CreateFileMapping will return NULL.
If you've paid attention so far, you must be thinking that something is terribly wrong here. It's nice that Windows supports
files and file-mapping objects that can be anywhere up to 16 EB, but how are you ever going to map a file that big into a
32-bit process' address space, which has a maximum limit of 4 GB (little of which is even usable)? I'll explain how you can
accomplish this in the next section. Of course, a 64-bit process has a 16-EB address space so that you can work with much
larger file mappings, but a similar limitation still exists if the file is super-big.
To really understand how CreateFile and CreateFileMapping work, you should try the following experiment. Take
the following code, build it, and then run it in a debugger. As you single-step through each statement, jump to a command
shell and execute a dir command on the C:\ directory. Notice the changes that are appearing in the directory as you
execute each statement in the debugger.
int WINAPI _tWinMain(HINSTANCE, HINSTANCE, PTSTR, int) {
// Before executing the line below, C:\ does not have
// a file called "MMFTest.Dat"
HANDLE hFile = CreateFile(TEXT("C:\\MMFTest.Dat"),
GENERIC_READ | GENERIC_WRITE,
FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL, NULL);
// Before executing the line below, the MMFTest.Dat
// file does exist but has a file size of 0 bytes.
HANDLE hFileMap = CreateFileMapping(hFile, NULL, PAGE_READWRITE,
0, 100, NULL);Windows via C/C++, Fifth Edition by Jeffrey Richter and Christophe Nasarre
// After executing the line above, the MMFTest.Dat
// file has a size of 100 bytes.
// Cleanup
CloseHandle(hFileMap);
CloseHandle(hFile);
// When the process terminates, MMFTest.Dat remains
// on the disk with a size of 100 bytes.
return(0);
}
If you call CreateFileMapping, passing the PAGE_READWRITE flag, the system checks to make sure that the
associated data file on the disk is at least the same size as the size specified in the dwMaximumSizeHigh and
dwMaximumSizeLow parameters. If the file is smaller than the specified size, CreateFileMapping makes the file on the
disk larger by extending its size. This enlargement is required so that the physical storage will already exist when the file is
used later as a memory-mapped file. If the file-mapping object is being created with the PAGE_READONLY or the PAGE_
WRITECOPY flag, the size specified to CreateFileMapping must be no larger than the physical size of the disk file. This
is because you won't be able to append any data to the file.
The last parameter of CreateFileMapping, pszName, is a zero-terminated string that assigns a name to this
file-mapping object. The name is used to share the object with another process. (An example of this is shown later in this
chapter. Chapter 3, "Kernel Objects," also discusses kernel object sharing in greater detail.) A memory-mapped data file
usually doesn't need to be shared; therefore, this parameter is usually NULL.
The system creates the file-mapping object and returns a handle identifying the object back to the calling thread. If the
system cannot create the file-mapping object, a NULL handle value is returned. Again, please remember that CreateFile
returns INVALID_HANDLE_VALUE (defined as -1) when it fails and CreateFileMapping returns NULL when it fails.
Don't get these error values confused.
