NtCreateTransactionManager function (wdm.h)

Article
03/11/2022

The ZwCreateTransactionManager routine creates a new transaction manager object.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Parameters

[out] TmHandle

A pointer to a caller-allocated variable that receives a handle to the new transaction manager object.

[in] DesiredAccess

An ACCESS_MASK value that specifies the caller's requested access to the transaction manager object. In addition to the access rights that are defined for all kinds of objects (see ACCESS_MASK), the caller can specify any of the following access right flags for transaction manager objects.

ACCESS_MASK flag	Allows the caller to
TRANSACTIONMANAGER_CREATE_RM	Create a resource manager (see ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Obtain information about the transaction manager (see ZwQueryInformationTransactionManager and ZwEnumerateTransactionObject). Also required for ZwOpenResourceManager, ZwCreateTransaction, and ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Recover the transaction manager (see ZwRecoverTransactionManager and ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Not used.
TRANSACTIONMANAGER_SET_INFORMATION	Not used.

Alternatively, you can specify one or more of the following ACCESS_MASK bitmaps. These bitmaps combine the flags from the previous table with the STANDARD_RIGHTS_XXX flags that are described on the ACCESS_MASK reference page. You can also combine these bitmaps with additional flags from the preceding table. The following table shows how the bitmaps correspond to specific access rights.

Rights bitmap	Set of specific access rights
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ and TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME, and TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE, and TRANSACTIONMANAGER_GENERIC_EXECUTE

[in, optional] ObjectAttributes

A pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use the InitializeObjectAttributes routine 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. This parameter is optional and can be NULL.

[in, optional] LogFileName

A pointer to a UNICODE_STRING structure that contains the path and file name of a CLFS log file stream to be associated with the transaction manager object. This parameter must be NULL if the CreateOptions parameter is TRANSACTION_MANAGER_VOLATILE. Otherwise, this parameter must be non-NULL. For more information, see the following Remarks section.

[in, optional] CreateOptions

Optional object creation flags. The following table contains the available flags, which are defined in Ktmtypes.h.

Option flag	Meaning
TRANSACTION_MANAGER_VOLATILE	The transaction manager object will be volatile. Therefore, it will not use a log file.
TRANSACTION_MANAGER_COMMIT_DEFAULT	For internal use only.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	For internal use only.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	For internal use only.
TRANSACTION_MANAGER_COMMIT_LOWEST	For internal use only.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	For internal use only.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	For internal use only.

[in, optional] CommitStrength

Reserved for future use. This parameter must be zero.

Return value

ZwCreateTransactionManager returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	The value of an input parameter is invalid.
STATUS_INSUFFICIENT_RESOURCES	KTM could not allocate system resources (typically memory).
STATUS_LOG_CORRUPTION_DETECTED	KTM encountered an error while creating or opening the log file.
STATUS_INVALID_ACL	A security descriptor contains an invalid access control list (ACL).
STATUS_INVALID_SID	A security descriptor contains an invalid security identifier (SID).
STATUS_OBJECT_NAME_EXISTS	The object name that the ObjectAttributes parameter specifies already exists.
STATUS_OBJECT_NAME_COLLISION	The operating system detected a duplicate object name. The error might indicate that the log stream is already being used.
STATUS_OBJECT_NAME_INVALID	The object name that the ObjectAttributes parameter specifies is invalid.
STATUS_ACCESS_DENIED	The value of the DesiredAccess parameter is invalid.

The routine might return other NTSTATUS values.

Remarks

If the log file stream that the LogFileName parameter specifies does not exist, KTM calls CLFS to create the stream. If the stream already exists, KTM calls CLFS to open the stream.

Your TPS component must call ZwRecoverTransactionManager after it has called ZwCreateTransactionManager

If your TPS component specifies the TRANSACTION_MANAGER_VOLATILE flag in the CreateOptions parameter, all resource managers that are associated with the transaction manager object must specify the RESOURCE_MANAGER_VOLATILE flag when they call ZwCreateResourceManager.

A TPS component that calls ZwCreateTransactionManager must eventually call ZwClose to close the object handle.

For more information about how use ZwCreateTransactionManager, see Creating a Resource Manager.

NtCreateTransactionManager and ZwCreateTransactionManager are two versions of the same Windows Native System Services routine.

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	Available in Windows Vista and later operating system versions.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs, PowerIrpDDis