util

Documentation

Overview

Package util provides utility functions for interacting with filesystems.

Index

• Constants
• Variables
• func Atomic(path string, fn func(path string) error) error
• func CopyFile(source, sink string) error
• func CopyFileRangeTo(path string, offset, length int64, writer io.Writer) error
• func CopyFileTo(path string, writer io.Writer) error
• func Create(path string) (*os.File, error)
• func CreateFile(path string, flags int, mode os.FileMode) (*os.File, error)
• func DirExists(path string) (bool, error)
• func FileExists(path string) (bool, error)
• func FileSize(path string) (uint64, error)
• func Mkdir(path string, mode os.FileMode, parents, ignoreExists bool) error
• func OpenRandAccess(path string, start, end int64) (*os.File, error)
• func OpenSeqAccess(path string, start, end int64) (*os.File, error)
• func ReadIfProvided(path string) ([]byte, error)
• func ReadJSONFile(path string, data any) error
• func Remove(path string, ignoreNotExists bool) error
• func RemoveAll(path string) error
• func Sync(path string) error
• func Touch(path string) error
• func WriteAt(path string, data []byte, offset int64) error
• func WriteFile(path string, data []byte, mode os.FileMode) error
• func WriteJSONFile(path string, data any, mode os.FileMode) error
• func WriteTempFile(dir string, data []byte) (string, error)
• func WriteToFile(path string, reader io.Reader, mode os.FileMode) error

Constants

const (
	// DefaultFileMode represents the default file mode which will be used if a zero value file mode is provided for
	// operations which create new files.
	DefaultFileMode os.FileMode = 0o660

	// DefaultDirMode represents the default file mode which will be used if a zero value file mode is provided for
	// operations which create new directories.
	DefaultDirMode os.FileMode = 0o770
)

Variables

var (
	// ErrNotFile is returned by 'FileExists' if a directory exists at the provided path.
	ErrNotFile = errors.New("not a file")

	// ErrNotDir is returned by 'DirExists' if a file exists at the provided path.
	ErrNotDir = errors.New("not a directory")
)

Functions

func Atomic

func Atomic(path string, fn func(path string) error) error

Atomic will perform the provided function in an "atmoic" fashion. It's required that the provided function create the file at the given path if it doesn't already exist.

NOTE: This only works to the degree that the underlying operating system guarantees that renames are atomic.

func CopyFile

func CopyFile(source, sink string) error

CopyFile copies the source file to the sink file truncating it if it already exists.

NOTE: The sink file will be given the same permissions as the source file.

func CopyFileRangeTo

func CopyFileRangeTo(path string, offset, length int64, writer io.Writer) error

CopyFileRangeTo is similar to 'CopyFileTo' but allows specifying an offset/length.

func CopyFileTo

func CopyFileTo(path string, writer io.Writer) error

CopyFileTo copies all the data from the file at the provided path into the given writer.

func Create

func Create(path string) (*os.File, error)

Create a new file at the provided path in read/write mode, any existing file will be truncated when opening.

func CreateFile

func CreateFile(path string, flags int, mode os.FileMode) (*os.File, error)

CreateFile creates a new file (or truncates an existing one) at the provided path using the given flags/mode.

NOTE: If a zero value file mode is suppled, the default will be used.

func DirExists

func DirExists(path string) (bool, error)

DirExists returns a boolean indicating whether a directory at the provided path exists.

func FileExists

func FileExists(path string) (bool, error)

FileExists returns a boolean indicating whether a file at the provided path exists.

func FileSize

func FileSize(path string) (uint64, error)

FileSize returns the size in bytes of the file at the provided path.

func Mkdir

func Mkdir(path string, mode os.FileMode, parents, ignoreExists bool) error

Mkdir creates a new directory with the provided mode and may optionally create all parent directories.

NOTE: If a zero value file mode is suppled, the default will be used.

func OpenRandAccess

func OpenRandAccess(path string, start, end int64) (*os.File, error)

OpenRandAccess opens the provided file whilst advising the kernel that we'll be accessing the byte range from start to end with a random access pattern; this should decrease the pre-fetch amount and avoid bloating the page cache with data that we'll only be using once. If a zero start/end is provided kernels after 2.6.6 will treat this as "all the bytes through to the end of the file".

NOTE: This is advise to the kernel, the kernel provides no guarantees that it will honor/action the advise.

func OpenSeqAccess

func OpenSeqAccess(path string, start, end int64) (*os.File, error)

OpenSeqAccess opens the provided file whilst advising the kernel that we'll be accessing the byte range from start to end sequentially; this should increase the pre-fetch amount for this file. If a zero start/end is provided kernels after 2.6.6 will treat this as "all the bytes through to the end of the file".

NOTE: This is advise to the kernel, the kernel provides no guarantees that it will honor/action the advise.

func ReadIfProvided

func ReadIfProvided(path string) ([]byte, error)

ReadIfProvided is the equvilent to 'os.ReadFile' but will return <nil>, <nil> if no path is provided.

func ReadJSONFile

func ReadJSONFile(path string, data any) error

ReadJSONFile unmarshals data from the provided file into the given interface.

func Remove

func Remove(path string, ignoreNotExists bool) error

Remove the file/directory at the given path.

func RemoveAll

func RemoveAll(path string) error

RemoveAll removes all the files/directories at the provided path.

func Sync

func Sync(path string) error

Sync the provided file to disk.

func Touch

func Touch(path string) error

Touch is analogous to the unix 'touch' command, it updates the access/modified times of the file at the provided path creating it if it doesn't exist.

func WriteAt

func WriteAt(path string, data []byte, offset int64) error

WriteAt writes data to the given offset in the file at the provided path.

NOTE: The file at the given path must already exist.

func WriteFile

func WriteFile(path string, data []byte, mode os.FileMode) error

WriteFile writes out the provided data to the file at the given path.

func WriteJSONFile

func WriteJSONFile(path string, data any, mode os.FileMode) error

WriteJSONFile marshals the provided interface and writes it to a file at the given path.

func WriteTempFile

func WriteTempFile(dir string, data []byte) (string, error)

WriteTempFile writes out the provided data to a temporary file in the given directory (OS temporary directory if omitted) and returns the path to that file.

NOTE: It's the job of the caller to correctly handle cleaning up the file.

func WriteToFile

func WriteToFile(path string, reader io.Reader, mode os.FileMode) error

WriteToFile copies all the data from the provided reader and writes it to the file at the given path.