INF: Dynamically Growing Named File Mappings

PSS ID Number: Q104012
Article last modified on 12-23-1993

3.10
WINDOWS

----------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Win32 Software Development Kit (SDK) for Windows NT,
   version 3.1
----------------------------------------------------------------------

SUMMARY
=======
CreateFileMapping() can be used to create a named file mapping object,
which is generally used as shared memory between applications. This
call can use/grow an existing file on disk, use a temporary file it
first creates, or use part of the system pagefile.
Mapping a view of the file with MapViewOfFile() maps a range of
virtual memory addresses to the appropriate file. Anything that is
written to the pointer returned from MapViewOfFile() will be written
to the file on disk. All applications with views to this file mapping
object will see the same data. It is important to remember that you
cannot force the view beyond the end of the file mapping object.
If you have a named file mapping object that needs to be bigger, the
file can be grown by calling CreateFileMapping() a second time,
specifying a larger size than was specified the previous time. Be sure
to specify (as a first parameter) both a handle to the same file that
was specified originally and the same name. Otherwise, this file will
be grown to the size specified, but it will not be used as the file
mapping object. Note that the handle does not need to be closed to do
this.
The handle that you receive will be a handle to the original file
mapping object, although the handle itself will be different.

MORE INFORMATION
================
Be sure to check the return code to verify that a file mapping object
was created. If you have a handle, it is still a good idea to call
GetLastError(). If GetLastError() returns 0 (zero) when creating a
named object, this indicates that you have been given the single
handle to this file mapping object. If it returns
ERROR_ALREADY_EXISTS, then you have been given another handle to an
existing file mapping object. If this is intentional (perhaps you are
trying to grow the mapping as described above) and you specified the
correct handle in the first parameter of CreateFileMapping(), then you
can use the handle safely. If you did not intend to be using an
existing file mapping object, chances are that you will have problems.
In this case, release the handle just received by calling
CloseHandle(), and call specifying a new name for the file mapping
object.

Additional reference words: 3.10
KBCategory:
KBSubcategory:
Copyright Microsoft Corporation 1993.