NtCreateSectionEx-Funktion (ntifs.h)

Artikel
08/07/2023

NtCreateSectionEx erstellt ein Abschnittsobjekt** 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 es sich tatsächlich um einen AWE-Abschnitt (Address Windowing Extensions) handelt.

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 auf 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 alle folgenden Zugriffsrechte angeben, die spezifisch für Abschnittsobjekte sind:

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

[in, optional] ObjectAttributes

Zeiger 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 er das attribut OBJ_KERNEL_HANDLE festlegen, wenn initializeObjectAttributes aufgerufen wird.

[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. Wenn der Abschnitt von der Auslagerungsdatei unterstützt wird, gibt MaximumSize die tatsächliche Größe des Abschnitts an. Wenn der Abschnitt von einer gewöhnlichen 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 bestimmt. 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 FileHandleNULL 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 zeigt.

Rückgabewert

NtCreateSectionEx gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden NTSTATUS-Fehlercode bei Einem Fehler zurück. Mögliche Fehler status Codes:

Rückgabecode	Beschreibung
STATUS_FILE_LOCK_CONFLICT	Die durch den FileHandle-Parameter angegebene Datei ist gesperrt.
STATUS_INVALID_FILE_FOR_SECTION	Die von 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 von FileHandle angegebenen Datei ist null, und MaximumSize ist 0.
STATUS_SECTION_TOO_BIG	Der Wert von MaximumSize ist zu groß. Dies tritt auf, wenn MaximumSize entweder größer als das systemdefinierte Maximum für Abschnitte ist, oder wenn MaximumSize größer als die angegebene Datei ist und der Abschnitt nicht beschreibbar ist.

Hinweise

Sobald das Handle, auf das sectionHandle verweist, 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 allen von ihr erstellten Handles um private Handles handelt. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen. Weitere Informationen finden Sie unter Objekthandles.

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

Hinweis

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 verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienstroutinen.

ExtendedParameters ist ein stapelbasierter erweiterter Parameter, wenn der bevorzugte NUMA-Knoten angegeben wurde.

Es kann nur eine instance eines erweiterten Parameters angegeben werden.

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