RtCreateSharedMemory

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

Syntax

Copy

HANDLE RtCreateSharedMemory(
    [in]  DWORD flProtect,
    [in]           DWORD MaximumSizeHigh,
    [in]           DWORD MaximumSizeLow,
    [in]           LPCTSTR lpName,
    [out]          VOID ** location
);

Parameters

[in] flProtect

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.

[in] MaximumSizeHigh

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

[in] MaximumSizeLow

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

[in] lpName

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

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.

[out] location

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

Return Value

If the function succeeds, it returns a handle to the shared memory object. If the function fails, it returns NULL. Call GetLastError to obtain an error code.

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 wRTOS and Windows.

When you make the call from a wRTOS 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, RtCreateSharedMemory fails with ERROR_ALREADY_EXISTS and the shared memory does not shrink. If the requested amount of memory is greater than the current size of the shared memory object, the shared memory does not expand and RtCreateSharedMemory fails with ERROR_INVALID_PARAMETER.
If a Windows process requests an amount of memory smaller than the current size, the object size is reduced accordingly, the specified memory is returned, and RtCreateSharedMemory fails with ERROR_ALREADY_EXISTS. However, if the requested memory is greater then the current size, the shared memory remains unchanged, and RtCreateSharedMemory fails with ERROR_INVALID_PARAMETER.

Remarks

The handle that RtCreateSharedMemory returns has complete 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.

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.

Requirements

Minimum supported version	Header	Library
wRTOS 1.0 SDK	RtApi.h	RtApi.lib (Windows), Startup.lib (RTSS)