replacefile

Documentation

Overview

Package replacefile is a small helper package focused directly at the problem of atomically "renaming" one file over another one.

On Unix systems this is the standard behavior of the rename function, but the equivalent operation on Windows requires some specific operation flags which this package encapsulates.

This package uses conditional compilation to select a different implementation for Windows vs. all other platforms. It may therefore require further fiddling in future if OpenTofu is ported to another OS that is neither Unix-like nor Windows.

Index

• func AtomicRename(source, destination string) error
• func AtomicWriteFile(filename string, data []byte, perm os.FileMode) error

Functions

func AtomicRename

func AtomicRename(source, destination string) error

AtomicRename renames from the source path to the destination path, atomically replacing any file that might already exist at the destination.

Typically this operation can succeed only if the source and destination are within the same physical filesystem, so this function is best reserved for cases where the source and destination exist in the same directory and only the local filename differs between them.

The Unix implementation of AtomicRename relies on the atomicity of renaming that is required by the ISO C standard, which in turn assumes that Go's implementation of rename is calling into a system call that preserves that guarantee.

func AtomicWriteFile

func AtomicWriteFile(filename string, data []byte, perm os.FileMode) error

AtomicWriteFile uses a temporary file along with this package's AtomicRename function in order to provide a replacement for ioutil.WriteFile that writes the given file into place as atomically as the underlying operating system can support.

The sense of "atomic" meant by this function is that the file at the given filename will either contain the entirety of the previous contents or the entirety of the given data array if opened and read at any point during the execution of the function.

On some platforms attempting to overwrite a file that has at least one open filehandle will produce an error. On other platforms, the overwriting will succeed but existing open handles will still refer to the old file, even though its directory entry is no longer present.

Although AtomicWriteFile tries its best to avoid leaving behind its temporary file on error, some particularly messy error cases may result in a leftover temporary file.