atomicMoveTo

fun Path.atomicMoveTo(target: Path): Path

Moves this path to target, replacing target if it already exists.

The move is performed atomically when the platform and file stores allow it (StandardCopyOption.ATOMIC_MOVE). If an atomic replace is not supported (for example when source and target are on different file stores) or the implementation refuses to replace an existing target under ATOMIC_MOVE, the operation falls back to a non-atomic REPLACE_EXISTING move.

The fallback is not crash-safe: a failure or interruption in the middle may leave target deleted, truncated, or otherwise inconsistent. Callers that require an all-or-nothing replace must keep source and target on the same file store and treat AtomicMoveNotSupportedException as fatal instead of using this helper.

Replacing a non-empty directory is not supported and still fails with java.nio.file.DirectoryNotEmptyException or another IOException.

Return

target

Throws

if the move fails

if the security manager denies the operation