Windows NtCreateFile: RootDirectory, reparse-point handling, and supported flag combinations

Starlin Concepcion 0 Reputation points
2026-11-16T17:50:43.24+00:00

Hello,

I am researching the documented Windows file-system API contracts for a security-sensitive operation that may need to create one new file within a previously validated directory.

This is a documentation and design question only. No implementation or testing is being requested.

  1. RootDirectory and relative file creation

When NtCreateFile is called with a relative ObjectName and a RootDirectory handle:

  • What requirements must the RootDirectory handle satisfy?
  • Must the handle have been opened through NtCreateFile, or can a compatible handle obtained through another documented Windows API be used?
  • What directory access rights are required for relative creation?
  • Are there additional requirements concerning the handle's sharing mode or lifetime?
  1. OBJ_DONT_REPARSE

The general OBJECT_ATTRIBUTES documentation describes OBJ_DONT_REPARSE, while the NtCreateFile documentation identifies a more limited set of supported object attributes.

  • Is OBJ_DONT_REPARSE supported for file-system operations performed through NtCreateFile?
  • If supported, does it apply to every component resolved during a relative-path operation, or only to certain components?
  • What status is returned when a reparse point is encountered?
  • Are there Windows-version or file-system-specific limitations?
  1. FILE_DIRECTORY_FILE and FILE_OPEN_REPARSE_POINT

The NtCreateFile documentation includes restrictions on creation options used with FILE_DIRECTORY_FILE.

  • Is combining FILE_DIRECTORY_FILE with FILE_OPEN_REPARSE_POINT supported?
  • If not, what documented mechanism should an application use to inspect a directory reparse point without following its target?
  • How does that behavior differ for intermediate path components?
  1. Exclusive creation

When FILE_CREATE is used with a directory-relative name:

  • Does exclusive creation apply atomically to the final directory entry?
  • Which parts of the directory path or object identity are outside that guarantee?
  • Which documented failure statuses should be distinguished from an operation whose result is uncertain?

I am looking for authoritative API-contract clarification, including applicable Windows versions, supported option combinations, limitations, and official references.

I am not requesting code or an operational workaround.

Thank you.

Windows development | Windows API - Win32
0 comments No comments

2 answers

Sort by: Most helpful
  1. Nguyen Dam (WICLOUD CORPORATION) 1,580 Reputation points Microsoft External Staff Moderator
    2026-11-17T03:38:11.8266667+00:00

    Hello @Starlin Concepcion , and thank you for reaching out. 

    Based on the published Windows API documentation, here is what I can clarify regarding your questions, along with areas where further clarification may be needed. 

    1. RootDirectory and relative creation 

    Assuming NtCreateFile is called with a relative ObjectName and a RootDirectory handle: 

    1. The RootDirectory handle must refer to an existing directory, and ObjectName must specify a path relative to that directory. For FILE_CREATE, the target file must not already exist, although any intermediate directories in the relative path must exist. 
    2. Documentation doesn't specify explicitly whether the handle must be opened through NtCreateFile or not. 
    3. FILE_ADD_FILE is the documented directory access right associated with creating files within a directory. However, the documentation does not explicitly establish whether this right must be granted to the RootDirectory handle for relative creation through NtCreateFile. 
    4. Concerning the handle's sharing mode or lifetime, normal Windows file-sharing rules apply, and the directory handle must remain valid while it is being used. Other than that, the documentation does not identify additional sharing or lifetime requirements specific to relative creation. 

    2. OBJ_DONT_REPARSE 

    Although OBJ_DONT_REPARSE is described in the general OBJECT_ATTRIBUTES documentation, the NtCreateFile documentation lists a narrower set of supported flags. 

    The general documentation specifies STATUS_REPARSE_POINT_ENCOUNTERED when a reparse point is encountered. However, I cannot confirm from these references whether NtCreateFile supports this flag with the requested guarantees, including its precise scope during relative-path resolution and any Windows-version or file-system-specific limitations. 

    3. FILE_DIRECTORY_FILE and FILE_OPEN_REPARSE_POINT 

    After reviewing the relevant documentation, I could not establish whether this combination is officially supported by NtCreateFile, as FILE_OPEN_REPARSE_POINT is not included among the listed compatible options for FILE_DIRECTORY_FILE. 

    For the second and third questions, CreateFileW provides a documented way to open a directory reparse point itself using FILE_FLAG_OPEN_REPARSE_POINT together with FILE_FLAG_BACKUP_SEMANTICS. The reparse-point data can then be inspected separately. However, this does not prevent reparse-point processing for intermediate path components. 

    4. Exclusive creation 

    When FILE_CREATE is used with a directory-relative name, the following distinctions are relevant:

    1. FILE_CREATE provides exclusive creation semantics. If the specified name already exists, the operation fails with STATUS_OBJECT_NAME_COLLISION. This provides create-only-if-absent behavior, although the documentation does not explicitly establish broader atomicity guarantees across all file systems and concurrent operations. 
    2. This guarantee concerns the file creation operation itself. It does not independently guarantee that the parent directory has remained unchanged since validation or that every component involved in path resolution retains its original identity. 
    3. If NtCreateFile completes with a failure status such as STATUS_OBJECT_NAME_COLLISION (the name already exists), STATUS_OBJECT_PATH_NOT_FOUND (part of the path was not found), or STATUS_ACCESS_DENIED (access was denied), the creation attempt has failed. However, if the final completion status is unavailable, the caller cannot determine from that information alone whether the file was created. An initial STATUS_PENDING indicates that the operation has not yet completed, rather than that it has failed. 

    As Microsoft Q&A is a community support forum, I cannot provide authoritative confirmation of undocumented API behavior or guarantees. If you need an authoritative clarification of the API contract, I recommend opening a case with Microsoft Support for Business. If you do not have a business support plan, you can contact Microsoft Support instead. 

    If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation. Thank you. 

    Was this answer helpful?


  2. AI answer

    2026-11-16T17:52:36.56+00:00

    The supported design boundary is narrower than an “original directory object or no effect” guarantee: use a live directory handle and a single relative name with FILE_CREATE, but do not rely on OBJ_DONT_REPARSE, FILE_DIRECTORY_FILE | FILE_OPEN_REPARSE_POINT, or FILE_CREATE to provide concurrency guarantees beyond those expressly documented.

    1. RootDirectory and relative creation

    For user-mode NtCreateFile, the published parameter contract says that a non-NULL RootDirectory is a handle to a directory obtained by a preceding NtCreateFile call; ObjectName is then interpreted relative to that directory. The broader OBJECT_ATTRIBUTES page merely says that the handle can refer to a file-system directory or Object Manager directory. ^1^ ^2^

    Consequently:

    • Strictly documented origin: a directory handle returned by NtCreateFile.
    • Handle from another API: Win32 file handles are often interoperable in practice, but the cited NtCreateFile contract does not establish every other API as a supported source for RootDirectory. A security design requiring a published guarantee should not infer such compatibility.
    • Lifetime: the handle must remain valid for the operation. The public documentation does not define a stronger identity guarantee when the directory is concurrently renamed, deleted, or converted into a reparse point.
    • Sharing: sharing is fixed when the directory handle is opened and remains effective until it is closed. An incompatible later open can fail with a sharing violation. Sharing does not itself establish protection against every namespace or reparse-point change. ^3^

    For authorization, distinguish two questions:

    1. The directory access rights have these meanings:
      • FILE_ADD_FILE (FILE_WRITE_DATA for a directory) permits creating a file.
      • FILE_ADD_SUBDIRECTORY (FILE_APPEND_DATA for a directory) permits creating a subdirectory.
      • FILE_TRAVERSE permits accessing objects through a directory. ^4^
    2. The available documentation does not clearly state that those rights must already be present in the granted-access mask of the retained RootDirectory handle. Creation is still subject to the applicable security checks against the directory and target. Therefore, do not turn the semantic definitions above into an undocumented exact handle-mask requirement.

    2. OBJ_DONT_REPARSE

    The documentation is inconsistent:

    • OBJECT_ATTRIBUTES says OBJ_DONT_REPARSE prevents following any reparse point encountered while parsing the associated name and returns STATUS_REPARSE_POINT_ENCOUNTERED. ^2^
    • The user-mode NtCreateFile page says its Attributes value can be zero or OBJ_CASE_INSENSITIVE; it does not list OBJ_DONT_REPARSE. ^1^

    A Microsoft Q&A test found that OBJ_DONT_REPARSE was honored by user-mode NtCreateFile on Windows 11 build 26200 and local NTFS, for both final and intermediate reparse points, returning STATUS_REPARSE_POINT_ENCOUNTERED (0xC000050B). That is implementation evidence for that configuration, not a published cross-version or cross-file-system support guarantee. ^5^

    Do not confuse that status with STATUS_REPARSE: NtCreateFile expressly says it never returns STATUS_REPARSE; normal reparse processing is handled internally before the final result. ^6^

    Reparse support itself is file-system-specific: NTFS and ReFS support reparse points, while FAT does not. Filters can also define processing for particular tags. ^7^

    3. FILE_DIRECTORY_FILE | FILE_OPEN_REPARSE_POINT

    This combination is not in the documented compatibility set. With FILE_DIRECTORY_FILE, the listed compatible options are only:

    • FILE_SYNCHRONOUS_IO_ALERT
    • FILE_SYNCHRONOUS_IO_NONALERT
    • FILE_WRITE_THROUGH
    • FILE_OPEN_FOR_BACKUP_INTENT
    • FILE_OPEN_BY_FILE_ID

    FILE_OPEN_REPARSE_POINT is absent. Therefore, the public contract does not establish the combination as supported, even if a particular Windows/file-system version accepts it. ^1^ Microsoft Q&A reaches the same conclusion for local NTFS and notes that no documented version, file-system, or filter qualification makes the combination supported. ^8^

    The documented Win32 mechanism for inspecting a directory reparse point is:

    1. Open the directory using CreateFile with both FILE_FLAG_BACKUP_SEMANTICS and FILE_FLAG_OPEN_REPARSE_POINT.
    2. Issue DeviceIoControl(..., FSCTL_GET_REPARSE_POINT, ...) on that handle. FSCTL_GET_REPARSE_POINT support is optional and may fail where the object store does not implement it. ^9^ ^10^

    FILE_OPEN_REPARSE_POINT affects the object being directly opened. It does not document a refusal policy for every intermediate component; intermediate reparse processing can still occur. OBJ_DONT_REPARSE describes the different “refuse if any reparse is encountered” behavior, subject to the documentation discrepancy above.

    4. FILE_CREATE and exclusivity

    FILE_CREATE documents only this final-name behavior:

    • If the resolved file already exists, fail without opening or creating it.
    • If it does not exist, create it.
    • On completed success, IoStatusBlock.Information can report FILE_CREATED. ^1^

    That is the documented exclusive-create disposition for the resolved final name. The API page does not independently specify a broader atomic guarantee covering:

    • stability of the retained parent’s namespace identity;
    • concurrent conversion of the parent into a junction;
    • intermediate-component traversal;
    • reparse or filter redirection;
    • rename/delete races;
    • an “original object or pre-effect refusal” boundary.

    Microsoft Q&A specifically concludes that the public documentation does not establish that stronger guarantee for concurrent reparse-point conversion. ^8^

    Treat a result as confirmed only after the operation has reached final completion and both the final NTSTATUS and IO_STATUS_BLOCK have been examined. Ordinary completed failures—such as a name collision, access denial, sharing violation, invalid option combination, or STATUS_REPARSE_POINT_ENCOUNTERED where applicable—are distinguishable failures. The public contract does not provide a general recovery rule for interruption, filter-specific behavior, or concurrency cases where final completion cannot be established.


    References

    1. NtCreateFile function (winternl.h)
    2. OBJECT_ATTRIBUTES structure (ntdef.h)
    3. CreateFileA function (fileapi.h)
    4. Access Mask
    5. Is OBJ_DONT_REPARSE supported by user-mode NtCreateFile with a directory-relative name? - Microsoft Q&A
    6. NtCreateFile function (ntifs.h)
    7. File system reparse points
    8. NTFS single-component NtCreateFile relative to a held directory during junction conversion: original-object-or-refusal contract? - Microsoft Q&A
    9. Reparse Point Operations
    10. [IP Address].14 FSCTL_GET_REPARSE_POINT
    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.