DosAllocSharedMem
Contents
Syntax
DosAllocSharedMem( pBaseAddress, pszName, ulObjectSize, ulFlags )
Parameters
- PPVOID pBaseAddress (output)
- This is a pointer to the variable that should receive the base address of the allocated memory space.
- PSZ pszName (input)
- This an optional address of a name string that is to be associated with the shared memory block which we are about to allocate. The name should be in the format of an OS/2 filename, and is an ordinary ASCIIZ string. Will be stored in the \SHAREMEM\ subdirectory.
- ULONG ulObjectSize (input)
- This is the size of the memory block we wish to allocate. It's given in bytes, and the system will round it up to the next page-size boundary. The page-size is on most systems (by default) 4096 bytes.
- ULONG ulFlags (input)
- Flags that describe the desired access protection and allocation attributes.
Allocation attributes
Setting PAG_COMMIT (0x00000010) will make all the pages in the allocated object committed initially.
Setting OBJ_GIVEABLE (0x00000200) specifies that access to the memory block can be given to another process, using the DosGiveSharedMem.
Setting OBJ_GETTABLE (0x00000100) specifies that the memory object can be accessed by another project. That process should use DosGetSharedMem to get access, this also forces that process to know the address of the memory block.
Setting OBJ_TILE (0x00000040) forces the system to allocate the memory block within the first 512 MB of virtual-address space, using 16-bit selectors to map the memory object.
| 32bit Offset | 16bit alias selectors |
| BaseAddress+000KB | Sel |
| BaseAddress+064KB | Sel + HugeInc |
| BaseAddress+128KB | Sel + HugeInc * 2 |
| ... | ... |
HugeInc is the same huge increment that is used by DosAllocHuge.
Access protection
Setting PAG_READ (0x00000001) tells the system that read access is desired.
Setting PAG_WRITE (0x00000002) tells the system that write access is desired.
Setting PAG_EXECUTE (0x00000004) tells the system that execute access is desired.
Setting PAG_GUARD (0x00000008) tells the system that access to the memory object should cause a guard page exception to be raised, in the subject process.
At least one of PAG_READ,PAG_WRITE or PAG_EXECUTE must be set.
Returns
- APIRET rc
- The following values can be returned:
- 0 NO_ERROR
- 8 ERROR_NOT_ENOUGH_MEMORY
- 87 ERROR_INVALID_PARAMETER
- 95 ERROR_INTERRUPT
- 123 ERROR_INVALID_NAME
- 183 ERROR_ALREADY_EXISTS
Usage Explanation
DosAllocSharedMem is used to allocate a shared memory object, within the virtual address space. When the allocated shared memory block is given a name, it can be shared with other processes. This other processes use DosGetNamedSharedMem to gain access to the memory block. Note that this requires that they know the name of the shared memory block.
If you don't specify a name it will be an unnamed shared memory block. An unnamed memory block can be shared with all other processes that get access using DosGetSharedMem, or DosGiveSharedMem.
As with DosAllocMem the allocated shared memory object is rounded up to a multiple of the page-size in size. The page-size will on most system be 4 KB, since this is the default value.
OBJ_TILE is used for compatibility with the existing 16-bit implementation of OS/2. Using this flag forces the shared memory to be allocated within the first 512 MB of the virtual-address space.
Sample Code
#define INCL_DOSMEMMGR
#include <bsememf.h>
#include <os2.h>
PVOID BaseAddress; /* Pointer to the base address of the allocated */
/* memory block */
UCHAR Name[40]; /* Pointer the requested name of the memory block */
/* which we are about to allocate. */
ULONG ObjectSize; /* The size of the memory space we wishes to allocate. */
/* It will be given in bytes. */
ULONG Flags; /* Flags describing the memory block's characteristics. */
APIRET rc; /* Receiving the return code */
strcpy(Name,"\\SHAREMEM\\BLOCK.DAT"); /* Name of the shared memory block. */
/* Note the \\SHAREMEM\\ prefix. */
ObjectSize = 8192; /* We request 8192 bytes, this is already a */
/* multiple of the page-size (assuming the */
/* default size of 4096 bytes), and will therefore */
/* not be rounded up by the system. */
Flags = PAG_WRITE | PAG_READ | PAG_COMMIT;
/* We request read and write access to the shared */
/* memory block, and also have the pages of the */
/* memory block committed at once within the */
/* virtual memory. */
rc = DosAllocSharedMem( &BaseAddress, Name, ObjectSize, Flags);
if (rc != 0)
{
/* We have an error we must take care of. */
}
