Sync SDL3 wiki -> header
This commit is contained in:
@@ -308,8 +308,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path);
|
|||||||
* Note that this will not copy files across filesystems/drives/volumes, as
|
* Note that this will not copy files across filesystems/drives/volumes, as
|
||||||
* that is a much more complicated (and possibly time-consuming) operation.
|
* that is a much more complicated (and possibly time-consuming) operation.
|
||||||
*
|
*
|
||||||
* Which is to say, if this function fails, SDL_CopyFile() to a temporary
|
* Which is to say, if this function fails, SDL_CopyFile() to a temporary file
|
||||||
* file in the same directory as `newpath`, then SDL_RenamePath() from the
|
* in the same directory as `newpath`, then SDL_RenamePath() from the
|
||||||
* temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work
|
* temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work
|
||||||
* for files. Renaming a non-empty directory across filesystems is
|
* for files. Renaming a non-empty directory across filesystems is
|
||||||
* dramatically more complex, however.
|
* dramatically more complex, however.
|
||||||
@@ -330,26 +330,25 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char
|
|||||||
* contents of the file at `oldpath`.
|
* contents of the file at `oldpath`.
|
||||||
*
|
*
|
||||||
* This function will block until the copy is complete, which might be a
|
* 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
|
* significant time for large files on slow disks. On some platforms, the copy
|
||||||
* copy can be handed off to the OS itself, but on others SDL might just open
|
* can be handed off to the OS itself, but on others SDL might just open both
|
||||||
* both paths, and read from one and write to the other.
|
* paths, and read from one and write to the other.
|
||||||
*
|
*
|
||||||
* Note that this is not an atomic operation! If something tries to read from
|
* 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
|
* `newpath` while the copy is in progress, it will see an incomplete copy of
|
||||||
* of the data, and if the calling thread terminates (or the power goes out)
|
* the data, and if the calling thread terminates (or the power goes out)
|
||||||
* during the copy, `oldpath`'s previous contents will be gone, replaced with
|
* during the copy, `oldpath`'s previous contents will be gone, replaced with
|
||||||
* an incomplete copy of the data. To avoid this risk, it is recommended that
|
* 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
|
* the app copy to a temporary file in the same directory as `newpath`, and if
|
||||||
* if the copy is successful, use SDL_RenamePath() to replace `newpath` with
|
* the copy is successful, use SDL_RenamePath() to replace `newpath` with the
|
||||||
* the temporary file. This will ensure that reads of `newpath` will either
|
* temporary file. This will ensure that reads of `newpath` will either see a
|
||||||
* see a complete copy of the data, or it will see the pre-copy state of
|
* complete copy of the data, or it will see the pre-copy state of `newpath`.
|
||||||
* `newpath`.
|
|
||||||
*
|
*
|
||||||
* This function attempts to synchronize the newly-copied data to disk before
|
* 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
|
* 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
|
* have a problem in a system crash or power failure, where the file could be
|
||||||
* be renamed but the contents never made it from the system file cache to
|
* renamed but the contents never made it from the system file cache to the
|
||||||
* the physical disk.
|
* physical disk.
|
||||||
*
|
*
|
||||||
* If the copy fails for any reason, the state of `newpath` is undefined. It
|
* 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
|
* might be half a copy, it might be the untouched data of what was already
|
||||||
|
|||||||
Reference in New Issue
Block a user