FsRtlCreateSectionForDataScan function (ntifs.h)

Article
11/04/2022

The FsRtlCreateSectionForDataScan routine creates a section object. Use this routine with extreme caution. (See the following Remarks section.)

Syntax

NTSTATUS FsRtlCreateSectionForDataScan(
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize,
  [in]            PFILE_OBJECT       FileObject,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags
);

Parameters

[out] SectionHandle

Pointer to a caller-allocated variable that receives an opaque handle to the section object.

[out] SectionObject

Pointer to a caller-allocated variable that receives an opaque pointer to the section object.

[out, optional] SectionFileSize

Pointer to a caller-allocated variable that receives the size, in bytes, of the file at the time the section object was created. This parameter is optional and can be NULL.

[in] FileObject

File object for an open file. The section object will be backed by the specified file. This parameter is required and cannot be NULL.

[in] DesiredAccess

Specifies the desired access for the section object as one or more of the following ACCESS_MASK flags.

DesiredAccess flag	Allows caller to
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 actions defined by the previous flags as well as that defined by STANDARD_RIGHTS_REQUIRED. (For more information about STANDARD_RIGHTS_REQUIRED, see ACCESS_MASK.)

[in, optional] ObjectAttributes

Pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use the InitializeObjectAttributes macro to initialize this structure. Because FsRtlCreateSectionForDataScan inserts this object into the process handle table, the caller must specify the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

[in, optional] MaximumSize

This parameter is reserved for future use.

[in] SectionPageProtection

Specifies the protection to place on each page in the section. Specify one of the following values. This parameter is required and cannot be zero.

Flag	Meaning
PAGE_READONLY	Enables read-only access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.

[in] AllocationAttributes

Bitmasks of the SEC_XXX flags determine the allocation attributes of the section. Specify one or more of the following values. This parameter is required and cannot be zero.

Flag	Meaning
SEC_COMMIT	Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting. Note that this flag is required and cannot be omitted.
SEC_FILE	The file specified by the FileObject parameter is a mapped file.

[in] Flags

This parameter is reserved for future use.

Return value

FsRtlCreateSectionForDataScan returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return code	Description
STATUS_END_OF_FILE	The size of the file specified by the FileObject parameter is zero. This is an error code.
STATUS_FILE_LOCK_CONFLICT	The file specified by the FileObject parameter is locked. This is an error code.
STATUS_INSUFFICIENT_RESOURCES	FsRtlCreateSectionForDataScan encountered a pool allocation failure. This is an error code.
STATUS_INVALID_FILE_FOR_SECTION	The file specified by the FileObject parameter does not support sections. This is an error code.
STATUS_INVALID_PARAMETER_8	The value specified for the SectionPageProtection parameter is invalid. This is an error code.
STATUS_INVALID_PARAMETER_9	The caller specified an invalid value for the AllocationAttributes parameter. This is an error code.
STATUS_PRIVILEGE_NOT_HELD	The caller did not have the required privilege to create a section object with the access specified in the DesiredAccess parameter. This is an error code.

Remarks

Important The FsRtlCreateSectionForDataScan routine should only be used in cases where a handle to the file object specified in the FileObject parameter has not yet been created (typically while processing a post-create operation). If the driver has a handle to the file object or can obtain a handle to the file object, the driver should use the ZwCreateSection routine instead.

Once the section object created by this routine is no longer necessary, be sure to close the section object's handle (SectionHandle) by calling the ZwClose routine and dereference the section object itself (SectionObject) by calling the ObDereferenceObject routine.

For more information on creating mapped sections and views of memory, see Section Objects and Views. Also see the documentation for the CreateFileMapping routine in the Microsoft Windows SDK.

Requirements

Requirement	Value
Minimum supported client	Update Rollup for Windows 2000 Service Pack 4 (SP4); Filter Manager Rollup for Windows XP Service Pack 2 (SP2).
Minimum supported server	Microsoft Windows Server 2003 SP1
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL