NtCreateSection - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTMMAPI_H
//
// Sections
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * The NtCreateSection routine creates a section object.
 *
 * \param SectionHandle Pointer to a variable that receives a handle to the section object.
 * \param DesiredAccess The access mask that specifies the requested access to the section object.
 * \param ObjectAttributes Pointer to the base virtual address of the view to unmap. This value can be any virtual address within the view.
 * \param MaximumSize The maximum size, in bytes, of the section. The actual size when backed by the paging file, or the maximum the file can be extended or mapped when backed by an ordinary file.
 * \param SectionPageProtection Specifies the protection to place on each page in the section.
 * \param AllocationAttributes A bitmask of SEC_XXX flags that determines the allocation attributes of the section.
 * \param FileHandle Optionally specifies a handle for an open file object. If the value of FileHandle is NULL, the section is backed by the paging file. Otherwise, the section is backed by the specified file.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwcreatesection
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtCreateSection(
    _Out_ PHANDLE SectionHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_opt_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _In_opt_ PLARGE_INTEGER MaximumSize,
    _In_ ULONG SectionPageProtection,
    _In_ ULONG AllocationAttributes,
    _In_opt_ HANDLE FileHandle
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwCreateSection(
    _Out_ PHANDLE SectionHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_opt_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _In_opt_ PLARGE_INTEGER MaximumSize,
    _In_ ULONG SectionPageProtection,
    _In_ ULONG AllocationAttributes,
    _In_opt_ HANDLE FileHandle
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateSection(
  [out]          PHANDLE            SectionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PLARGE_INTEGER     MaximumSize,
  [in]           ULONG              SectionPageProtection,
  [in]           ULONG              AllocationAttributes,
  [in, optional] HANDLE             FileHandle
);
View the official Windows Driver Kit DDI reference
// wdm.h

NTSYSAPI NTSTATUS ZwCreateSection(
  [out]          PHANDLE            SectionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PLARGE_INTEGER     MaximumSize,
  [in]           ULONG              SectionPageProtection,
  [in]           ULONG              AllocationAttributes,
  [in, optional] HANDLE             FileHandle
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-ntcreatesection)

NtCreateSection function

Description

The NtCreateSection routine creates a section object.

Parameters

SectionHandle [out]

Pointer to a HANDLE variable that receives a handle to the section object.

DesiredAccess [in]

Specifies an ACCESS_MASK value that determines the requested access to the object. In addition to the access rights that are defined for all types of objects, the caller can specify any of the following access rights, which are specific to section objects:

DesiredAccess flag Allows caller to do this
SECTION_EXTEND_SIZE Dynamically extend the size of the section.
SECTION_MAP_EXECUTE Execute views of the section.
SECTION_MAP_READ Read views of the section.
SECTION_MAP_WRITE Write views of the section.
SECTION_QUERY Query the section object for information about the section. Drivers should set this flag.
SECTION_ALL_ACCESS All of the previous flags combined with STANDARD_RIGHTS_REQUIRED.

ObjectAttributes [in, optional]

Pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use InitializeObjectAttributes to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

MaximumSize [in, optional]

Specifies the maximum size, in bytes, of the section. NtCreateSection rounds this value up to the nearest multiple of PAGE_SIZE. If the section is backed by the paging file, MaximumSize specifies the actual size of the section. If the section is backed by an ordinary file, MaximumSize specifies the maximum size that the file can be extended or mapped to.

SectionPageProtection [in]

Specifies the protection to place on each page in the section. Use one of the following four values: PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE, or PAGE_WRITECOPY. For a description of these values, see CreateFileMapping.

AllocationAttributes [in]

Specifies a bitmask of SEC_XXX flags that determines the allocation attributes of the section. For a description of these flags, see CreateFileMapping.

FileHandle [in, optional]

Optionally specifies a handle for an open file object. If the value of FileHandle is NULL, the section is backed by the paging file. Otherwise, the section is backed by the specified file.

Return value

NtCreateSection returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. Possible error status codes include the following:

Return code Description
STATUS_FILE_LOCK_CONFLICT The file specified by the FileHandle parameter is locked.
STATUS_INVALID_FILE_FOR_SECTION The file specified by FileHandle does not support sections.
STATUS_INVALID_PAGE_PROTECTION The value specified for the SectionPageProtection parameter is invalid.
STATUS_MAPPED_FILE_SIZE_ZERO The size of the file specified by FileHandle is zero, and MaximumSize is zero.
STATUS_SECTION_TOO_BIG The value of MaximumSize is too big. This occurs when either MaximumSize is greater than the system-defined maximum for sections, or if MaximumSize is greater than the specified file and the section is not writable.

Remarks

Once the handle pointed to by SectionHandle is no longer in use, the driver must call NtClose to close it.

If the caller is not running in a system thread context, it must ensure that any handles it creates are private handles. Otherwise, the handle can be accessed by the process in whose context the driver is running. For more information, see Object Handles.

For more information, see Managing Memory Sections.

[!NOTE] If the call to this function occurs in user mode, you should use the name "NtCreateSection" instead of "ZwCreateSection".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

CreateFileMapping

InitializeObjectAttributes

ZwClose

ZwMapViewOfSection

ZwOpenSection

ZwUnmapViewOfSection

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-wdm-zwcreatesection)

Description

The ZwCreateSection routine creates a section object.

Parameters

SectionHandle [out]

Pointer to a HANDLE variable that receives a handle to the section object.

DesiredAccess [in]

Specifies an ACCESS_MASK value that determines the requested access to the object. In addition to the access rights that are defined for all types of objects (see ACCESS_MASK), the caller can specify any of the following access rights, which are specific to section objects:

DesiredAccess flag Allows caller to do this
SECTION_EXTEND_SIZE Dynamically extend the size of the section.
SECTION_MAP_EXECUTE Execute views of the section.
SECTION_MAP_READ Read views of the section.
SECTION_MAP_WRITE Write views of the section.
SECTION_QUERY Query the section object for information about the section. Drivers should set this flag.
SECTION_ALL_ACCESS All of the previous flags combined with STANDARD_RIGHTS_REQUIRED.

ObjectAttributes [in, optional]

Pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use InitializeObjectAttributes to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

MaximumSize [in, optional]

Specifies the maximum size, in bytes, of the section. ZwCreateSection rounds this value up to the nearest multiple of PAGE_SIZE. If the section is backed by the paging file, MaximumSize specifies the actual size of the section. If the section is backed by an ordinary file, MaximumSize specifies the maximum size that the file can be extended or mapped to.

SectionPageProtection [in]

Specifies the protection to place on each page in the section. Use one of the following four values: PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE, or PAGE_WRITECOPY. For a description of these values, see CreateFileMapping.

AllocationAttributes [in]

Specifies a bitmask of SEC_XXX flags that determines the allocation attributes of the section. For a description of these flags, see CreateFileMapping.

FileHandle [in, optional]

Optionally specifies a handle for an open file object. If the value of FileHandle is NULL, the section is backed by the paging file. Otherwise, the section is backed by the specified file.

Return value

ZwCreateSection returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. Possible error status codes include the following:

Return code Description
STATUS_FILE_LOCK_CONFLICT The file specified by the FileHandle parameter is locked.
STATUS_INVALID_FILE_FOR_SECTION The file specified by FileHandle does not support sections.
STATUS_INVALID_PAGE_PROTECTION The value specified for the SectionPageProtection parameter is invalid.
STATUS_MAPPED_FILE_SIZE_ZERO The size of the file specified by FileHandle is zero, and MaximumSize is zero.
STATUS_SECTION_TOO_BIG The value of MaximumSize is too big. This occurs when either MaximumSize is greater than the system-defined maximum for sections, or if MaximumSize is greater than the specified file and the section is not writable.

Remarks

Once the handle pointed to by SectionHandle is no longer in use, the driver must call ZwClose to close it.

If the caller is not running in a system thread context, it must ensure that any handles it creates are private handles. Otherwise, the handle can be accessed by the process in whose context the driver is running. For more information, see Object Handles.

For more information about setting up mapped sections and views of memory, see Sections and Views.

If the call to this function occurs in user mode, you should use the name "NtCreateSection" instead of "ZwCreateSection".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

CreateFileMapping

InitializeObjectAttributes

ZwClose

ZwMapViewOfSection

ZwOpenSection

ZwUnmapViewOfSection

View the official Windows Driver Kit DDI reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit here and here.

Function NtCreateSection creates Section Object (virtual memory block with associated file).

SectionHandle

Result of call - HANDLE to Section Object.

DesiredAccess

Access mask. Can be combination of:

ObjectAttributes

Pointer to OBJECT_ATTRIBUTES structure contains section name, in Object Namespace format.

MaximumSize

Optionally define maximum size of section. Must be defined when caller create section based on system PageFile.

PageAttributes

Can be one or combination of:

SectionAttributes

Can be one or combination of:

FileHandle

Optionally HANDLE to File Object opened with proper access.

Documented by

See also

Edit description on GitHub