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

The OS/2 API Project

DosAllocMem

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

Syntax

 rc = DosAllocMem( pBaseAddress, ulObjectSize, ulAllocationFlags );

Parameters
PPVOID pBaseAddress (output)
This is a pointer to the variable which will recieve 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

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

Setting 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 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_EXECUTE (0x00000004) tells the system that 'execute access' to the commited pages is desired in the memory block.

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_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
0NO_ERROR
8ERROR_NOT_ENOUGH_MEMORY
87ERROR_INVALID_PARAMETER
95ERROR_INTERRUPT

Include Info

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

Usage Explanation

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

Relevant Structures

Gotchas

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 recieve 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

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

DosAllocMem