{"id":105822,"date":"2021-10-22T07:00:00","date_gmt":"2021-10-22T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105822"},"modified":"2021-10-22T07:17:02","modified_gmt":"2021-10-22T14:17:02","slug":"20211022-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20211022-00\/?p=105822","title":{"rendered":"Renaming a file is a multi-step process, only one of which is changing the name of the file"},"content":{"rendered":"

A customer reported that the Read\u00adDirectory\u00adChangesW<\/code> function was reporting changes too soon. No, it wasn’t generating changes from the future, \u00e0 la<\/i> Minority Report<\/a><\/i>. Rather, it generated rename notifications before the rename was complete.<\/p>\n

The customer came to this conclusion because they observed their program behaving like this:<\/p>\n\n\n\n\n\n\n\n\n\n
Thread 1<\/th>\nThread 2<\/th>\n<\/tr>\n
 <\/td>\nRead\u00adDirectory\u00adChangesW(\n FILE_NOTIFY_CHANGE_FILE_NAME)<\/code>.<\/td>\n<\/tr>\n
Call Move\u00adFile\u00adEx<\/code> to rename a file.<\/td>\n <\/td>\n<\/tr>\n
 <\/td>\nRead\u00adDirectory\u00adChangesW<\/code> reports a rename occurred.<\/td>\n<\/tr>\n
 <\/td>\nTries to read the renamed file and gets ERROR_SHARING_VIOLATION<\/code>.<\/td>\n<\/tr>\n
Move\u00adFile\u00adEx<\/code> returns.<\/td>\n <\/td>\n<\/tr>\n
 <\/td>\nTries to read the renamed file and succeeds.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

The Read\u00adDirectory\u00adChangesW<\/code> function reports the rename before the Move\u00adFile\u00adEx<\/code> function returns, and consequently before the rename has completed.<\/p>\n

What’s going on here?<\/p>\n

Well, the first thing to observe is that the customer’s conclusion doesn’t match the evidence. Observe that the attempt to open the renamed file failed with ERROR_SHARING_VIOLATION<\/code>, whereas they expected error would be ERROR_FILE_NOT_FOUND<\/code> if the file hadn’t been renamed yet. The fact that they’re getting ERROR_SHARING_VIOLATION<\/code> means that the rename really did occur<\/i>, but they are unable to access the renamed file due to a sharing violation.<\/p>\n

Okay, let’s look at how renaming a file is performed internally. It’s a multi-step operation.<\/p>\n

    \n
  1. Open the file with DELETE<\/code> permission.<\/li>\n
  2. Call Nt\u00adSet\u00adInformation\u00adFile<\/code><\/a> with File\u00adRename\u00adInformation<\/code>.<\/li>\n
  3. Close the handle.<\/li>\n<\/ol>\n

    Opening with DELETE<\/code> permission grants permission to rename the file. The required permission is DELETE<\/code> because the old name is being deleted.<\/p>\n

    The call with File\u00adRename\u00adInformation<\/code> is what actually renames the file, and it is here that the Read\u00adDirectory\u00adChangesW<\/code> is signaled.<\/p>\n

    Now that the rename is complete, the handle can be closed.<\/p>\n

    It is technically correct for the Read\u00adDirectory\u00adChangesW<\/code> to be signaled once the Nt\u00adSet\u00adInformation\u00adFile<\/code> is done, because the file is well and truly renamed.<\/p>\n

    Let’s look at that sharing violation again. The customer explained that they tried to open the file by doing this:<\/p>\n

    std::ifstream file(path, std::ios::binary, _SH_DENYNO);\r\n<\/pre>\n
    The _SH_DENYNO<\/code> indicates that no sharing operations are denied. So why is sharing denied?<\/p>\n
    You were faked out by a flag name that makes sense in context, but has ended up being confusing due to the passage of time.<\/p>\n
    Let’s  look at those sharing flags<\/a> in context:<\/p>\n\n\n\n\n\n\n\n
    Flag<\/th>\nMeaning<\/th>\nMnemonic<\/th>\n<\/tr>\n
    _SH_DENYRD<\/code><\/td>\nDeny read, allow write.<\/td>\nDeny read.<\/td>\n<\/tr>\n
    _SH_DENYWR<\/code><\/td>\nAllow read, deny write.<\/td>\nDeny write.<\/td>\n<\/tr>\n
    _SH_DENYRW<\/code><\/td>\nDeny read, deny write.<\/td>\nDeny read and write.<\/td>\n<\/tr>\n
    _SH_DENYNO<\/code><\/td>\nAllow read, allow write.<\/td>\nDeny none.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    The mnemonic for _SH_DENY\u00adNO<\/code> is “Deny none”, but the word “none” is only with the context of read and write. You could say that it denies  neither country nor<\/i> western<\/a>.<\/p>\n
    The important sharing mode here is neither read nor write. It’s FILE_SHARE_DELETE<\/code>, which means “I’m okay with letting someone delete or rename the file while I have it open.”\u00b9 This is a sharing flag that programs really should be using more often than they do, and the fact that the C runtime doesn’t give you an easy way to set this sharing flag may be a contributing factor.<\/p>\n
    If you call the Create\u00adFile<\/code> function directly, then you can pass the FILE_SHARE_DELETE<\/code> sharing flag, and then you’ll be able to open the file even before Move\u00adFile\u00adEx<\/code> cleans up its handle.<\/p>\n
    “So why not have Read\u00adDirectory\u00adChangesW<\/code> wait until the handle is closed before raising the rename notification?”<\/p>\n
    Well, for one thing, the file really has been renamed as soon as the Nt\u00adSet\u00adInformation\u00adFile<\/code> is complete, so delaying the notification would be a little disingenuous. But seeing as it’s just a small delay, maybe that’s okay, seeing as the whole thing is a notification anyway, and notifications can be delayed for other reasons.<\/p>\n
    But the real reason is that delaying the notification until the close of the handle could delay it indefinitely. The caller is not required to close the handle immediately after the Nt\u00adSet\u00adInformation\u00adFile<\/code> returns. It could leave the handle open so it can perform other operations on the file. For example, maybe it’s a log file that is being renamed while it is still being actively written to. That log file’s new name takes effect immediately, but the handle won’t be closed for a long time yet.<\/p>\n
    The customer confirmed that switching to a direct Create\u00adFile<\/code> with FILE_SHARE_DELETE<\/code> allowed them to open and read the file immediately after it was renamed.<\/p>\n
    Moral of the story: Don’t forget FILE_SHARE_DELETE<\/code>. It lets you coexist with code that is deleting or renaming the file you are looking at.<\/p>\n
    \u00b9 My colleague Malcolm Smith, whom I rely on for all things filesystem, notes that the name FILE_SHARE_DELETE<\/code> is rather misleading. Because the fact that you opened the file for FILE_SHARE_DELETE<\/code> prevents it from being deleted, even though you’re allowing it! In Windows, when you mark a file for deletion, the deletion doesn’t take effect until all outstanding handles are closed, and holding a file open for FILE_SHARE_DELETE<\/code> means that the last handle isn’t closed yet. What FILE_SHARE_DELETE<\/code> does is allow the file to be opened by others in DELETE<\/code> mode, which as it happens is a prerequisite for both deleting and renaming files.<\/p>\n","protected":false},"excerpt":{"rendered":"
    If you’re going to swoop in, make sure to swoop in carefully.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-105822","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
    If you’re going to swoop in, make sure to swoop in carefully.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105822","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=105822"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105822\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=105822"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105822"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105822"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}