Difference between revisions of "DosAliasMem"

From EDM2
Jump to: navigation, search
(Created page with "==Description== DosAliasMem creates a private Read/Write alias or an LDT code segment alias to part of an existing memory object. The alias object is accessible only to the pr...")
 
m
Line 9: Line 9:
 
     APIRET APIENTRY DosAliasMem (PVOID pMem, ULONG cbSize, PPVOID ppAlias, ULONG flags)
 
     APIRET APIENTRY DosAliasMem (PVOID pMem, ULONG cbSize, PPVOID ppAlias, ULONG flags)
 
</PRE>
 
</PRE>
 +
 
==Parameters==
 
==Parameters==
; pMem (PMEM) input : Contains the address of the memory to be aliased. It must be on a page boundary (that is, 4K aligned), but may specify an address within a memory object.  
+
;pMem (PMEM) input : Contains the address of the memory to be aliased. It must be on a page boundary (that is, 4K aligned), but may specify an address within a memory object.
 
+
;cbSize (CBSIZE) input : Specifies the size in bytes for the memory to alias. The entire range must lie within a single memory object and must be committed if OBJ_SELMAPALL is specified.
; cbSize (CBSIZE) input : Specifies the size in bytes for the memory to alias. The entire range must lie within a single memory object and must be committed if OBJ_SELMAPALL is specified.  
+
 
+
 
; ppAlias (PPALIAS) output : Address of a location in which the address of the aliased memory is returned. The corresponding LDT selector is not explicitly returned but may be calculated by using the Compatibility Mapping Algorithm
 
; ppAlias (PPALIAS) output : Address of a location in which the address of the aliased memory is returned. The corresponding LDT selector is not explicitly returned but may be calculated by using the Compatibility Mapping Algorithm
 
+
sel = (SEL) ((ULONG) (*ppAlias) >> 13 | 7)
    sel = (SEL) ((ULONG) (*ppAlias) >> 13 | 7)
+
;flags (FLAGS) input : Flags are defined as follows:
 
+
:'''OBJ_SELMAPALL (0x00000800)'''
; flags (FLAGS) input : Flags are defined as follows
+
::OBJ_SELMAPALL creates a Read/Write 32 bit alias to the address specified. The entire range must be committed, start on page boundary and be within the extent of a single memory object. An LDT selector is created to map the entire range specified.
 
+
::If OBJ_SELMAPALL is not specified, then size is rounded up to a 4K multiple and the alias created inherits the permissions from the pages of the original object.
'''OBJ_SELMAPALL (0x00000800)'''
+
::OBJ_TILE may be specified, but currently this is enforced whether or not specified. This forces LDT selectors to be based on 64K boundaries.  
 
+
:'''SEL_CODE (0x00000001)'''
OBJ_SELMAPALL creates a Read/Write 32 bit alias to the address specified. The entire range must be committed, start on page boundary and be within the extent of a single memory object. An LDT selector is created to map the entire range specified.
+
::Marks the LDT alias selector(s) Read-Executable code selectors.  
 
+
:'''SEL_USE32 (0x00000002)'''
If OBJ_SELMAPALL is not specified, then size is rounded up to a 4K multiple and the alias created inherits the permissions from the pages of the original object.
+
::Used with OBJ_SELMAPALL, otherwise ignored. Marks the first alias LDT selector as a 32 bit selector by setting the BIG/C32 bit.
 
+
OBJ_TILE may be specified, but currently this is enforced whether or not specified. This forces LDT selectors to be based on 64K boundaries.  
+
 
+
'''SEL_CODE (0x00000001)'''
+
 
+
Marks the LDT alias selector(s) Read-Executable code selectors.  
+
+
'''SEL_USE32 (0x00000002)'''
+
 
+
Used with OBJ_SELMAPALL, otherwise ignored. Marks the first alias LDT selector as a 32 bit selector by setting the BIG/C32 bit.
+
  
 
==Return Code==
 
==Return Code==
 
  ulrc (APIRET) returns
 
  ulrc (APIRET) returns
 
+
DosAliasMem returns one of the following values:
DosAliasMem returns one of the following values
+
* 0 NO_ERROR
 
+
*   ERROR_NOT_ENOUGH_MEMORY
* 0         NO_ERROR
+
* 87 ERROR_INVALID_PARAMETER
*           ERROR_NOT_ENOUGH_MEMORY
+
* 95 ERROR_INTERRUPT  
* 87       ERROR_INVALID_PARAMETER
+
* 32798 ERROR_CROSSES_OBJECT_BOUNDARY  
* 95       ERROR_INTERRUPT  
+
* 32798     ERROR_CROSSES_OBJECT_BOUNDARY  
+
  
 
==Remarks==
 
==Remarks==
 
An export for DosAliasMem does not appear in versions of OS2386.LIB distributed prior to Warp Server for e-business. When using older versions, the following statements should be added to the link edit .DEF file
 
An export for DosAliasMem does not appear in versions of OS2386.LIB distributed prior to Warp Server for e-business. When using older versions, the following statements should be added to the link edit .DEF file
 
 
  importsDosAliasMem = DOSCALLS.298
 
  importsDosAliasMem = DOSCALLS.298
 
 
An alias is removed by calling DosFreeMem with the alias address.
 
An alias is removed by calling DosFreeMem with the alias address.
  
Line 58: Line 43:
 
==Example Code==
 
==Example Code==
 
<PRE>
 
<PRE>
#define INCL_DOSMEMMGR#include int main(int argc, char *argv[], char *envp[])
+
#define INCL_DOSMEMMGR
 +
#include <os2.h>
 +
 
 +
int main(int argc, char *argv[], char *envp[])
 
{
 
{
 
   PVOID pAlias;
 
   PVOID pAlias;
Line 72: Line 60:
  
 
   rc = DosAliasMem(pMem, 128*1024,  pAlias, OBJ_TILE);
 
   rc = DosAliasMem(pMem, 128*1024,  pAlias, OBJ_TILE);
 
 
   .
 
   .
 
   .
 
   .
 
   .
 
   .
  .
 
 
 
   return 0;
 
   return 0;
 
}
 
}
 
</PRE>
 
</PRE>
==Related Functions==
 
* [[OS2 API:CPI:DosAllocMem|DosAllocMem]]
 
* [[OS2 API:CPI:DosAllocSharedMem|DosAllocSharedMem]]
 
* [[OS2 API:CPI:DosFreeMem|DosFreeMem]]
 
  
 +
==Related Functions==
 +
*[[DosAllocMem]]
 +
*[[DosAllocSharedMem]]
 +
*[[DosFreeMem]]
  
[[Category:The OS/2 API Project]]
+
[[Category:Dos]]

Revision as of 14:03, 6 December 2016

Description

DosAliasMem creates a private Read/Write alias or an LDT code segment alias to part of an existing memory object. The alias object is accessible only to the process that created it. The original object must be accessible to the caller of DosAliasMem.

Syntax

#define INCL_DOSMEMMGR
#include  os2.h>

    APIRET APIENTRY DosAliasMem (PVOID pMem, ULONG cbSize, PPVOID ppAlias, ULONG flags)

Parameters

pMem (PMEM) input 
Contains the address of the memory to be aliased. It must be on a page boundary (that is, 4K aligned), but may specify an address within a memory object.
cbSize (CBSIZE) input 
Specifies the size in bytes for the memory to alias. The entire range must lie within a single memory object and must be committed if OBJ_SELMAPALL is specified.
ppAlias (PPALIAS) output 
Address of a location in which the address of the aliased memory is returned. The corresponding LDT selector is not explicitly returned but may be calculated by using the Compatibility Mapping Algorithm
sel = (SEL) ((ULONG) (*ppAlias) >> 13 | 7)
flags (FLAGS) input 
Flags are defined as follows:
OBJ_SELMAPALL (0x00000800)
OBJ_SELMAPALL creates a Read/Write 32 bit alias to the address specified. The entire range must be committed, start on page boundary and be within the extent of a single memory object. An LDT selector is created to map the entire range specified.
If OBJ_SELMAPALL is not specified, then size is rounded up to a 4K multiple and the alias created inherits the permissions from the pages of the original object.
OBJ_TILE may be specified, but currently this is enforced whether or not specified. This forces LDT selectors to be based on 64K boundaries.
SEL_CODE (0x00000001)
Marks the LDT alias selector(s) Read-Executable code selectors.
SEL_USE32 (0x00000002)
Used with OBJ_SELMAPALL, otherwise ignored. Marks the first alias LDT selector as a 32 bit selector by setting the BIG/C32 bit.

Return Code

ulrc (APIRET) returns

DosAliasMem returns one of the following values:

  • 0 NO_ERROR
  • ERROR_NOT_ENOUGH_MEMORY
  • 87 ERROR_INVALID_PARAMETER
  • 95 ERROR_INTERRUPT
  • 32798 ERROR_CROSSES_OBJECT_BOUNDARY

Remarks

An export for DosAliasMem does not appear in versions of OS2386.LIB distributed prior to Warp Server for e-business. When using older versions, the following statements should be added to the link edit .DEF file

importsDosAliasMem = DOSCALLS.298

An alias is removed by calling DosFreeMem with the alias address.

Though it is possible to create a Read/Write alias to a code segment to allow code modification this is not recommended. On Pentium(R) processors, and later, pipe-lining techniques used by the processor might allow the processor not to be aware of the modified code, if appropriate pipe-line serialization is not performed by the programmer. For further information see the processor documentation.

Example Code

#define INCL_DOSMEMMGR
#include <os2.h>

int main(int argc, char *argv[], char *envp[])
{
   PVOID pAlias;
   PVOID pMem;
   APIRET rc;

   /* alias a read-only shared memory object as a private read/write */
   /* object. This will allow clients of this object to read only    */
   /* while allowing the owner to update it.                         */

   rc=DosAllocSharedMem( pMem,NULL,128*1024,
      PAG_READ+PAG_COMMIT+OBJ_GIVEABLE);

   rc = DosAliasMem(pMem, 128*1024,  pAlias, OBJ_TILE);
   .
   .
   .
   return 0;
}

Related Functions