[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosAllocSharedMem

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 rc = DosAllocSharedMem( pBaseAddress, pszName, ulObjectSize, ulFlags );

Parameters
PPVOID pBaseAddress (output)
This is a pointer to the variable that should recieve 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 commited 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 512MB of virtual-address space, using 16-bit selectors to map the memory object.

32bit Offset16bit alias selectors
BaseAddress+000KBSel
BaseAddress+064KBSel + HugeInc
BaseAddress+128KBSel + 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
0NO_ERROR
8ERROR_NOT_ENOUGH_MEMORY
87ERROR_INVALID_PARAMETER
95ERROR_INTERRUPT
123ERROR_INVALID_NAME
183ERROR_ALREADY_EXISTS

Include Info

 #define INCL_DOSMEMMGR
#include <bsememf.h>
#include <os2.h>

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 uses 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 gets 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 4KB, since this is the default value.

OBJ_TILE is used for compability with the existing 16-bit implementation of OS/2. Using this flag forces the shared memory to be allocated within the first 512MB of the virtual-address space.

Relevant Structures

Gotchas

Sample Code

 #define INCL_DOSMEMMGR #include <os2.h> #include <bsememf.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; /* Recieving 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 commited at once within the */ /* virtual memory. */ rc = DosAllocSharedMem( &BaseAddress, Name, ObjectSize, Flags); if (rc != 0) { /* We have an error we must take care of. */ }

See Also

 DosAllocMem, DosFreeMem, DosGetNamedSharedMem, DosGetSharedMem, DosGiveSharedMem

Author

Stefan Mars - mars@lysator.liu.se

Additions

Last modified March 16/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosAllocSharedMem