package renameio

import "github.com/google/renameio"

Package renameio provides a way to atomically create or replace a file or symbolic link.

Caveat: this package requires the file system rename(2) implementation to be atomic. Notably, this is not the case when using NFS with multiple clients: https://stackoverflow.com/a/41396801

Index ¶

• func Symlink(oldname, newname string) error
• func TempDir(dest string) string
• func WriteFile(filename string, data []byte, perm os.FileMode) error
• type PendingFile
• func TempFile(dir, path string) (*PendingFile, error)
• func (t *PendingFile) Cleanup() error
• func (t *PendingFile) CloseAtomicallyReplace() error

Examples ¶

• TempFile (Justone)
• TempFile (Many)

Functions ¶

func Symlink ¶

func Symlink(oldname, newname string) error

Symlink wraps os.Symlink, replacing an existing symlink with the same name atomically (os.Symlink fails when newname already exists, at least on Linux).

func TempDir ¶

func TempDir(dest string) string

TempDir checks whether os.TempDir() can be used as a temporary directory for later atomically replacing files within dest. If no (os.TempDir() resides on a different mount point), dest is returned.

Note that the returned value ceases to be valid once either os.TempDir() changes (e.g. on Linux, once the TMPDIR environment variable changes) or the file system is unmounted.

func WriteFile ¶

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

WriteFile mirrors ioutil.WriteFile, replacing an existing file with the same name atomically.

Types ¶

type PendingFile ¶

type PendingFile struct {
	*os.File
	// contains filtered or unexported fields
}

PendingFile is a pending temporary file, waiting to replace the destination path in a call to CloseAtomicallyReplace.

func TempFile ¶

func TempFile(dir, path string) (*PendingFile, error)

TempFile wraps ioutil.TempFile for the use case of atomically creating or replacing the destination file at path.

If dir is the empty string, TempDir(filepath.Base(path)) is used. If you are going to write a large number of files to the same file system, store the result of TempDir(filepath.Base(path)) and pass it instead of the empty string.

The file's permissions will be 0600 by default. You can change these by explicitly calling Chmod on the returned PendingFile.

package main

import (
	"fmt"
	"log"

	"github.com/google/renameio"
)

func main() {
	persist := func(temperature float64) error {
		t, err := renameio.TempFile("", "/srv/www/metrics.txt")
		if err != nil {
			return err
		}
		defer t.Cleanup()
		if _, err := fmt.Fprintf(t, "temperature_degc %f\n", temperature); err != nil {
			return err
		}
		return t.CloseAtomicallyReplace()
	}
	// Thanks to the write package, a webserver exposing /srv/www never
	// serves an incomplete or missing file.
	if err := persist(31.2); err != nil {
		log.Fatal(err)
	}
}

package main

import (
	"fmt"
	"log"

	"github.com/google/renameio"
)

func main() {
	// Prepare for writing files to /srv/www, effectively caching calls to
	// TempDir which TempFile would otherwise need to make.
	dir := renameio.TempDir("/srv/www")
	persist := func(temperature float64) error {
		t, err := renameio.TempFile(dir, "/srv/www/metrics.txt")
		if err != nil {
			return err
		}
		defer t.Cleanup()
		if _, err := fmt.Fprintf(t, "temperature_degc %f\n", temperature); err != nil {
			return err
		}
		return t.CloseAtomicallyReplace()
	}

	// Imagine this was an endless loop, reading temperature sensor values.
	// Thanks to the write package, a webserver exposing /srv/www never
	// serves an incomplete or missing file.
	for {
		if err := persist(31.2); err != nil {
			log.Fatal(err)
		}
	}
}

func (*PendingFile) Cleanup ¶

func (t *PendingFile) Cleanup() error

Cleanup is a no-op if CloseAtomicallyReplace succeeded, and otherwise closes and removes the temporary file.

This method is not safe for concurrent use by multiple goroutines.

func (*PendingFile) CloseAtomicallyReplace ¶

func (t *PendingFile) CloseAtomicallyReplace() error

CloseAtomicallyReplace closes the temporary file and atomically replaces the destination file with it, i.e., a concurrent open(2) call will either open the file previously located at the destination path (if any), or the just written file, but the file will always be present.

This method is not safe for concurrent use by multiple goroutines.

Source Files ¶

doc.go tempfile.go writefile.go

Directories ¶