fileutil

Documentation

Index

• func AtomicWrite(path string, data []byte, perm os.FileMode) error
• func AtomicWriteExclusive(path string, data []byte, perm os.FileMode) error
• func AtomicWriteJSON(path string, v any, perm os.FileMode) error
• func AtomicWriteStream(path string, src io.Reader, perm os.FileMode) error
• type FileLock
  • func NewFileLock(targetPath string) (*FileLock, error)
  • func (l *FileLock) Unlock()

Functions

func AtomicWrite

func AtomicWrite(path string, data []byte, perm os.FileMode) error

AtomicWrite writes data to path via a temporary file + rename for crash safety. The perm argument sets the final file permissions (e.g. 0644 for docs, 0755 for hooks).

func AtomicWriteExclusive

func AtomicWriteExclusive(path string, data []byte, perm os.FileMode) error

AtomicWriteExclusive writes data to path via a temporary file + hard link. Unlike AtomicWrite, it fails if path already exists (returns an error where os.IsExist reports true). This avoids the TOCTOU race inherent in Stat-then-Rename patterns.

func AtomicWriteJSON

func AtomicWriteJSON(path string, v any, perm os.FileMode) error

AtomicWriteJSON marshals v as indented JSON and writes it to path via writeAtomicDurable. Used for state files where the indented form is worth the handful of extra bytes for human diff-ability. Returns a non-nil error if marshaling fails; the target file is left unchanged in that case.

func AtomicWriteStream

func AtomicWriteStream(path string, src io.Reader, perm os.FileMode) error

AtomicWriteStream streams src into path via writeAtomicDurable. Used by backup/restore where the source is an already-open file and buffering the full contents into memory would be wasteful.

Types

type FileLock

type FileLock struct {
	// contains filtered or unexported fields
}

FileLock holds an exclusive advisory lock on a side-car `.lock` file. Created via NewFileLock and released with Unlock. Not safe for concurrent use by multiple goroutines within a process; the caller should serialize access.

func NewFileLock

func NewFileLock(targetPath string) (*FileLock, error)

NewFileLock creates (or opens) a `<target>.lock` file next to the supplied target path and takes an exclusive advisory lock on it. Callers MUST defer Unlock to release the lock and close the fd.

The lock file is never removed so concurrent processes that race to create it cannot accidentally delete a file another process holds. The lock file contains nothing; only its inode participates in the flock contract.

func (*FileLock) Unlock

func (l *FileLock) Unlock()

Unlock releases the advisory lock and closes the file descriptor. Safe to call multiple times; the second call is a no-op via sync.Once.