RtCreateSharedMemory

RtCreateSharedMemory creates a named or unnamed region of physical memory that can be mapped by any process.

Syntax

HANDLE RtCreateSharedMemory(
    DWORD flProtect,
    DWORD MaximumSizeHigh,
    DWORD MaximumSizeLow,
    LPCTSTR lpName,
    VOID ** location
);

Parameters

flProtect (ignored by RTSS configurations - see Remarks below)

The protection desired for the shared memory view. This parameter can be one of the following values:

• SHM_MAP_READ 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.

• SHM_MAP_WRITE gives read-write access to the committed region of pages.

MaximumSizeHigh

The high-order 32 bits of the size of the shared memory object. This value can only be zero (0).

MaximumSizeLow

The low-order 32 bits of the size of the shared memory object.

lpName

A pointer to a null-terminated string specifying the name of the shared memory object. The name can contain any character except the backslash (\).

If this parameter matches the name of an existing named shared memory object, the function requests access to the shared memory object with the protection specified by flProtect.

If lpName matches the name of an existing event, mutex, or semaphore object, the function fails and GetLastError returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and shared memory objects share the same namespace.

If lpName is NULL, the mapping object is created without a name.

location

A pointer to a location where the virtual address of the shared memory will be stored.

Return Value

A handle to the shared memory object if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

If the shared memory object existed before the function call, GetLastError returns ERROR_ALREADY_EXISTS, and the return value is a valid handle to the existing shared memory object. If the mapping object did not exist, GetLastError returns zero and the location is set.

NOTE: If you use RtCreateSharedMemorywith the same name but a different size to create shared memory that already exists, the behavior differs between RTX64 and Windows.

• When you make the call from an RTX64 process, the size of the shared memory that is returned is equal to the amount that was created by the RtCreateSharedMemory call that first created the shared memory object. If the requested amount of memory is less than the current size of the shared memory object, the object's size is decreased to the requested size and that amount of memory is returned. If the requested amount of memory is greater than the current size of the shared memory object, the shared memory does not expand and the API fails with invalid parameter.
• When you make the call from a Windows process, the API fails with invalid parameter.

Remarks

The handle that RtCreateSharedMemory returns has full access to the new shared memory object. Shared memory objects can be shared by name. If you use RtCreateSharedMemory and the named object already exists, the behavior is similar to the behavior of RtOpenSharedMemory. For information on opening a shared memory object by name, see RtOpenSharedMemory.

To close a shared memory object, an application must close its handle by calling RtCloseHandle.

When all handles to the shared memory object representing the physical memory are closed, the object is destroyed and physical memory is returned to the system.

RtCreateSharedMemory will fail when a larger memory size is passed on a subsequent call to open the same name memory.

Parameter flProtect is ignored when RtCreateSharedMemory is called by an application that was built in an RTSS configuration. It is not ignored when called from an application built in a Windows configuration.

 

See Also:

RtCloseHandle

RtOpenSharedMemory