filesystem: Improve docs, make some promises about overwrites and file caches.

Note that SDL_FlushIO() doesn't make promises about file data sync but that
is intended to be changed in the IOStream code in a later commit.

Fixes #10886.

src/filesystem/posix/SDL_sysfsops.c

@@ -121,7 +121,12 @@ bool SDL_SYS_CopyFile(const char *oldpath, const char *newpath)
     SDL_CloseIO(input);
     input = NULL;
 
+    if (!SDL_FlushIO(output)) {
+        goto done;
+    }
+
     if (!SDL_CloseIO(output)) {
+        output = NULL;  // it's gone, even if it failed.
         goto done;
     }
     output = NULL;