NtCreateSection function (ntifs.h)
The NtCreateSection routine creates a section object.
Syntax
__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
);
Parameters
[out] SectionHandle
Pointer to a HANDLE variable that receives a handle to the section object.
[in] DesiredAccess
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. |
[in, optional] ObjectAttributes
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.
[in, optional] MaximumSize
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.
[in] SectionPageProtection
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.
[in] AllocationAttributes
Specifies a bitmask of SEC_XXX flags that determines the allocation attributes of the section. For a description of these flags, see CreateFileMapping.
[in, optional] 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 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 NtXxx and ZwXxx 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 NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 |
| Target Platform | Universal |
| Header | ntifs.h (include Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |