Windows NTFS — Supported user-mode primitive for no-replace publication of an existing file

SkullyHIT Rios 0 Reputation points
2026-10-28T14:00:40.3366667+00:00

I'm researching a Windows application that writes and flushes a staged file, closes its handle, and then publishes the completed file under a destination pathname.

The requirements are:

Never replace an existing destination.

Prevent competing publishers from both successfully claiming the same destination.

Bind publication to the exact intended staged file, even when other actors may modify the namespace.

Distinguish confirmed destination collisions from other failures.

Preserve an unknown-outcome classification if an operation's completion status is lost.

SetFileInformationByHandle(FileRenameInfo) with ReplaceIfExists = FALSE documents existing-destination refusal, but I have not found a public guarantee of full concurrent linearizability.

CreateHardLinkW offers a different publication model but selects the source by pathname and leaves an additional link requiring lifecycle management.

The filesystem-driver documentation describes handle-based linking through FileLinkInformation, but that class is not listed among the supported classes for the Win32 SetFileInformationByHandle function.

My question: Is there a documented, supported user-mode Windows API or combination of APIs that provides stronger guarantees for this operation? In particular, is there a supported way to bind the exact staged file object to a no-replace publication operation after its original handle has been closed?

I'm looking for authoritative Microsoft documentation or technically grounded limitations, not assumptions based only on observed NTFS behavior.

This is documentation-only research. No code execution or implementation is being requested.

Windows development | Windows API - Win32
0 comments

2 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Zack Nguyen (WICLOUD CORPORATION) 405 Reputation points Microsoft External Staff Moderator
    2026-10-29T03:37:34.98+00:00

    Hi @SkullyHIT Rios ,
    Thank you for the clear write up and for your questions.

    Public Microsoft documentation establishes individual guarantees for this operation, but it does not establish a complete API contract covering all of your stated requirements.

    1. If only the original handle must be closed

    • There is a documented way to preserve binding to the exact file object: retain a duplicate created before closing that handle. The DuplicateHandle documentation explicitly states that the duplicate refers to the same object as the original.
    • That surviving handle can identify the source for SetFileInformationByHandle, provided it has the permissions required for the operation. With FileRenameInfo, the FILE_RENAME_INFO documentation states that ReplaceIfExists = FALSE causes an error if the target exists. This combines documented source-object binding with documented existing-destination refusal. It does not, however, establish the stronger concurrent-linearizability or lost-completion guarantees you describe.

    2. If all handles to the staged file must be closed before publication

    • OpenFileById is a documented alternative to reopening the source by pathname. It opens the file matching a specified identifier. The file-ID documentation states that an NTFS file retains its ID until deletion, but also warns that file IDs are not guaranteed unique over time because file systems may reuse them.
    • Consequently, reopening by ID is relevant when the intended file survives the closed-handle interval. A saved ID does not establish an unconditional guarantee of binding to the original file if other actors may delete it and the identifier may subsequently be reused.

    3. Regarding handle-based linking

    • FileLinkInformation is not listed among the supported classes for the Win32 SetFileInformationByHandle function. However, the NtSetInformationFile documentation lists that class and explicitly discusses calls from user mode. It would therefore be too strong to describe handle-based linking as entirely undocumented for user mode. Nevertheless, that reference does not establish the complete stronger publication contract you are seeking, and its user-mode guidance should not be treated as making FileLinkInformation supported by the Win32 function.

    In conclusion, closing the original handle is compatible with preserving exact object binding through a surviving duplicate. If the requirement instead mandates closing every handle and allowing unrestricted deletion or replacement during that interval, the cited documentation does not establish a supported combination that guarantees subsequent publication of the exact original staged file. Nor does it establish the full concurrent-publication and outcome-recovery guarantees.

    If you need an authoritative, supported statement on whether Windows provides stronger guarantees for this publication pattern, including the concurrency and exact-file-identity cases described above, I’d recommend opening a support request with Microsoft through Support for Business. If you don’t have a business support plan, you can instead contact Microsoft Support. This would be the appropriate route for obtaining guidance on behavior or guarantees that are not explicitly established by the public API documentation.

    I hope this helps clarifying your requirements and answering your questions. If you find my response helpful, I would greatly appreciate it if you could follow the guide here so others experiencing similar behavior or issue can benefit from it as well.

    Was this answer helpful?

  2. AI answer

    2026-10-28T14:01:02.9233333+00:00

    No public documentation in the provided material establishes a stronger supported user-mode primitive than rename/move semantics for this requirement, and no documented API in that material provides a handle-bound, no-replace publication guarantee after the original staged-file handle has been closed.

    Supported facts from the documentation provided:

    • For transacted file I/O, renaming is documented as a move operation: to rename a file as a transacted operation, call MoveFileTransacted.
    • Transactional NTFS documentation also states that directory contents can change while enumeration is in progress, and changes outside a transaction are immediately visible inside the transaction. That material describes visibility and isolation behavior, not a general linearizability guarantee for competing publishers.
    • Applications should close all handles bound to a transaction before commit, and for memory-mapped files must flush views, close the mapping object, and close the file handle before committing. That supports durability/cleanup requirements, but not the stronger publication contract requested.
    • Windows file-system operations are only cancelable when blocked and waiting; operations actively being processed are not cancelable. That means loss of completion status can leave uncertainty about outcome, but the provided documentation does not define a publication primitive that eliminates that ambiguity.

    The closest documented conclusion in the provided material is a limitation:

    • Public documentation does not establish the requested object/effect boundary or concurrency guarantee for relative create/rename-style operations under namespace races.
    • Observed NTFS behavior on a tested build is not a supported Windows-wide contract.
    • An authoritative determination of internal serialization boundaries and supported guarantees would require a Microsoft Support case.

    Applied to this question, the provided documentation does not document:

    • a supported user-mode API that binds publication to an exact staged file object after its handle has been closed,
    • a stronger no-replace publication guarantee than the documented rename/move behavior,
    • a documented way to distinguish all destination-collision outcomes from every other failure under concurrent namespace mutation beyond the normal returned status of the specific API call,
    • a documented primitive that removes unknown-outcome cases when completion status is lost.

    So, from the provided documentation alone, the supported answer is:

    • No documented stronger user-mode primitive is established here.
    • No documented handle-bound no-replace publication operation after closing the original handle is established here.
    • The public documentation provided is insufficient to claim full concurrent linearizability or a stronger exact-object publication contract.
    • For an authoritative guarantee beyond that, a Microsoft Support case is required.

    References:

    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.