NtCreateTransaction - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTTMAPI_H
/**
* Creates a KTM transaction to group operations by participating resource managers. This is not
* NtCreateRegistryTransaction's registry-only object type. The ntoskrnl entry forwards to tm.sys;
* ownership/outcome must be managed separately.
*
* \param TransactionHandle Required output receiving a caller-owned handle on success. Close with NtClose.
* Last transaction-handle close before commit rolls back the active transaction; closing a participating key
* handle is not a commit.
* \param DesiredAccess Nonzero requested rights. Query uses 0x1, set uses 0x2, enlistment uses 0x4, commit
* uses 0x8 and rollback uses 0x10. The synchronous commit/rollback entries additionally require SYNCHRONIZE
* (0x100000).
* \param ObjectAttributes Optional Object Manager attributes/security, or NULL.
* \param Uow Optional GUID; NULL requests an automatically generated UOW identifier. Query
* TransactionBasicInformation to obtain it for NtOpenTransaction. The native user-mode capture checks a
* supplied GUID for 4-byte alignment.
* \param TmHandle Optional manager handle. Use NULL for ordinary user-mode creation: the tm.sys entry rejects
* any non-NULL manager for a user-mode caller. Kernel-mode manager association follows a separate
* access-checked path.
* \param CreateOptions Creation flags. The entry admits only 0 or TRANSACTION_DO_NOT_PROMOTE (0x1); other
* bits return STATUS_INVALID_PARAMETER. Accepted creation options do not imply support for every promotion or
* resource-manager operation.
* \param IsolationLevel Reserved by the public contract; pass 0.
* \param IsolationFlags Reserved by the public contract; pass 0.
* \param Timeout Optional transaction expiration time, not a timeout on this creation call. Units are 100 ns:
* negative is relative, positive is absolute. NULL or 0 requests no deadline at creation. If the transaction
* is still active when its deadline expires, KTM initiates rollback.
* \param Description Optional counted Unicode description copied by KTM. The create path accepts at most 128
* bytes (64 WCHARs) in Length and rejects 130 bytes. Exclude any terminator from the counted byte length.
* \return STATUS_SUCCESS or an NTSTATUS failure. Initialize outputs and check status; native capture need not
* clear a failed result and WoW64 copyback differs.
* \remarks Keep key/transaction handles and transaction completion separate. KTM commit/rollback with Wait =
* FALSE can return STATUS_PENDING; that is not proof of a completed outcome. Resource-manager enlistment,
* recovery, and concurrent completion have separate contracts.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwcreatetransaction
* \remarks On the tm.sys entry, a user-mode caller must pass NULL for TmHandle; a non-NULL handle returns
* STATUS_INVALID_PARAMETER even when it refers to a valid owned transaction manager. The kernel-mode path has
* separate support for an explicit manager. Resource-manager ownership is selected separately when creating
* an enlistment.
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtCreateTransaction(
_Out_ PHANDLE TransactionHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_opt_ LPGUID Uow,
_In_opt_ HANDLE TmHandle,
_In_opt_ ULONG CreateOptions,
_In_opt_ ULONG IsolationLevel,
_In_opt_ ULONG IsolationFlags,
_In_opt_ PLARGE_INTEGER Timeout,
_In_opt_ PCUNICODE_STRING Description
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwCreateTransaction(
_Out_ PHANDLE TransactionHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_opt_ LPGUID Uow,
_In_opt_ HANDLE TmHandle,
_In_opt_ ULONG CreateOptions,
_In_opt_ ULONG IsolationLevel,
_In_opt_ ULONG IsolationFlags,
_In_opt_ PLARGE_INTEGER Timeout,
_In_opt_ PCUNICODE_STRING Description
);
View code on GitHub// wdm.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
[out] PHANDLE TransactionHandle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] LPGUID Uow,
[in, optional] HANDLE TmHandle,
[in, optional] ULONG CreateOptions,
[in, optional] ULONG IsolationLevel,
[in, optional] ULONG IsolationFlags,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PUNICODE_STRING Description
);
View the official Windows Driver Kit DDI reference// wdm.h
NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
[out] PHANDLE TransactionHandle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] LPGUID Uow,
[in, optional] HANDLE TmHandle,
[in, optional] ULONG CreateOptions,
[in, optional] ULONG IsolationLevel,
[in, optional] ULONG IsolationFlags,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PUNICODE_STRING Description
);
View the official Windows Driver Kit DDI referenceThe ZwCreateTransaction routine creates a transaction object.
TransactionHandle [out]A pointer to a caller-allocated variable that receives a handle to the new transaction object, if the call to ZwCreateTransaction succeeds.
DesiredAccess [in]An ACCESS_MASK value that specifies the caller's requested access to the transaction 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 flags for transaction objects.
| Access mask | Allows the caller to |
|---|---|
| TRANSACTION_COMMIT | Commit the transaction (see ZwCommitTransaction). |
| TRANSACTION_ENLIST | Create an enlistment for the transaction (see ZwCreateEnlistment). |
| TRANSACTION_PROPAGATE | Do not use. |
| TRANSACTION_QUERY_INFORMATION | Obtain information about the transaction (see ZwQueryInformationTransaction). |
| TRANSACTION_ROLLBACK | Roll back the transaction (see ZwRollbackTransaction). |
| TRANSACTION_SET_INFORMATION | Set information for the transaction (see ZwSetInformationTransaction). |
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 |
|---|---|
| TRANSACTION_GENERIC_READ | STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION, and SYNCHRONIZE |
| TRANSACTION_GENERIC_WRITE | STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT, and SYNCHRONIZE |
| TRANSACTION_GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK, and SYNCHRONIZE |
| TRANSACTION_ALL_ACCESS | STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE, and TRANSACTION_GENERIC_EXECUTE |
| TRANSACTION_RESOURCE_MANAGER_RIGHTS | STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, and SYNCHRONIZE |
Typically, a resource manager specifies TRANSACTION_RESOURCE_MANAGER_RIGHTS.
The DesiredAccess value cannot be zero.
ObjectAttributes [in, optional]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.
Uow [in, optional]A pointer to a GUID that KTM uses as the new transaction object's unit of work (UOW) identifier. This parameter is optional and can be NULL. If this parameter is NULL, KTM generates a GUID and assigns it to the transaction object. For more information, see the following Remarks section.
TmHandle [in, optional]A handle to a transaction manager object that was obtained by a previous call to ZwCreateTransactionManager or ZwOpenTransactionManager. KTM assigns the new transaction object to the specified transaction manager object. If this parameter is NULL, KTM assigns the new transaction object to a transaction manager later, when a resource manager creates an enlistment for the transaction.
CreateOptions [in, optional]Optional object creation flags. The following table contains the available flags, which are defined in Ktmtypes.h.
| Option flag | Meaning |
|---|---|
| TRANSACTION_DO_NOT_PROMOTE | Reserved for future use. |
IsolationLevel [in, optional]Reserved for future use. Callers must set this parameter to zero.
IsolationFlags [in, optional]Reserved for future use. Callers should set this parameter to zero.
Timeout [in, optional]A pointer to a time-out value. If the transaction has not been committed by the time specified by this parameter, KTM rolls back the transaction. The time-out value is expressed in system time units (100-nanosecond intervals), and can specify either an absolute time or a relative time. If the value pointed to by Timeout is negative, the expiration time is relative to the current system time. Otherwise, the expiration time is absolute. This pointer is optional and can be NULL if you do not want the transaction to have a time-out value. If Timeout = NULL or *Timeout = 0, the transaction never times out. (You can also use ZwSetInformationTransaction to set a time-out value.)
Description [in, optional]A pointer to a caller-supplied UNICODE_STRING structure that contains a NULL-terminated string. The string provides a description of the transaction. KTM stores a copy of the string and includes the string in messages that it writes to the log stream. The maximum string length is MAX_TRANSACTION_DESCRIPTION_LENGTH. This parameter is optional and can be NULL.
ZwCreateTransaction returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:
| Return code | Description |
|---|---|
| STATUS_INVALID_PARAMETER | The CreateOptions parameter contains an invalid flag, the DesiredAccess parameter is zero, or the Description parameter's string is too long. |
| STATUS_INSUFFICIENT_RESOURCES | KTM could not allocate system resources (typically memory). |
| 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_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.
The caller can use the Uow parameter to specify a UOW identifier for the transaction object. If the caller does not specify a UOW identifier, KTM generates a GUID and assigns it to the transaction object. The caller can later obtain this GUID by calling ZwQueryInformationTransaction.
Typically, you should let KTM generate a GUID for the transaction object, unless your component communicates with another TPS component that has already generated a UOW identifier for the transaction.
To close the transaction handle, the component that called ZwCreateTransaction must call ZwClose. If the last transaction handle closes before any component calls ZwCommitTransaction for the transaction, KTM rolls back the transaction.
For more information about how transaction clients should use ZwCreateTransaction, see Creating a Transactional Client.
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.
Using Nt and Zw Versions of the Native System Services Routines
The ZwCreateTransaction routine creates a transaction object.
TransactionHandle [out]A pointer to a caller-allocated variable that receives a handle to the new transaction object, if the call to ZwCreateTransaction succeeds.
DesiredAccess [in]An ACCESS_MASK value that specifies the caller's requested access to the transaction 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 flags for transaction objects.
| Access mask | Allows the caller to |
|---|---|
| TRANSACTION_COMMIT | Commit the transaction (see ZwCommitTransaction). |
| TRANSACTION_ENLIST | Create an enlistment for the transaction (see ZwCreateEnlistment). |
| TRANSACTION_PROPAGATE | Do not use. |
| TRANSACTION_QUERY_INFORMATION | Obtain information about the transaction (see ZwQueryInformationTransaction). |
| TRANSACTION_ROLLBACK | Roll back the transaction (see ZwRollbackTransaction). |
| TRANSACTION_SET_INFORMATION | Set information for the transaction (see ZwSetInformationTransaction). |
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 |
|---|---|
| TRANSACTION_GENERIC_READ | STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION, and SYNCHRONIZE |
| TRANSACTION_GENERIC_WRITE | STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT, and SYNCHRONIZE |
| TRANSACTION_GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK, and SYNCHRONIZE |
| TRANSACTION_ALL_ACCESS | STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE, and TRANSACTION_GENERIC_EXECUTE |
| TRANSACTION_RESOURCE_MANAGER_RIGHTS | STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, and SYNCHRONIZE |
Typically, a resource manager specifies TRANSACTION_RESOURCE_MANAGER_RIGHTS.
The DesiredAccess value cannot be zero.
ObjectAttributes [in, optional]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.
Uow [in, optional]A pointer to a GUID that KTM uses as the new transaction object's unit of work (UOW) identifier. This parameter is optional and can be NULL. If this parameter is NULL, KTM generates a GUID and assigns it to the transaction object. For more information, see the following Remarks section.
TmHandle [in, optional]A handle to a transaction manager object that was obtained by a previous call to ZwCreateTransactionManager or ZwOpenTransactionManager. KTM assigns the new transaction object to the specified transaction manager object. If this parameter is NULL, KTM assigns the new transaction object to a transaction manager later, when a resource manager creates an enlistment for the transaction.
CreateOptions [in, optional]Optional object creation flags. The following table contains the available flags, which are defined in Ktmtypes.h.
| Option flag | Meaning |
|---|---|
| TRANSACTION_DO_NOT_PROMOTE | Reserved for future use. |
IsolationLevel [in, optional]Reserved for future use. Callers must set this parameter to zero.
IsolationFlags [in, optional]Reserved for future use. Callers should set this parameter to zero.
Timeout [in, optional]A pointer to a time-out value. If the transaction has not been committed by the time specified by this parameter, KTM rolls back the transaction. The time-out value is expressed in system time units (100-nanosecond intervals), and can specify either an absolute time or a relative time. If the value pointed to by Timeout is negative, the expiration time is relative to the current system time. Otherwise, the expiration time is absolute. This pointer is optional and can be NULL if you do not want the transaction to have a time-out value. If Timeout = NULL or *Timeout = 0, the transaction never times out. (You can also use ZwSetInformationTransaction to set a time-out value.)
Description [in, optional]A pointer to a caller-supplied UNICODE_STRING structure that contains a NULL-terminated string. The string provides a description of the transaction. KTM stores a copy of the string and includes the string in messages that it writes to the log stream. The maximum string length is MAX_TRANSACTION_DESCRIPTION_LENGTH. This parameter is optional and can be NULL.
ZwCreateTransaction returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:
| Return code | Description |
|---|---|
| STATUS_INVALID_PARAMETER | The CreateOptions parameter contains an invalid flag, the DesiredAccess parameter is zero, or the Description parameter's string is too long. |
| STATUS_INSUFFICIENT_RESOURCES | KTM could not allocate system resources (typically memory). |
| 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_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.
The caller can use the Uow parameter to specify a UOW identifier for the transaction object. If the caller does not specify a UOW identifier, KTM generates a GUID and assigns it to the transaction object. The caller can later obtain this GUID by calling ZwQueryInformationTransaction.
Typically, you should let KTM generate a GUID for the transaction object, unless your component communicates with another TPS component that has already generated a UOW identifier for the transaction.
To close the transaction handle, the component that called ZwCreateTransaction must call ZwClose. If the last transaction handle closes before any component calls ZwCommitTransaction for the transaction, KTM rolls back the transaction.
For more information about how transaction clients should use ZwCreateTransaction, see Creating a Transactional Client.
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.
Using Nt and Zw Versions of the Native System Services Routines