DosQueryMem

From EDM2
Jump to: navigation, search

Syntax

DosQueryMem( pBaseAddress, pulRegionSize, pulAllocationFlags )

Parameters

PVOID pBaseAddress (input)
This is the base address of the memory block to be queried.
PULONG pulRegionSize (input/output)
As input this is a pointer to a variable that contains the size in bytes of the range of pages to be queried. This size is then rounded so

that it includes all pages addressed by the requested base and size. As output this parameter will point to a variable that contains the actual size in bytes, of the queried pages.

PULONG pulAllocationFlags (output)
This is a pointer that upon return from the function call will receive the attribute flags that describe the allocation and access protection of

the queried memory block.

Allocation attributes

If PAG_COMMIT (0x00000010) is set, the memory pages are commited.

If PAG_FREE (0x00004000) is set, the memory pages are free.

If PAG_SHARED (0x00002000) is set, the memory pages queried is in a shared memory block. Otherwise it's in a private memory block.

If PAG_BASE (0x00010000) is set, the first page specified is the base of a memory object.

Access protection

If PAG_EXECUTE (0x00000004) is set, execute access to the memory pages are allowed.

If PAG_WRITE (0x00000002) is set, write access to the memory pages are allowed.

If PAG_EXECUTE (0x00000001) is set, read access to the memory pages are allowed.

If PAG_GUARD (0x00000008) is set, access to the memory pages will cause a guard page exception to be raised in the process.

Returns

APIRET rc

The following values can be returned

0 NO_ERROR
87 ERROR_INVALID_PARAMETER
95 ERROR_INTERRUPT
487 ERROR_INVALID_ADDRESS

Usage Explanation

Within the virtual address space of a process DosQueryMem can be used to determine the allocation attributes and access protection of a range of pages. This is the only memory management function that does not require the pages to be entirely contained within an allocated memory block.

DosQueryMem will take the allocation attribute and access protection of the first memory page in the specified region, and from there search the following memory pages until it finds one that has a nonmatching set of attributes, the specifed region is fully searched, or it finds the first memory page in another memory block. DosQueryMem will then return the size in bytes of the pages that had the same attributes as the first page. It will also return the attributes themselves, and an error code.

If the returned allocation attributes does not contain PAG_COMMIT or PAG_FREE it is considered to be reserved. This will also make the access protection returned the same as when the memory block was allocated into the address space of the process.

Sample Code

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

PVOID BaseAddress;
      /* A pointer to the memory which we are querying.     */
      /* For this example we assume that the memory has     */
      /* already been allocated, and that the address of it */
      /* is stored in this pointer.                         */

ULONG RegionSize;
      /* When we call DosQueryMem this will contain the */
      /* size of the memory we want to query. Upon      */
      /* return it will hold the size actually queried. */

ULONG Flags;
      /* This variable will receive the attribute set of the */
      /* queried memory.                                     */

APIRET rc;
      /* Just for taking care of the return code. */

RegionSize = 8192;
      /* We wish to query 2 pages of memory. */

rc = DosQueryMem( BaseAddress, &RegionSize, &Flags);

/* RegionSize will now have the value of 4096 or 8192, depending      */
/* on if the second page had attributes matching the first memory     */
/* page or not. If not, DosQueryMem will have stopped its search      */
/* after the first page and returned 4096, otherwise it returns 8192. */

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

See Also