atomicfile

README

atomicfile

Linux command to atomically create fully-formed files with contents read from stdin.

# Atomically create a file called hello.txt with the contents passed on stdin
echo 'Hello world!' | atomicfile hello.txt

# Atomically copy a file (also across filesystems)
atomicfile destination.file </some/other/filesystem/source.file

Files are always created atomically using O_TMPFILE/linkat, so any other process in the system can not observe the file in an incomplete state (this includes all aspects of the file specified as flags to the command, such as xattrs, permissions, owner, etc.).

In addition, the same functionality is exposed as a Go library:

// atomically create a file with contents read from the provided io.Reader r
err := atomicfile.Create(filename, atomicfile.Contents(r))
if err != nil {
  panic(err)
}

Install

go install github.com/CAFxX/atomicfile/cmd/atomicfile@latest

Usage

usage: atomicfile [<flags>] <filename>

Flags:
  --help                 Show context-sensitive help (also try --help-long and --help-man).
  --fsync                Fsync the file
  --prealloc=0           Preallocate file space (bytes)
  --xattr=KEY=VALUE ...  Extended attributes to be added to the file
  --perm=PERM            File permissions
  --uid=UID              File owner user
  --gid=GID              File owner group
  --mtime=MTIME          File modification time (RFC 3339)
  --atime=ATIME          File access time (RFC 3339)

Args:
  <filename>  Name of the file to create

Requirements

• atomicfile requires Linux >= 3.11 (for O_TMPFILE).
• Availability of some of the features (preallocating space, extended attributes, ...) depend on the filesystem and kernel version.
• Setting UID/GID normally requires the process to run with elevated privileges (sudo).

Documentation

Index

• func Create(filename string, options ...Option) error
• type Option
  • func AccessTime(t time.Time) Option
  • func Contents(r io.Reader) Option
  • func Fsync() Option
  • func ModificationTime(t time.Time) Option
  • func Ownership(uid, gid int) Option
  • func Permissions(mode os.FileMode) Option
  • func Preallocate(size int64) Option
  • func Xattr(name string, value []byte) Option

Functions

func Create

func Create(filename string, options ...Option) error

Create creates the specified file with the provided options. The file is created atomically in a fully-formed state using O_TMPFILE/linkat. Create fails if the file already exists.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is the interface for options passed to Create.

func AccessTime

func AccessTime(t time.Time) Option

AccessTime specifies the access time of the target file.

func Contents

func Contents(r io.Reader) Option

Contents specifies the contents to be written to the target file.

func Fsync

func Fsync() Option

Fsync enables the invocation of fsync() on the target file and its containing directory.

func ModificationTime

func ModificationTime(t time.Time) Option

ModificationTime specifies the modification time of the target file.

func Ownership

func Ownership(uid, gid int) Option

Ownership specifies the target file owner UID and GID.

func Permissions

func Permissions(mode os.FileMode) Option

Permissions specifies the Unix permissions to be set on the target file.

func Preallocate

func Preallocate(size int64) Option

Preallocate allocates the specified amount of bytes in the target file, regardless of the amount of content written. Not all filesystems and kernel versions support preallocating space.

func Xattr

func Xattr(name string, value []byte) Option

Xattr specifies an extended attribute to be added to the target file. Multiple externded attributes can be added to the same file. Not all filesystems and kernel versions support extended attributes.