Clarification of documented Windows directory-metadata guarantees

Hello @Matthew Roberts ,

I read the six pages you cited line by line, and I checked them against the normative [MS-FSA] spec and the related Win32/WDK pages. Below I give my classification for each item, with the exact sentence I rely on.

1. Attribute / tag / payload: I classify this as CONDITIONAL

• FILE_ATTRIBUTE_TAG_INFO has only FileAttributes and ReparseTag. I find the payload only via FSCTL_GET_REPARSE_POINT.
• MS-FSA 2.1.5.12.5: "If Open.GrantedAccess does not contain FILE_READ_ATTRIBUTES, the operation MUST be failed with STATUS_ACCESS_DENIED."
• CreateFileW, dwDesiredAccess: "If this parameter is zero, the application can query certain metadata … without accessing that file or device." The Remarks add "if the application is running with adequate security settings."
• Why I do not say GUARANTEED: MS-FSA 2.1.5.1 says "If DesiredAccess is zero … the operation MUST be failed with STATUS_ACCESS_DENIED", and I cannot find on the Win32 page what a zero value is mapped to. For cloud placeholders the filter can hide the tag: RtlSetProcessPlaceholderCompatibilityMode says "When placeholders are disguised, these details are completely hidden … Windows may decide that certain applications see disguised placeholders by default." GetFileInformationByHandleEx says the information classes are "subject to change between operating system releases."

2. Referral: I classify this as GUARANTEED for the final component only, and NOT_GUARANTEED for parent components

• CreateFileW: "Normal reparse point processing will not occur … If the file is not a reparse point, then this flag is ignored." In MS-FSA 2.1.5.1.2 I see the FILE_OPEN_REPARSE_POINT check applied only to the final File.
• MS-FSA 2.1.5.1, Phase 6, for components 1..n-1: "If Link.File.IsSymbolicLink is TRUE, the operation MUST be failed with … STATUS_STOPPED_ON_SYMLINK." This rule does not look at the flag. NtCreateFile: "NtCreateFile never returns STATUS_REPARSE", so the I/O manager follows the link for you.
• I could not find any description of non-symlink tags (junction, mount point, cloud) at intermediate positions, so for those I say CANNOT_CONFIRM.

3. Identity: I classify this as CONDITIONAL

• GetFileInformationByHandle: you can compare VolumeSerialNumber and FileIndex "to determine if two paths map to the same target." The same Remarks also say the function "may fail, return partial information, or full information" depending on the network.
• BY_HANDLE_FILE_INFORMATION: "File IDs are not guaranteed to be unique over time"; on ReFS the 64-bit ID "is not guaranteed to be unique."
• GetFinalPathNameByHandleW describes the handle you already hold. I found nothing on any page about binding over time, or about proving that no earlier referral happened, so I say CANNOT_CONFIRM for those two points.

4. Effects: I classify this as NOT_GUARANTEED

• I read FILE_FLAG_OPEN_NO_RECALL as a request about file data only. CreateFileW: "it should continue to be located in remote storage … This flag is for use by remote storage systems." NtCreateFile: "Instructs any filters … to not recall the contents of the file."
• For virtual items I found the documentation saying the opposite. File Attribute Constants, FILE_ATTRIBUTE_RECALL_ON_OPEN: "Opening the item … will cause at least some of it to be fetched from a remote store." ProjFS, Providing File Data: on open, "ProjFS calls the PRJ_GET_PLACEHOLDER_INFO_CB callback for each item of the path that does not yet exist on disk … to create a placeholder in the local file system." MS-FSA 2.1.5.6.3: a directory query "MUST note that the file has been accessed."
• FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY (FindFirstFileExW): "Limits the results to files that are physically on disk." I read this as an output filter only; it says nothing about provider work.

5. Enumeration: I classify this as CONDITIONAL for binding and tag visibility, and NOT_GUARANTEED for completeness, snapshot, finite work and absence of provider effects

• FindFirstFileExW: the data describes "the symbolic link, not the target." The child tag is in dwReserved0 when FILE_ATTRIBUTE_REPARSE_POINT is set (Reparse Point Tags).
• Same page: "does no sorting"; "file attribute information on NTFS file systems may not be current"; another process "could create or delete a file … between the time you query for the result and the time you act on the information."
• MS-FSA 2.1.5.6.3: the store "MAY delay updating a Link's duplicated information … returning stale information", and I see it walks a live DirectoryList, not a snapshot.
• File Attribute Constants, FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS: "enumerating the directory … will cause at least some of the file/directory content to be fetched from a remote store." ProjFS, Enumerating Files and Directories: enumeration calls the provider's enumeration callbacks.
• I found no time limit on any page, so I say CANNOT_CONFIRM.

6. Failure / completion: I classify this as NOT_GUARANTEED for a deadline, and CANNOT_CONFIRM for absence of internal retries

• CancelSynchronousIo: "marks them for cancellation … other operations can continue toward completion … does not wait." The operation can still complete normally "because the cancel request might not have been submitted in time."
• Canceling Pending I/O Operations: "There is no guarantee that underlying drivers correctly support cancellation."
• MS-FSA 2.1.5.20: "How operation cancellation is implemented is object store specific."
• I found no completion deadline and no statement about internal retries on any page. I note that all six pages list SMB 3.0 Transparent Failover as supported, which by design retries operations for the application.

The six pages support the individual API contracts above. In my reading they do not support the combined guarantee (metadata only, no referral anywhere in the path, no provider activity, no recall, no storage change, complete finite enumeration, hard cancel deadline). For items 2, 4 and 5 the documentation says the opposite for reparse or virtual directories. For items 3 and 6 it is silent. The conditions I see missing are: Windows version, file system, every filter/provider on the path and its placeholder mode, the tags of all path components, and driver support for cancellation.

For the gaps and the inconsistency I noted in item 1, I suggest using the feedback control on the page itself. On every Microsoft Learn page it is in the right-hand column, directly under "In this article" ("Was this page helpful?"). It goes to the team that owns that page.

Hope these information help! If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation.

Thank you.

Hello Matthew,

Based on the six Microsoft Learn references you cited, the documented contracts do not support a single combined guarantee covering all of the properties in the question. Several of the requested properties are explicitly outside the contract of these Win32 APIs.

My reading of the documented behavior is:

Item	Result	Documentation-based reason
1. Attribute/tag/payload	GUARANTEED, with conditions	FILE_ATTRIBUTE_TAG_INFO contains FileAttributes and ReparseTag; it does not contain the reparse payload. CreateFile also documents that dwDesiredAccess = 0 can permit querying certain metadata without requesting read/write access to the file. However, this does not constitute a general guarantee that no filesystem/filter/provider will access underlying data.
--------	--------	--------
1. Attribute/tag/payload	GUARANTEED, with conditions	FILE_ATTRIBUTE_TAG_INFO contains FileAttributes and ReparseTag; it does not contain the reparse payload. CreateFile also documents that dwDesiredAccess = 0 can permit querying certain metadata without requesting read/write access to the file. However, this does not constitute a general guarantee that no filesystem/filter/provider will access underlying data.
2. Referral / reparse behavior	CONDITIONAL	FILE_FLAG_OPEN_REPARSE_POINT changes the final-component behavior: Windows attempts to open the reparse point itself rather than performing normal reparse processing. For symbolic links, Microsoft explicitly documents that without the flag the handle is to the target, while with it the handle is to the symbolic link. The cited documentation does not establish a blanket guarantee about every intermediate path component or every possible filesystem/filter-provider referral.
3. Identity	CONDITIONAL	GetFileInformationByHandle documents that VolumeSerialNumber and FileIndex can be compared to determine whether two paths map to the same target. GetFinalPathNameByHandle reports the final path associated with an already-open handle. Neither API establishes uninterrupted historical binding from the original pathname, nor does equality prove that no earlier referral occurred. Concurrent changes and filesystem/provider semantics remain relevant.
4. Effects	NOT_GUARANTEED	FILE_FLAG_OPEN_NO_RECALL is documented as a request that file data remain in remote storage rather than being transported back to local storage; it is not documented as a universal prohibition on provider activity, synchronization, metadata changes, or other side effects. Likewise, requesting metadata does not create a general contract that no filesystem/filter/provider activity occurs.
5. Enumeration	CONDITIONAL	FindFirstFileEx returns directory-entry information, but the documentation explicitly notes that results can become stale because another process can create/delete an entry between the query and subsequent use. It also does not promise a snapshot, completeness under concurrent modification, bounded execution time, or absence of filesystem/provider activity. If the path itself is a symbolic link, the returned data describes the link rather than its target.
6. Failure/completion	NOT_GUARANTEED	CancelSynchronousIo specifically does not wait for canceled operations to complete. Microsoft states that some operations can continue toward completion and that the caller must examine the eventual completion status. Therefore cancellation is a cancellation request, not a documented deadline.

1. Attribute/tag versus payload

The strongest explicit contract among these references is the separation represented by FILE_ATTRIBUTE_TAG_INFO:

FileAttributes
ReparseTag

The structure has no reparse-data/payload field. The payload is a separate concept obtained through APIs intended to retrieve reparse data.

More importantly, CreateFile explicitly documents that dwDesiredAccess = 0 permits an application to query certain metadata without accessing the file/device for read or write access. That is an access-right statement, not an absolute statement about what every filesystem or minifilter/provider will physically do internally.

2. Reparse/no-follow scope

FILE_FLAG_OPEN_REPARSE_POINT has a documented meaning for the object being opened. In particular, Microsoft's symbolic-link section explicitly distinguishes:

• without the flag → the handle is to the symbolic-link target;

with the flag → the handle is to the symbolic link itself.

That is sufficient to establish final-component behavior for the documented symbolic-link case. It is not sufficient to infer a universal "no referral anywhere in the pathname" guarantee, especially for arbitrary reparse tags, filesystems, or filesystem filters.

3. Names and identifiers

GetFinalPathNameByHandle is explicitly about the object represented by an existing handle. FILE_NAME_OPENED returns the opened name, whereas FILE_NAME_NORMALIZED returns the normalized final path. The documentation also says that a final path is the path obtained when a path is fully resolved.

GetFileInformationByHandle provides the VolumeSerialNumber and FileIndex information and explicitly says these can be compared to determine whether two paths map to the same target.

Neither statement establishes a temporal guarantee such as:

"This pathname was continuously bound to this object from the beginning of the operation."

Nor does identifier equality prove that no reparse/referral occurred before the object was opened.

4. OPEN_NO_RECALL

This flag should not be interpreted more strongly than Microsoft's wording.

Microsoft says FILE_FLAG_OPEN_NO_RECALL means that the requested file data should continue to be located in remote storage and should not be transported back to local storage. That is specifically about recall/localization of file data. It is not documented as a general "provider must perform no work" or "storage state cannot change" guarantee.

Similarly, the fact that an operation requests metadata rather than file contents does not create a universal guarantee against filesystem, filter, network redirector, or storage-provider activity.

5. Enumeration

FindFirstFileEx is particularly important here because the documentation explicitly warns about concurrent changes: another process can create or delete a file between obtaining the information and acting on it. Therefore the API should not be interpreted as providing an immutable directory snapshot.

The documentation also says that, when the path itself is a symbolic link, WIN32_FIND_DATA describes the symbolic link rather than its target.

Nothing in the cited reference provides a hard upper bound on enumeration time or guarantees that filesystem/provider work cannot occur.

6. Cancellation and completion

This is the clearest NOT_GUARANTEED case.

CancelSynchronousIo:

marks pending synchronous I/O for cancellation;

may allow some operations to continue toward completion;

does not wait for those operations to finish;

requires the caller to determine the eventual completion status.

Microsoft explicitly lists three possible completion outcomes: normal completion, cancellation (ERROR_OPERATION_ABORTED), or another failure.

Therefore there is no documented hard completion deadline in this API, and cancellation cannot be used as evidence that the underlying operation has already stopped.

Bottom line

The six references support specific API-level contracts, but they do not collectively establish the stronger composite invariant described in the question:

metadata-only + no referral + no provider activity + no recall/hydration + no storage-state change + complete finite enumeration + hard cancellation deadline.

For that stronger guarantee, additional contracts would have to be identified for the relevant Windows version, filesystem, network redirector, minifilter/provider, reparse-tag semantics, and access mode. The six cited Win32 pages alone do not provide such a universal guarantee.Hello Matthew,

Based on the six Microsoft Learn references you cited, the documented contracts do not support a single combined guarantee covering all of the properties in the question. Several of the requested properties are explicitly outside the contract of these Win32 APIs.

My reading of the documented behavior is:

Item	Result	Documentation-based reason
1. Attribute/tag/payload	GUARANTEED, with conditions	FILE_ATTRIBUTE_TAG_INFO contains FileAttributes and ReparseTag; it does not contain the reparse payload. CreateFile also documents that dwDesiredAccess = 0 can permit querying certain metadata without requesting read/write access to the file. However, this does not constitute a general guarantee that no filesystem/filter/provider will access underlying data.
2. Referral / reparse behavior	CONDITIONAL	FILE_FLAG_OPEN_REPARSE_POINT changes the final-component behavior: Windows attempts to open the reparse point itself rather than performing normal reparse processing. For symbolic links, Microsoft explicitly documents that without the flag the handle is to the target, while with it the handle is to the symbolic link. The cited documentation does not establish a blanket guarantee about every intermediate path component or every possible filesystem/filter-provider referral.
3. Identity	CONDITIONAL	GetFileInformationByHandle documents that VolumeSerialNumber and FileIndex can be compared to determine whether two paths map to the same target. GetFinalPathNameByHandle reports the final path associated with an already-open handle. Neither API establishes uninterrupted historical binding from the original pathname, nor does equality prove that no earlier referral occurred. Concurrent changes and filesystem/provider semantics remain relevant.
4. Effects	NOT_GUARANTEED	FILE_FLAG_OPEN_NO_RECALL is documented as a request that file data remain in remote storage rather than being transported back to local storage; it is not documented as a universal prohibition on provider activity, synchronization, metadata changes, or other side effects. Likewise, requesting metadata does not create a general contract that no filesystem/filter/provider activity occurs.
5. Enumeration	CONDITIONAL	FindFirstFileEx returns directory-entry information, but the documentation explicitly notes that results can become stale because another process can create/delete an entry between the query and subsequent use. It also does not promise a snapshot, completeness under concurrent modification, bounded execution time, or absence of filesystem/provider activity. If the path itself is a symbolic link, the returned data describes the link rather than its target.
6. Failure/completion	NOT_GUARANTEED	CancelSynchronousIo specifically does not wait for canceled operations to complete. Microsoft states that some operations can continue toward completion and that the caller must examine the eventual completion status. Therefore cancellation is a cancellation request, not a documented deadline.

1. Attribute/tag versus payload

The strongest explicit contract among these references is the separation represented by FILE_ATTRIBUTE_TAG_INFO:

FileAttributes
ReparseTag

The structure has no reparse-data/payload field. The payload is a separate concept obtained through APIs intended to retrieve reparse data.

More importantly, CreateFile explicitly documents that dwDesiredAccess = 0 permits an application to query certain metadata without accessing the file/device for read or write access. That is an access-right statement, not an absolute statement about what every filesystem or minifilter/provider will physically do internally.

2. Reparse/no-follow scope

FILE_FLAG_OPEN_REPARSE_POINT has a documented meaning for the object being opened. In particular, Microsoft's symbolic-link section explicitly distinguishes:

without the flag → the handle is to the symbolic-link target;

with the flag → the handle is to the symbolic link itself.

That is sufficient to establish final-component behavior for the documented symbolic-link case. It is not sufficient to infer a universal "no referral anywhere in the pathname" guarantee, especially for arbitrary reparse tags, filesystems, or filesystem filters.

3. Names and identifiers

GetFinalPathNameByHandle is explicitly about the object represented by an existing handle. FILE_NAME_OPENED returns the opened name, whereas FILE_NAME_NORMALIZED returns the normalized final path. The documentation also says that a final path is the path obtained when a path is fully resolved.

GetFileInformationByHandle provides the VolumeSerialNumber and FileIndex information and explicitly says these can be compared to determine whether two paths map to the same target.

Neither statement establishes a temporal guarantee such as:

"This pathname was continuously bound to this object from the beginning of the operation."

Nor does identifier equality prove that no reparse/referral occurred before the object was opened.

4. OPEN_NO_RECALL

This flag should not be interpreted more strongly than Microsoft's wording.

Microsoft says FILE_FLAG_OPEN_NO_RECALL means that the requested file data should continue to be located in remote storage and should not be transported back to local storage. That is specifically about recall/localization of file data. It is not documented as a general "provider must perform no work" or "storage state cannot change" guarantee.

Similarly, the fact that an operation requests metadata rather than file contents does not create a universal guarantee against filesystem, filter, network redirector, or storage-provider activity.

5. Enumeration

FindFirstFileEx is particularly important here because the documentation explicitly warns about concurrent changes: another process can create or delete a file between obtaining the information and acting on it. Therefore the API should not be interpreted as providing an immutable directory snapshot.

The documentation also says that, when the path itself is a symbolic link, WIN32_FIND_DATA describes the symbolic link rather than its target.

Nothing in the cited reference provides a hard upper bound on enumeration time or guarantees that filesystem/provider work cannot occur.

6. Cancellation and completion

This is the clearest NOT_GUARANTEED case.

CancelSynchronousIo:

marks pending synchronous I/O for cancellation;

may allow some operations to continue toward completion;

does not wait for those operations to finish;

requires the caller to determine the eventual completion status.

Microsoft explicitly lists three possible completion outcomes: normal completion, cancellation (ERROR_OPERATION_ABORTED), or another failure.

Therefore there is no documented hard completion deadline in this API, and cancellation cannot be used as evidence that the underlying operation has already stopped.

Bottom line

The six references support specific API-level contracts, but they do not collectively establish the stronger composite invariant described in the question:

metadata-only + no referral + no provider activity + no recall/hydration + no storage-state change + complete finite enumeration + hard cancellation deadline.

For that stronger guarantee, additional contracts would have to be identified for the relevant Windows version, filesystem, network redirector, minifilter/provider, reparse-tag semantics, and access mode. The six cited Win32 pages alone do not provide such a universal guarantee.