sdlCopyFile function

bool sdlCopyFile(String? oldpath, String? newpath)

Copy a file.

If the file at newpath already exists, it will be overwritten with the contents of the file at oldpath.

This function will block until the copy is complete, which might be a significant time for large files on slow disks. On some platforms, the copy can be handed off to the OS itself, but on others SDL might just open both paths, and read from one and write to the other.

Note that this is not an atomic operation! If something tries to read from newpath while the copy is in progress, it will see an incomplete copy of the data, and if the calling thread terminates (or the power goes out) during the copy, newpath's previous contents will be gone, replaced with an incomplete copy of the data. To avoid this risk, it is recommended that the app copy to a temporary file in the same directory as newpath, and if the copy is successful, use SDL_RenamePath() to replace newpath with the temporary file. This will ensure that reads of newpath will either see a complete copy of the data, or it will see the pre-copy state of newpath.

This function attempts to synchronize the newly-copied data to disk before returning, if the platform allows it, so that the renaming trick will not have a problem in a system crash or power failure, where the file could be renamed but the contents never made it from the system file cache to the physical disk.

If the copy fails for any reason, the state of newpath is undefined. It might be half a copy, it might be the untouched data of what was already there, or it might be a zero-byte file, etc.

\param oldpath the old path. \param newpath the new path. \returns true on success or false on failure; call SDL_GetError() for more information.

\since This function is available since SDL 3.1.3.

extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath)

Implementation

bool sdlCopyFile(String? oldpath, String? newpath) {
  final sdlCopyFileLookupFunction = libSdl3.lookupFunction<
      Uint8 Function(Pointer<Utf8> oldpath, Pointer<Utf8> newpath),
      int Function(
          Pointer<Utf8> oldpath, Pointer<Utf8> newpath)>('SDL_CopyFile');
  final oldpathPointer = oldpath != null ? oldpath.toNativeUtf8() : nullptr;
  final newpathPointer = newpath != null ? newpath.toNativeUtf8() : nullptr;
  final result = sdlCopyFileLookupFunction(oldpathPointer, newpathPointer) == 1;
  calloc.free(oldpathPointer);
  calloc.free(newpathPointer);
  return result;
}