.\" This manpage content is licensed under Creative Commons
.\"  Attribution 4.0 International (CC BY 4.0)
.\"   https://creativecommons.org/licenses/by/4.0/
.\" This manpage was generated from SDL's wiki page for SDL_CopyFile:
.\"   https://wiki.libsdl.org/SDL_CopyFile
.\" Generated with SDL/build-scripts/wikiheaders.pl
.\"  revision release-3.2.10-0-g877399b2b
.\" Please report issues in this manpage's content at:
.\"   https://github.com/libsdl-org/sdlwiki/issues/new
.\" Please report issues in the generation of this manpage from the wiki at:
.\"   https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20SDL_CopyFile
.\" SDL can be found at https://libsdl.org/
.de URL
\$2 \(laURL: \$1 \(ra\$3
..
.if \n[.g] .mso www.tmac
.TH SDL_CopyFile 3 "SDL 3.2.10" "Simple Directmedia Layer" "SDL3 FUNCTIONS"
.SH NAME
SDL_CopyFile \- Copy a file\[char46]
.SH HEADER FILE
Defined in SDL3/SDL_filesystem\[char46]h

.SH SYNOPSIS
.nf
.B #include \(dqSDL3/SDL.h\(dq
.PP
.BI "bool SDL_CopyFile(const char *oldpath, const char *newpath);
.fi
.SH DESCRIPTION
If the file at
.BR newpath
already exists, it will be overwritten with the
contents of the file at
.BR oldpath
\[char46]

This function will block until the copy is complete, which might be a
significant time for large files on slow disks\[char46] 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\[char46]

Note that this is not an atomic operation! If something tries to read from
.BR 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,
.BR newpath
's previous contents will be gone, replaced with
an incomplete copy of the data\[char46] To avoid this risk, it is recommended that
the app copy to a temporary file in the same directory as
.BR newpath
, and if
the copy is successful, use 
.BR SDL_RenamePath
() to replace
.BR newpath
with the temporary file\[char46] This will ensure that reads of
.BR newpath
will either see a complete copy of the data, or it will see the pre-copy
state of
.BR newpath
\[char46]

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\[char46]

If the copy fails for any reason, the state of
.BR newpath
is undefined\[char46] 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\[char46]

.SH FUNCTION PARAMETERS
.TP
.I oldpath
the old path\[char46]
.TP
.I newpath
the new path\[char46]
.SH RETURN VALUE
Returns true on success or false on failure; call

.BR SDL_GetError
() for more information\[char46]

.SH AVAILABILITY
This function is available since SDL 3\[char46]2\[char46]0\[char46]