Why does std::filesystem::copy_file() ignore the create_hard_links option flag?

I am writing a function to copy large binary images around. I first try to copy them by hard link. If that fails, then I fallback to copying them normally.

I initially wrote the function to use std::filesystem::copy_file(), like this:

public bool CopyLargeStaticFile(const path& source, const path& dest)
{
    // First try a hard-link.

    std::error_code ec;
    copy_file(source, dest, copy_options::create_hard_links, ec);

    if (ec)
    {
        // On error, fall-back to a regular copy.  When copying to a different
        // disk, I would expect this error but it does not happen because copy_file
        // ignores the 'create_hard_links' flag and just makes a regular copy

        ec.clear();
        copy_file(source, dest, ec);
    }

    return !ec;
}

But then I discovered that the create_hard_link flag is not honored when you call copy_file. If you want it to be honored, you must instead call filesystem::copy.

Does anyone know why? Is there some technical reason? Is it an oversight of the filesystem spec? Something wrong with the Visual Studio implementation? It just makes no sense to me.

Editing to add: After I discovered this, I did come across the mention in the copy_options enum that the flag only applies to copy(). Just don't understand the "why" of it.

If you look at the C++ standard for copy_options, you'll see that create_hard_links is designed to only affect copy() and not copy_file(). If you look at Microsoft's implementation of copy_file(), you'll see that it only looks at the bits of copy_options that are part of the "what to do with existing files" logic.

So unfortunately for you, Microsoft's STL follows the standard here, and what you're trying to do simply won't work.

Technically you're even skirting around undefined behavior here:

> The behavior is undefined if there is more than one option in any of the copy_options option group present in options (even in the groups not relevant to filesystem::copy_file)

Since you only specify create_hard_links you're still technically not invoking UB (and Microsoft's implementation would be lenient here anyway), but it simply won't have any effect.

I don't know for sure, but my guess is that the reasoning here would be that copy_file is designed to explicitly copy the contents of a file (and not care about fancy filesystem features), while copy is a higher-level routine. (The standard itself says that copy may call copy_file in some cases.)

Hence, if you want hard links, simply use copy.