DosAllocMem: Difference between revisions

Latest revision as of 23:52, 27 November 2019

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. */
   }

@@ Line 1: / Line 1: @@
-=== Syntax ===
+DosAllocMem is used to allocate a private memory object, within the boundaries of the virtual-address space.
- rc = DosAllocMem( ''pBaseAddress'',
-                   ''ulObjectSize'',
-                   ''ulAllocationFlags'' );
+== Syntax ==
+ DosAllocMem( ''pBaseAddress'', ''ulObjectSize'', ''ulAllocationFlags'' )
 === Parameters ===
-PPVOID ''pBaseAddress'' (output)
+;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.
-This is a pointer to the variable which will recieve the base address of the allocated
+;ULONG ''ulAllocationFlags'' (input):Flags used to describe allocation attributes, as well as access protection of the private memory block.
-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
+:'''PAG_COMMIT''' (0x00000010) makes all private memory blocks initially committed.
-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.
+{|class="wikitable"
-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.
-{| border="1"
-|-
 |32bit Offset
-|16bit
+|16bit alias selectors
-alias selectors
 |-
 |BaseAddress+000KB
@@ Line 41: / Line 20: @@
 |-
 |BaseAddress+064KB
-|Sel
+|Sel + HugeInc
-+ HugeInc
 |-
 |BaseAddress+128KB
-|Sel
+|Sel + HugeInc * 2
-+ HugeInc * 2
 |-
-|. . .
+|...
-|. . .
+|...
-|} HugeInc is the same huge increment that is used by DosAllocHuge.
+|}
+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
+:'''PAG_EXECUTE''' (0x00000004) tells the system that 'execute access' to the committed pages is desired in the memory block.
-commited 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.
-Setting '''PAG_READ''' (0x00000001) tells the system that 'read 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.
-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
+ APIRET rc
-The following values can be returned
+The following values can be returned:
+*0 NO_ERROR
-{| border="1"
+*8 ERROR_NOT_ENOUGH_MEMORY
-|-
+*87 ERROR_INVALID_PARAMETER
-|0
+*95 ERROR_INTERRUPT
-|NO_ERROR
-|-
-|8
-|ERROR_NOT_ENOUGH_MEMORY
-|-
-|87
-|ERROR_INVALID_PARAMETER
-|-
-|95
-|ERROR_INTERRUPT
-|}
-=== Include Info ===
- #define INCL_DOSMEMMGR
- #include &lt;os2.h&gt;
- #include &lt;bsememf.h&gt;
-=== Usage Explanation ===
-DosAllocMem is used to allocate a private memory object, within the boundaries of the
-virtual-address space.
-=== Relevant Structures ===
-=== Gotchas ===
 === Sample Code ===
 <PRE>
 #define INCL_DOSMEMMGR
-#include
+#include <os2.h>
-#include     /* This will get the memory managment flags */
+#include <bsememf.h> /* This will get the memory managment flags */
-PVOID BaseAddress;      /* Pointer to the allocated memory block    */
+PVOID BaseAddress;      /* Pointer to the allocated memory block  */
-ULONG ObjectSize;       /* The requested size of the memory block   */
+ULONG ObjectSize;       /* The requested size of the memory block */
-ULONG AllocationFlags;  /* Flags                                    */
+ULONG AllocationFlags;  /* Flags                                  */
-APIRET rc;              /* Will recieve the return code             */
+APIRET rc;              /* Will receive the return code           */
     ObjectSize = 9000;   /* Asking for 9000 bytes, this will */
@@ Line 128: / Line 71: @@
     }
 </PRE>
 === See Also ===
- [[OS2 API:CPI:DosAllocSharedMem|CPI:DosAllocSharedMem]], [[OS2 API:CPI:DosFreeMem|CPI:DosFreeMem]]
+*[[DosAllocSharedMem]]
+*[[DosFreeMem]]
-[[Category:The OS/2 API Project]]
+[[Category:Dos]]