DosAllocMem

DosAllocMem is used to allocate a private memory object, within the boundaries of the virtual-address space.

Syntax

DosAllocMem( pBaseAddress, ulObjectSize, ulAllocationFlags )

Parameters

PPVOID pBaseAddress (output)

This is a pointer to the variable which will receive the base address of the allocated private memory object.

ULONG ulObjectSize (input)

The size in bytes of the memory block you want to allocate. This will, by the system, be rounded up to the next page-size boundary.

ULONG ulAllocationFlags (input)

Flags used to describe allocation attributes, as well as access protection of the private memory block.

Allocation attributes

PAG_COMMIT (0x00000010) makes all private memory blocks initially committed.

OBJ_TILE (0x00000040) forces the memory block to be allocated in the first 512MB of virtual-address space. Mapping the memory block is done with the 16-bit selectors. The following table shows how a 32-bit memory block is mapped using 16-bit selectors.

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

PAG_EXECUTE (0x00000004) tells the system that 'execute access' to the committed pages is desired in the memory block.

PAG_READ (0x00000001) tells the system that 'read access' is desired.

PAG_WRITE (0x00000002) tells the system that 'write access' is desired.

PAG_GUARD (0x00000008) tells the system that an access to the committed pages should cause a guard page exception to be raised.

At least one of PAG_EXECUTE, PAG_WRITE or PAG_READ 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

Sample Code

#define INCL_DOSMEMMGR
#include <os2.h>
#include <bsememf.h> /* This will get the memory managment flags */

PVOID BaseAddress;      /* Pointer to the allocated memory block  */
ULONG ObjectSize;       /* The requested size of the memory block */
ULONG AllocationFlags;  /* Flags                                  */
APIRET rc;              /* Will receive the return code           */

   ObjectSize = 9000;   /* Asking for 9000 bytes, this will */
                        /* rounded up to 12KB.              */

   AllocationFlags = PAG_WRITE | PAG_EXECUTE;
            /* Allows read/write to the memory block, but */
            /* the block isn't committed within memory    */
            /* yet.                                       */

   rc = DosAllocMem(&BaseAddress, ObjectSize, AllocationFlags);

   if ( rc != 0)
   {
     /* We have an error we must take care of. */
   }

See Also

• DosAllocSharedMem
• DosFreeMem