CreateDirectory2W: Clarification of return value, handle semantics, and path redirection

Question

CreateDirectory2W: Clarification of return value, handle semantics, and path redirection

Saengaloun Keosongvongsay 20

I'm evaluating CreateDirectory2W for security-sensitive directory provisioning on supported Windows versions.

The Microsoft Learn page declares a five-parameter function returning HANDLE. Its return-value section says failure returns zero, while the example checks INVALID_HANDLE_VALUE and appears to pass six arguments.

Could the Windows API owner clarify:

What exact value does CreateDirectory2W return on failure: NULL, INVALID_HANDLE_VALUE, or another value?

What is the authoritative declaration, including calling convention, for supported Windows SDK versions?

On success, is the returned handle bound to the directory created by that same call?

What are the scope and limitations of DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS, particularly for intermediate path components?

A corrected API reference or authoritative specification would help assess its suitability for a security-sensitive implementation.

Documentation: https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createdirectory2w

Thank you.

0 comments

Answer accepted by question author

AI answer

The current CreateDirectory2W reference is internally inconsistent and is not sufficient by itself to establish the exact ABI and security contract; use the five-parameter SDK declaration, defensively reject both NULL and INVALID_HANDLE_VALUE, and do not assume stronger intermediate-component or concurrency guarantees than Microsoft explicitly documents.

Return value and example defects

The Unicode page says failure returns zero, but its example checks INVALID_HANDLE_VALUE and passes six arguments to a documented five-parameter function.^1^

The ANSI counterpart has the same five parameters but explicitly says failure returns INVALID_HANDLE_VALUE; it also lists ERROR_PATH_REDIRECTED as a possible error.^2^

These pages therefore do not provide one consistent normative failure value. For code targeting the currently supported releases, treat either sentinel as failure and capture GetLastError() immediately:

HANDLE h = CreateDirectory2W(
    path,
    FILE_LIST_DIRECTORY | SYNCHRONIZE,
    FILE_SHARE_READ,
    DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS,
    securityAttributes);

if (h == nullptr || h == INVALID_HANDLE_VALUE) {
    const DWORD error = GetLastError();
    // Report or map error here.
    return error;
}

// Use h; close it exactly once.
CloseHandle(h);

This is a defensive workaround for the published discrepancy, not confirmation that both values are emitted by the implementation.

The example’s sixth NULL argument does not match either documented declaration and should not be copied.

Declaration and calling convention

The public syntax currently shown is:

HANDLE CreateDirectory2W(
    LPCWSTR               lpPathName,
    DWORD                 dwDesiredAccess,
    DWORD                 dwShareMode,
    DIRECTORY_FLAGS       DirectoryFlags,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

The documented requirements are Windows 11 24H2 or Windows Server 2025, fileapi.h through Windows.h, Kernel32.lib, and Kernel32.dll.^1^ The header index also identifies CreateDirectory2W as the Unicode entry point.^3^

However, the rendered declaration omits any import/export and calling-convention macros. The supplied public references do not establish the expanded calling convention. For ABI-sensitive use, the authoritative declaration for a particular build is the unmodified fileapi.h shipped with the exact Windows SDK used to compile it; do not create a handwritten declaration or infer the convention from the simplified Learn syntax. Microsoft needs to publish the complete header declaration if a source-level ABI specification is required.

Also call CreateDirectory2W explicitly rather than the encoding-neutral CreateDirectory2 alias when the path is UTF-16. The alias selects ANSI or Unicode according to UNICODE.^1^

Returned-handle semantics

The API accepts desired access and sharing parameters described as applying to “the returned handle,” strongly indicating that successful creation returns an open directory handle.^1^ The example likewise retains that handle to prevent deletion and closes it after using the directory.

Nevertheless, the current text does not explicitly specify:

an object-identity guarantee tying the handle to the directory inserted by that same operation;
behavior under concurrent rename or reparse-point conversion;
an atomic “create in the intended directory or create nothing” boundary.

For a security proof that depends on those properties, the present public documentation is insufficient.

`DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS`

The published flag definition says it prevents the specified path from being redirected by reparse points or symbolic links.^4^ The ANSI page associates a detected redirect with ERROR_PATH_REDIRECTED.^2^

It does not precisely define for CreateDirectory2W:

whether every intermediate component is checked;
which reparse tags are covered beyond the stated reparse points and symbolic links;
behavior when a component changes concurrently during resolution;
filesystem, SMB, or filter-driver qualifications;
whether detecting a redirect guarantees that no directory was created elsewhere.

RemoveDirectory2W is more explicit for its own operation: it says the call fails if any part of the path is redirected.^5^ That wording should not be promoted into a contractual guarantee for CreateDirectory2W.

Consequently, CreateDirectory2W may be useful as a mitigation on its supported systems, but the current references do not establish the full intermediate-component and race-resistant contract needed for a security-sensitive provisioning primitive. A corrected reference should specify the failure sentinel, exact exported declaration, handle/object identity, component coverage, race semantics, and no-side-effect behavior on ERROR_PATH_REDIRECTED.

References

AI-generated content may be incorrect. Read our transparency notes for more information.

1 additional answer

Your answer

Answer 1

Hi @Saengaloun Keosongvongsay ,

On the configuration I tested, CreateDirectory2W returned INVALID_HANDLE_VALUE for every failure, the SDK declares it with five parameters and WINAPI, successful handles referred to the directory created by the call, and DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS blocked every intermediate redirect I tried on a stable path. The result that matters most for a security design is different, though: when path components were replaced concurrently, some calls failed with the flag set and still left a directory at the redirected destination.

The tests ran on Windows 11 Pro build 26300.9457 with Windows SDK 10.0.26100.0, as a native x64 program on local NTFS volumes.

The CreateDirectory2W reference says failure returns zero, while its own example checks INVALID_HANDLE_VALUE and passes six arguments. The CreateDirectory2A reference documents INVALID_HANDLE_VALUE. In my tests, all 12,597 failed calls returned INVALID_HANDLE_VALUE, and none returned NULL. The SDK's fileapi.h declares:

WINBASEAPI
HANDLE
WINAPI
CreateDirectory2W(
    _In_z_ LPCWSTR lpPathName,
    _In_ DWORD dwDesiredAccess,
    _In_ DWORD dwShareMode,
    _In_ DIRECTORY_FLAGS DirectoryFlags,
    _In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes
    );

It is available when NTDDI_VERSION >= NTDDI_WIN11_GE, and WINAPI expands to __stdcall. Checking for both NULL and INVALID_HANDLE_VALUE is still a reasonable precaution until the W page is corrected.

To check the returned handle, I compared its volume serial number and 128-bit file ID with a separate open of the same path, as described in FILE_ID_INFO. Every successful call matched the directory it created. That supports reading the handle as bound to the created directory, but it does not show whether the directory ended up under the intended parent while the path was changing.

The DIRECTORY_FLAGS reference only says the flag prevents redirection by reparse points or symbolic links. On a stable path, it blocked symbolic links, junctions and a volume mount point at the parent, grandparent and chained positions, and nothing was created at the destination. The error was 4395 (ERROR_REPARSE_POINT_ENCOUNTERED), not ERROR_PATH_REDIRECTED, so error handling should not rely on the latter.

Concurrent changes produced a different result. While another thread kept swapping a parent component, 14 of 8,000 calls with the flag returned INVALID_HANDLE_VALUE and 4395, yet the directory existed at the redirected destination afterward. A separate minimal program swapping two symbolic links saw 23 such cases in 10,000 calls. This does not identify the internal cause, but on this build a failed call is not evidence that nothing was created elsewhere.

Two parameter details are also worth knowing. With the flag set, any share mode that includes FILE_SHARE_WRITE failed with ERROR_INVALID_PARAMETER (87). Undefined flag values such as 0x80000000 were accepted silently, so a wrong flag value gives no redirect protection rather than an error.

These results cover one build, x64 and local NTFS only. If your design needs "create in the intended location or create nothing", I would not rely on the flag and the failure return alone. For a contractual answer on these points, Windows developer support can reach the API owner, since forum testing can only describe observed behavior.

I hope this helps separate what can be observed today from what still needs an official guarantee. If you found my response helpful or informative, I would greatly appreciate it if you could follow this guidance so that others in the community facing a similar issue can find it more easily and help each other.

Thank you.