Jump to content

DosAllocMem: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(7 intermediate revisions by the same user not shown)
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 ===
=== 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 ===
=== 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
|32bit Offset
|16bit  
|16bit alias selectors
alias selectors
|-
|-
|BaseAddress+000KB
|BaseAddress+000KB
Line 41: Line 20:
|-
|-
|BaseAddress+064KB
|BaseAddress+064KB
|Sel  
|Sel + HugeInc
+ HugeInc
|-
|-
|BaseAddress+128KB
|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 ===
=== 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 ===
=== 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 <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 ===
=== Sample Code ===
<PRE>
<PRE>
#define INCL_DOSMEMMGR
#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 */
   ObjectSize = 9000;  /* Asking for 9000 bytes, this will */
Line 128: Line 71:
   }
   }
</PRE>
</PRE>
=== See Also ===
=== See Also ===
[[OS2 API:CPI:DosAllocSharedMem|DosAllocSharedMem]], [[OS2 API:CPI:DosFreeMem|DosFreeMem]]
*[[DosAllocSharedMem]]
 
*[[DosFreeMem]]


[[Category:The OS/2 API Project]]
[[Category:Dos]]

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

See Also

Retrieved from "https://www.edm2.com/index.php?title=DosAllocMem&oldid=65596"