osutil

Documentation

Overview

OS-related utilities

Small wrappers for dealing with ENV vars

Wrapper for doing "file exists" -dance in Go (which has a bit too much ceremony)

Writes a file to FS using temp-filename scheme, so destination filename should only appear when file write is atomically "ok"

Index

• Constants
• func CancelOnInterruptOrTerminate(logger *log.Logger) context.Context
• func CopyFile(sourcePath string, destinationPath string) error
• func CreateEmptyFile(path string) error
• func DirectoryAtomicOperationByRename(path string, operations func(pathTemp string) error) error
• func Exists(path string) (bool, error)
• func ExistsNoLinkFollow(path string) (bool, error)
• func ExitIfError(err error)
• func FileAtomicOperationByRename(path string, operations func(pathTemp string) error) error
• func FileMode(owner ownerBits, group groupBits, other otherBits) os.FileMode
• func GetenvRequired(key string) (string, error)
• func GetenvRequiredFromBase64(key string) ([]byte, error)
• func MoveFile(sourcePath string, destinationPath string) error
• func ParseEnv(serialized string) (string, string)
• func WriteFileAtomic(filename string, produce func(io.Writer) error, options ...WriteFileOption) error
• func WriteFileAtomicFromReader(filename string, content io.Reader, options ...WriteFileOption) error
• type WriteFileOption
  • func WriteFileChown(uid int, gid int) WriteFileOption
  • func WriteFileChownAndIgnoreIfErrors(uid int, gid int) WriteFileOption
  • func WriteFileIfSudoPreserveInvokingUsersUIDAndGID() WriteFileOption
  • func WriteFileMode(mode fs.FileMode) WriteFileOption
  • func WriteFileTimes(atime time.Time, mtime time.Time, ctime time.Time) WriteFileOption
  • func WriteFileXattrUser(key string, value []byte) WriteFileOption

Constants

const (
	// owner means "user", but I chose to go against the flow because it's more semantic
	OwnerNone ownerBits = 0b000000000
	OwnerR    ownerBits = 0b100000000
	OwnerRX   ownerBits = 0b101000000
	OwnerRW   ownerBits = 0b110000000
	OwnerRWX  ownerBits = 0b111000000

	GroupNone groupBits = 0b000000000
	GroupR    groupBits = 0b000100000
	GroupRX   groupBits = 0b000101000
	GroupRW   groupBits = 0b000110000
	GroupRWX  groupBits = 0b000111000

	OtherNone otherBits = 0b000000000
	OtherR    otherBits = 0b000000100
	OtherRX   otherBits = 0b000000101
	OtherRW   otherBits = 0b000000110
	OtherRWX  otherBits = 0b000000111
)

leaving out combinations that semantically don't make sense: (X), (W,X) - execute without read (W) - write without read

Functions

func CancelOnInterruptOrTerminate

func CancelOnInterruptOrTerminate(logger *log.Logger) context.Context

makes (background-derived) context that cancels on SIGINT ("Ctrl + c") or SIGTERM. it stops signal listening on first received signal, so that if user sends next signal (teardown maybe stuck?), it terminates the process immediately.

TODO: will signal.NotifyContext() cover our needs?

func CopyFile

func CopyFile(sourcePath string, destinationPath string) error

tries its best to preserve metadata like file permissions & timestamps

func CreateEmptyFile

func CreateEmptyFile(path string) error

does the same as "$ touch"

func DirectoryAtomicOperationByRename

func DirectoryAtomicOperationByRename(path string, operations func(pathTemp string) error) error

func Exists

func Exists(path string) (bool, error)

https://stackoverflow.com/questions/12518876/how-to-check-if-a-file-exists-in-go follows symlinks

func ExistsNoLinkFollow

func ExistsNoLinkFollow(path string) (bool, error)

func ExitIfError

func ExitIfError(err error)

if "err" is non-nil, exits with exit code 1 and prints the given error to stderr

intended to be ran once from program's entrypoint / main function

this abstraction seems silly, but I've written this so many times, and some of the times wrong (stdout instead of stderr), that maybe it's better to write this properly once

func FileAtomicOperationByRename

func FileAtomicOperationByRename(path string, operations func(pathTemp string) error) error

- ensures a file with given name only appears on the filesystem if all its file operations succeed - tries to clean up temp file on failure of *operations* or the atomic rename

func FileMode

func FileMode(owner ownerBits, group groupBits, other otherBits) os.FileMode

typesafe interface for specifying "chmod bits" in human readable way

func GetenvRequired

func GetenvRequired(key string) (string, error)

func GetenvRequiredFromBase64

func GetenvRequiredFromBase64(key string) ([]byte, error)

func MoveFile

func MoveFile(sourcePath string, destinationPath string) error

first tries by renaming, if that errors falls back to copying (so it works across filesystems)

func ParseEnv

func ParseEnv(serialized string) (string, string)

func WriteFileAtomic

func WriteFileAtomic(filename string, produce func(io.Writer) error, options ...WriteFileOption) error

- creates a <filename>.part file to write to - write all requested content to it (content produced by callback) - rename temp filename to filename if everything went OK

If encountering any errors, removes the partial file

func WriteFileAtomicFromReader

func WriteFileAtomicFromReader(filename string, content io.Reader, options ...WriteFileOption) error

helper for the most common case of pumping content to file from a reader

Types

type WriteFileOption

type WriteFileOption func(opt *writeFileOptions)

func WriteFileChown

func WriteFileChown(uid int, gid int) WriteFileOption

func WriteFileChownAndIgnoreIfErrors

func WriteFileChownAndIgnoreIfErrors(uid int, gid int) WriteFileOption

same as WriteFileChown() but if copying to filesystem that doesn't support Chown(), we'll get an error which we'll ignore

func WriteFileIfSudoPreserveInvokingUsersUIDAndGID

func WriteFileIfSudoPreserveInvokingUsersUIDAndGID() WriteFileOption

if running under '$ sudo', set the sudo-invoking "original" user as the UID & GID

func WriteFileMode

func WriteFileMode(mode fs.FileMode) WriteFileOption

func WriteFileTimes

func WriteFileTimes(atime time.Time, mtime time.Time, ctime time.Time) WriteFileOption

warning: ctime is ignored for now

func WriteFileXattrUser

func WriteFileXattrUser(key string, value []byte) WriteFileOption

write an extended attribute, in user namespace. See https://man7.org/linux/man-pages/man7/xattr.7.html