NtCreateSectionEx-Funktion (ntifs.h)

Artikel
02/07/2025

NtCreateSectionEx erstellt ein Section-Objekt** und öffnet ein Handle für das Objekt mit dem angegebenen gewünschten Zugriff. Es handelt sich um eine erweiterte Version von NtCreateSection, die ein Abschnittsobjekt erstellt, indem angegeben wird, dass dies tatsächlich ein Abschnitt mit Adressfenstererweiterungen (Address Windowing Extensions, AWE) ist.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateSectionEx(
  [out]          PHANDLE                 SectionHandle,
  [out]          ACCESS_MASK             DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES      ObjectAttributes,
  [in, optional] PLARGE_INTEGER          MaximumSize,
  [in]           ULONG                   SectionPageProtection,
  [in]           ULONG                   AllocationAttributes,
  [in, optional] HANDLE                  FileHandle,
  [in/out]       PMEM_EXTENDED_PARAMETER ExtendedParameters,
                 ULONG                   ExtendedParameterCount
);

Parameter

[out] SectionHandle

Zeiger auf eine HANDLE-Variable, die ein Handle für das Abschnittsobjekt empfängt.

[out] DesiredAccess

Gibt einen ACCESS_MASK Wert an, der den angeforderten Zugriff auf das Objekt bestimmt. Zusätzlich zu den Zugriffsrechten, die für alle Objekttypen definiert sind, kann der Aufrufer eine der folgenden Zugriffsrechte angeben, die spezifisch für Abschnittsobjekte sind:

DesiredAccess-Kennzeichnung	Ermöglicht dem Aufrufer, dies zu tun
SECTION_EXTEND_SIZE	Dynamisches Erweitern der Größe des Abschnitts.
SECTION_MAP_EXECUTE	Führen Sie Ansichten des Abschnitts aus.
SECTION_MAP_READ	Leseansichten des Abschnitts.
SECTION_MAP_WRITE	Schreibansichten des Abschnitts.
SECTION_QUERY	Fragen Sie das Abschnittsobjekt nach Informationen zum Abschnitt ab. Treiber sollten dieses Kennzeichen festlegen.
SECTION_ALL_ACCESS	Alle vorherigen Flags in Kombination mit STANDARD_RIGHTS_REQUIRED.

[in, optional] ObjectAttributes

Zeigen Sie auf eine OBJECT_ATTRIBUTES Struktur, die den Objektnamen und andere Attribute angibt. Verwenden Sie InitializeObjectAttributes, um diese Struktur zu initialisieren. Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss das attribut OBJ_KERNEL_HANDLE festgelegt werden, wenn er InitializeObjectAttributesaufruft.

[in, optional] MaximumSize

Gibt die maximale Größe des Abschnitts in Bytes an. NtCreateSection rundet diesen Wert auf das nächste Vielfache von PAGE_SIZE auf. Wenn der Abschnitt von der Auslagerungsdatei unterstützt wird, gibt MaximumSize die tatsächliche Größe des Abschnitts an. Wenn der Abschnitt von einer normalen Datei unterstützt wird, gibt MaximumSize die maximale Größe an, der die Datei erweitert oder zugeordnet werden kann.

[in] SectionPageProtection

Gibt den Schutz an, der auf jeder Seite im Abschnitt platziert werden soll. Verwenden Sie einen der folgenden vier Werte: PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE oder PAGE_WRITECOPY. Eine Beschreibung dieser Werte finden Sie unter CreateFileMapping.

[in] AllocationAttributes

Gibt eine Bitmaske von SEC_XXX Flags an, die die Zuordnungsattribute des Abschnitts bestimmen. Eine Beschreibung dieser Flags finden Sie unter CreateFileMapping.

[in, optional] FileHandle

Gibt optional ein Handle für ein geöffnetes Dateiobjekt an. Wenn der Wert von FileHandle-NULL-ist, wird der Abschnitt von der Auslagerungsdatei unterstützt. Andernfalls wird der Abschnitt von der angegebenen Datei unterstützt.

[in/out] ExtendedParameters

Ein Zeiger auf ein Array von MEM_EXTENDED_PARAMETER Strukturen, die die erweiterten Parameter zum Erstellen des Abschnitts enthält.

ExtendedParameterCount

Die Größe des Arrays, auf das ExtendedParameters verweist.

Rückgabewert

NtCreateSectionEx- gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden NTSTATUS-Fehlercode beim Fehler zurück. Mögliche Fehlerstatuscodes sind:

Rückgabecode	Beschreibung
STATUS_FILE_LOCK_CONFLICT	Die vom FileHandle Parameter angegebene Datei ist gesperrt.
STATUS_INVALID_FILE_FOR_SECTION	Die durch FileHandle- angegebene Datei unterstützt keine Abschnitte.
STATUS_INVALID_PAGE_PROTECTION	Der für den SectionPageProtection Parameter angegebene Wert ist ungültig.
STATUS_MAPPED_FILE_SIZE_ZERO	Die Größe der durch FileHandle- angegebenen Datei ist null, und MaximumSize ist Null.
STATUS_SECTION_TOO_BIG	Der Wert von MaximumSize ist zu groß. Dies tritt auf, wenn MaximumSize- größer als das vom System definierte Maximum für Abschnitte ist, oder wenn MaximumSize- größer als die angegebene Datei ist und der Abschnitt nicht schreibbar ist.

Bemerkungen

Sobald der Von SectionHandle- darauf verwiesene Handle nicht mehr verwendet wird, muss der Treiber NtClose- aufrufen, um es zu schließen.

Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss sichergestellt werden, dass es sich bei den erstellten Handles um private Handles handelt. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann. Weitere Informationen finden Sie unter Object Handles.

Weitere Informationen zum Einrichten zugeordneter Abschnitte und Ansichten des Arbeitsspeichers finden Sie unter Abschnitten und Ansichten.

Anmerkung

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtCreateSectionEx" anstelle von "ZwCreateSectionEx" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

ExtendedParameters ist ein stackbasierter erweiterter Parameter, wenn bevorzugter NUMA-Knoten angegeben wurde.

Es kann nur eine Instanz eines erweiterten Parameters angegeben werden.

Konvertieren Sie in eine 1-basierte Numa-Knotennummer, die nachgelagert von dieser API erwartet wird.