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

Question

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

SkullyHIT Rios 0

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.

0 comments

2 answers

Your answer

Answer 1

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:

Answer 2

Zack Nguyen (WICLOUD CORPORATION) 405 Microsoft External Staff Moderator

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.

SkullyHIT Rios 0 Reputation points

2026-10-29T15:40:11.4366667+00:00
Thank you for the detailed clarification regarding DuplicateHandle and SetFileInformationByHandle.

I have one follow-up question about the exact guarantees of this combination.

Suppose an application:

Creates and fully flushes a staged file.

Duplicates its open file handle using DuplicateHandle.

Closes the original handle while retaining the duplicate.

Calls SetFileInformationByHandle(FileRenameInfo) using the surviving duplicate, with ReplaceIfExists = FALSE.

My questions are:

Does this sequence provide a documented guarantee that the rename operates on the same underlying file object originally opened, even if another process changes the source pathname?

Are there documented limitations involving sharing modes, access rights, hard links, deletion or concurrent namespace changes that could invalidate this source-object binding?

Does retaining the duplicate affect the documented no-replace behavior when competing processes attempt to publish to the same destination?

I understand that this does not establish full concurrent linearizability or eliminate unknown outcomes when completion status is lost.

I'm specifically trying to distinguish what Microsoft publicly guarantees about source-object identity continuity from what remains unproven about concurrent destination publication.

Any authoritative Microsoft documentation clarifying these boundaries would be appreciated.Thank you for the detailed clarification regarding DuplicateHandle and SetFileInformationByHandle.

I have one follow-up question about the exact guarantees of this combination.

Suppose an application:

Creates and fully flushes a staged file.

Duplicates its open file handle using DuplicateHandle.

Closes the original handle while retaining the duplicate.

Calls SetFileInformationByHandle(FileRenameInfo) using the surviving duplicate, with ReplaceIfExists = FALSE.

My questions are:

Does this sequence provide a documented guarantee that the rename operates on the same underlying file object originally opened, even if another process changes the source pathname?

Are there documented limitations involving sharing modes, access rights, hard links, deletion or concurrent namespace changes that could invalidate this source-object binding?

Does retaining the duplicate affect the documented no-replace behavior when competing processes attempt to publish to the same destination?

I understand that this does not establish full concurrent linearizability or eliminate unknown outcomes when completion status is lost.

I'm specifically trying to distinguish what Microsoft publicly guarantees about source-object identity continuity from what remains unproven about concurrent destination publication.

Any authoritative Microsoft documentation clarifying these boundaries would be appreciated.
Zack Nguyen (WICLOUD CORPORATION) 405 Reputation points Microsoft External Staff Moderator

2026-10-30T10:22:13.3633333+00:00
Hi @SkullyHIT Rios ,

Thank you for the follow-up questions.

1. Does the rename operate on the same underlying file object?

Yes. The DuplicateHandle documentation states that the duplicate refers to the same object as the original handle. Closing the original handle does not change what the duplicate refers to.

Because SetFileInformationByHandle operates on the file identified by the supplied handle, changing the source pathname does not, by itself, cause it to select a different source file.

2. Can sharing modes, access rights, hard links, deletion, or namespace changes invalidate that binding?

The duplicate must have the access required for the rename. Sharing restrictions, deletion state, access checks, or concurrent namespace changes may cause the operation to fail, but the cited documentation does not say that they rebind the duplicate to another file.

Hard links also do not invalidate the binding because they are different directory entries for the same file, as described in Hard Links and Junctions.

3. Does retaining the duplicate affect the no-replace behavior?

No documented exception is stated for a duplicated handle. The FILE_RENAME_INFO documentation states that when ReplaceIfExists is FALSE, the operation returns an error if the destination exists.

If you need an authoritative clarification of guarantees that are not explicitly established by the public Windows API documentation, I recommend opening a support request through Microsoft Support for Business. If you do not have a business support plan, you can instead contact Microsoft Support.

I hope these answers are helpful to your questions.
Zack Nguyen (WICLOUD CORPORATION) 405 Reputation points Microsoft External Staff Moderator

2026-11-03T10:16:38.4366667+00:00

Hi @SkullyHIT Rios ,
Just checking in to see if you have any other questions. Feel free to let me know in a comment below.
Zack Nguyen (WICLOUD CORPORATION) 405 Reputation points Microsoft External Staff Moderator

2026-11-05T09:42:48.1766667+00:00

Hi @SkullyHIT Rios ,
As we haven’t heard back from you for a while, we’ll go ahead and close this thread for now. If you still need assistance later, feel free to reach out.

Thank you for your understanding.