ZwMapViewOfSection routine

The ZwMapViewOfSection routine maps a view of a section into the virtual address space of a subject process.

Syntax


NTSTATUS ZwMapViewOfSection(
  _In_         HANDLE SectionHandle,
  _In_         HANDLE ProcessHandle,
  _Inout_      PVOID *BaseAddress,
  _In_         ULONG_PTR ZeroBits,
  _In_         SIZE_T CommitSize,
  _Inout_opt_  PLARGE_INTEGER SectionOffset,
  _Inout_      PSIZE_T ViewSize,
  _In_         SECTION_INHERIT InheritDisposition,
  _In_         ULONG AllocationType,
  _In_         ULONG Win32Protect
);

Parameters

SectionHandle [in]

Handle to a section object. This handle is created by a successful call to ZwCreateSection or ZwOpenSection.

ProcessHandle [in]

Handle to the object that represents the process that the view should be mapped into. Use the ZwCurrentProcess macro to specify the current process. The handle must have been opened with PROCESS_VM_OPERATION access (described in the Microsoft Windows SDK documentation).

BaseAddress [in, out]

Pointer to a variable that receives the base address of the view. If the value of this parameter is not NULL, the view is allocated starting at the specified virtual address rounded down to the next 64-kilobyte address boundary.

ZeroBits [in]

Specifies the number of high-order address bits that must be zero in the base address of the section view. The value of this parameter must be less than 21 and is used only if BaseAddress is NULL—in other words, when the caller allows the system to determine where to allocate the view.

CommitSize [in]

Specifies the size, in bytes, of the initially committed region of the view. CommitSize is meaningful only for page-file backed sections and is rounded up to the nearest multiple of PAGE_SIZE. (For sections that map files, both the data and the image are committed at section-creation time.)

SectionOffset [in, out, optional]

A pointer to a variable that receives the offset, in bytes, from the beginning of the section to the view. If this pointer is not NULL, the offset is rounded down to the next allocation-granularity size boundary.

ViewSize [in, out]

A pointer to a SIZE_T variable. If the initial value of this variable is zero, ZwMapViewOfSection maps a view of the section that starts at SectionOffset and continues to the end of the section. Otherwise, the initial value specifies the view's size, in bytes. ZwMapViewOfSection always rounds this value up to the nearest multiple of PAGE_SIZE before mapping the view.

On return, the value receives the actual size, in bytes, of the view.

InheritDisposition [in]

Specifies how the view is to be shared with child processes. The possible values are:

ViewShare

The view will be mapped into any child processes that are created in the future.

ViewUnmap

The view will not be mapped into child processes.

Drivers should typically specify ViewUnmap for this parameter.

AllocationType [in]

Specifies a set of flags that describes the type of allocation to be performed for the specified region of pages. The valid flags are MEM_LARGE_PAGES, MEM_RESERVE, and MEM_TOP_DOWN. Although MEM_COMMIT is not allowed, it is implied unless MEM_RESERVE is specified. For more information about the MEM_XXX flags, see the description of the VirtualAlloc routine.

Win32Protect [in]

Specifies the type of protection for the region of initially committed pages. Device and intermediate drivers should set this value to PAGE_READWRITE.

Return value

ZwMapViewOfSection returns an NTSTATUS value. Possible return values include the following:

Return codeDescription
STATUS_SUCCESS

The routine successfully performed the requested operation.

STATUS_CONFLICTING_ADDRESSES

The specified address range conflicts with an address range already reserved, or the specified cache attribute type conflicts with the address range's existing cache attribute. For example, if the memory being mapped lies within a large page that is already mapped as fully cached, then it is illegal to request to map this memory as noncached or write combined.

STATUS_INVALID_PAGE_PROTECTION

The value specified for the Protect parameter is invalid.

STATUS_SECTION_PROTECTION

The value specified for the AllocationType parameter is incompatible with the protection type specified when the section was created.

 

Remarks

Several different views of a section can be concurrently mapped into the virtual address space of one or more processes.

If the specified section does not exist or the access requested is not allowed, ZwMapViewOfSection returns an error.

Do not use ZwMapViewOfSection to map a memory range from \Device\PhysicalMemory into user mode—unless your driver has directly allocated the memory range through MmAllocatePagesForMdl or another method guaranteeing that no other system component has mapped the same memory range with a different MEMORY_CACHING_TYPE value.

User applications cannot access \Device\PhysicalMemory directly starting with Windows Server 2003 with Service Pack 1 (SP1) and can access it only if the driver passes a handle to the application.

For more information about section objects, see Section Objects and Views.

Note  If the call to this function occurs in user mode, you should use the name "NtMapViewOfSection" instead of "ZwMapViewOfSection".

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

MEMORY_CACHING_TYPE
MmAllocatePagesForMdl
VirtualAlloc
ZwCurrentProcess
ZwOpenSection
ZwUnmapViewOfSection

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft