NtOpenDirectoryObject - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTOBAPI_H
//
// Directory objects
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)
/**
* Opens an existing directory object.
*
* @param DirectoryHandle A handle to the newly opened directory object.
* @param DesiredAccess An ACCESS_MASK that specifies the requested access to the directory object.
* @param ObjectAttributes The attributes for the directory object.
* @return NTSTATUS Successful or errant status.
* @sa https://learn.microsoft.com/en-us/windows/win32/devnotes/ntopendirectoryobject
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenDirectoryObject(
_Out_ PHANDLE DirectoryHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_ POBJECT_ATTRIBUTES ObjectAttributes
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenDirectoryObject(
_Out_ PHANDLE DirectoryHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_ POBJECT_ATTRIBUTES ObjectAttributes
);
View code on GitHub// ntifs.h
NTSYSAPI NTSTATUS ZwOpenDirectoryObject(
[out] PHANDLE DirectoryHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes
);
View the official Windows Driver Kit DDI referenceNTSTATUS WINAPI NtOpenDirectoryObject(
_Out_ PHANDLE DirectoryHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_ POBJECT_ATTRIBUTES ObjectAttributes
);
View the official Win32 development documentationNo description available.
The ZwOpenDirectoryObject routine opens an existing directory object.
DirectoryHandle [out]Handle for the newly opened directory object.
DesiredAccess [in]An ACCESS_MASK structure specifying the requested types of access being requested for this directory object. A caller can specify one or a combination of the following.
| DesiredAccess Flags | Meaning |
|---|---|
| DIRECTORY_QUERY | Query access to the directory object |
| DIRECTORY_TRAVERSE | Name-lookup access to the directory object |
| DIRECTORY_CREATE_OBJECT | Name-creation access to the directory object |
| DIRECTORY_CREATE_SUBDIRECTORY | Subdirectory-creation access to the directory object |
| DIRECTORY_ALL_ACCESS | All of the preceding rights plus STANDARD_RIGHTS_REQUIRED. |
These requested access types are compared with the object's discretionary access-control list (DACL) to determine which accesses are granted or denied.
ObjectAttributes [in]Specified attributes for the directory object supplied by the caller. This parameter is initialized by calling the InitializeObjectAttributes macro.
ZwOpenDirectoryObject returns STATUS_SUCCESS or an appropriate error status. The most common error status codes include the following:
| Return code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | A temporary buffer required by this routine could not be allocated. |
| STATUS_INVALID_PARAMETER | The specified ObjectAttributes parameter was a NULL pointer, not a valid pointer to an OBJECT_ATTRIBUTES structure, or some of the fields specified in the OBJECT_ATTRIBUTES structure were invalid. |
| STATUS_OBJECT_NAME_INVALID | The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure that was invalid because an empty string was found after the OBJECT_NAME_PATH_SEPARATOR character. |
| STATUS_OBJECT_NAME_NOT_FOUND | The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure that could not be found. |
| STATUS_OBJECT_PATH_NOT_FOUND | The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure with an object path that could not be found. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | The ObjectAttributes parameter did not contain a RootDirectory field, but the ObjectName field in the OBJECT_ATTRIBUTES structure was an empty string or did not contain an OBJECT_NAME_PATH_SEPARATOR character. This indicates incorrect syntax for the object path. |
The ZwOpenDirectoryObject routine throws an exception if the DirectoryHandle parameter is an illegal pointer.
ZwOpenDirectoryObject opens an existing directory object and returns a handle to the object.
The ZwOpenDirectoryObject routine is called after the InitializeObjectAttributes macro is used to initialize specific attributes of the OBJECT_ATTRIBUTES structure for the object to be opened.
A directory object is created using the ZwCreateDirectoryObject routine. Any handle obtained by calling ZwOpenDirectoryObject must eventually be released by calling ZwClose.
For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.
Note If the call to the ZwCreateDirectoryObject function occurs in user mode, you should use the name "NtCreateDirectoryObject" instead of "ZwCreateDirectoryObject".
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.
Using Nt and Zw Versions of the Native System Services Routines
[This function may be altered or unavailable in the future.]
Opens an existing directory object.
DirectoryHandle [out]
A handle to the newly opened directory object.
DesiredAccess [in]
An ACCESS_MASK that specifies the requested access to the directory object. This parameter can be one or more of the following values.
| Value | Meaning |
|---|---|
| DIRECTORY_QUERY 0x0001 |
Query access to the directory object. |
| DIRECTORY_TRAVERSE 0x0002 |
Name-lookup access to the directory object. |
| DIRECTORY_CREATE_OBJECT 0x0004 |
Name-creation access to the directory object. |
| DIRECTORY_CREATE_SUBDIRECTORY 0x0008 |
Subdirectory-creation access to the directory object. |
| DIRECTORY_ALL_ACCESS STANDARD_RIGHTS_REQUIRED | 0xF |
All of the preceding rights plus STANDARD_RIGHTS_REQUIRED. |
ObjectAttributes [in]
The attributes for the directory object. To initialize the OBJECT_ATTRIBUTES structure, use the InitializeObjectAttributes macro. For more information, see the documentation for these items in the documentation for the WDK.
The function returns STATUS_SUCCESS or an error status. The possible status codes include the following.
| Return code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | A temporary buffer required by this function could not be allocated. |
| STATUS_INVALID_PARAMETER | The specified ObjectAttributes parameter was a NULL pointer, not a valid pointer to an OBJECT_ATTRIBUTES structure, or some of the members specified in the OBJECT_ATTRIBUTES structure were not valid. |
| STATUS_OBJECT_NAME_INVALID | The ObjectAttributes parameter contained an ObjectName member in the OBJECT_ATTRIBUTES structure that was not valid because an empty string was found after the OBJECT_NAME_PATH_SEPARATOR character. |
| STATUS_OBJECT_NAME_NOT_FOUND | The ObjectAttributes parameter contained an ObjectName member in the OBJECT_ATTRIBUTES structure that could not be found. |
| STATUS_OBJECT_PATH_NOT_FOUND | The ObjectAttributes parameter contained an ObjectName member in the OBJECT_ATTRIBUTES structure with an object path that could not be found. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | The ObjectAttributes parameter did not contain a RootDirectory member, but the ObjectName member in the OBJECT_ATTRIBUTES structure was an empty string or did not contain an OBJECT_NAME_PATH_SEPARATOR character. This indicates incorrect syntax for the object path. |
This function has no associated import library or header file; you must call it using the LoadLibrary and GetProcAddress functions.
| Requirement | Value |
|---|---|
| DLL |
Ntdll.dll |
This function is documented in Windows Driver Kit.
Pointer to HANDLE value representing opened Directory Object.
Access mask. See NtCreateDirectoryObject for possible values.
Must contains valid Directory Object name.