View source for DosAllocSharedMem

== 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.
{|class="wikitable"
|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==
<PRE>
#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. */
}
</PRE>

==See Also==
*[[DosAllocMem]]
*[[DosFreeMem]]
*[[DosGetNamedSharedMem]]
*[[DosGetSharedMem]]
*[[DosGiveSharedMem]] 

[[Category:Dos]]