fio

README

go-fio-

optimized file I/O routines - including reflink based copies/clones

Documentation

Index

• Constants
• Variables
• func ClearXattr(nm string) error
• func CloneFile(dst, src string) error
• func CloneMetadata(dst, src string) error
• func CopyFd(dst, src *os.File) error
• func CopyFile(dst, src string, perm fs.FileMode) error
• func DelXattr(nm string, keys ...string) error
• func LclearXattr(nm string) error
• func LdelXattr(nm string, keys ...string) error
• func LreplaceXattr(nm string, x Xattr) error
• func LsetXattr(nm string, x Xattr) error
• func Lstatm(nm string, fi *Info) error
• func ReplaceXattr(nm string, x Xattr) error
• func SetXattr(nm string, x Xattr) error
• func Statm(nm string, fi *Info) error
• func UpdateMetadata(dst string, fi *Info) error
• type Info
  • func Lstat(nm string) (*Info, error)
  • func Stat(nm string) (*Info, error)
  • func (ii *Info) IsDir() bool
  • func (ii *Info) IsRegular() bool
  • func (ii *Info) MarshalSize() int
  • func (ii *Info) MarshalTo(b []byte) (int, error)
  • func (ii *Info) ModTime() time.Time
  • func (ii *Info) Mode() fs.FileMode
  • func (ii *Info) Name() string
  • func (ii *Info) Size() int64
  • func (ii *Info) String() string
  • func (ii *Info) Sys() any
  • func (ii *Info) Unmarshal(b []byte) (int, error)
• type SafeFile
  • func NewSafeFile(nm string, opts uint32, flag int, perm os.FileMode) (*SafeFile, error)
  • func (sf *SafeFile) Abort()
  • func (sf *SafeFile) Close() error
  • func (sf *SafeFile) Write(b []byte) (int, error)
  • func (sf *SafeFile) WriteAt(b []byte, off int64) (int, error)
• type Xattr
  • func GetXattr(nm string) (Xattr, error)
  • func LgetXattr(nm string) (Xattr, error)
  • func (x Xattr) Equal(y Xattr) bool
  • func (x Xattr) String() string

Constants

const (
	OPT_OVERWRITE uint32 = 1 << iota
	OPT_COW
)

Variables

var (
	ErrTooSmall = errors.New("buffer is not big enough")
)

Functions

func ClearXattr

func ClearXattr(nm string) error

ClearXattr deletes all the extended attributes of a file.

func CloneFile

func CloneFile(dst, src string) error

CloneFile copies src to dst - including all copyable file attributes and xattr. CloneFile will use the best available CoW facilities provided by the OS and Filesystem. It will fall back to using copy via mmap(2) on systems that don't have CoW semantics.

func CloneMetadata

func CloneMetadata(dst, src string) error

CloneMetadata clones all the metadata from src to dst: the metadata is atime, mtime, uid, gid, mode/perm, xattr

func CopyFd

func CopyFd(dst, src *os.File) error

CopyFd copies open files 'src' to 'dst' using the most efficient OS primitive available on the runtime platform. CopyFile will use copy-on-write facailities if the underlying file-system implements it. It will fallback to copying via memory mapping 'src' and writing the blocks to 'dst'.

func CopyFile

func CopyFile(dst, src string, perm fs.FileMode) error

CopyFile copies files 'src' to 'dst' using the most efficient OS primitive available on the runtime platform. CopyFile will use copy-on-write facilities if the underlying file-system implements it. It will fallback to copying via memory mapping 'src' and writing the blocks to 'dst'.

func DelXattr

func DelXattr(nm string, keys ...string) error

DelXattr deletes one or more extended attributes of a file.

func LclearXattr

func LclearXattr(nm string) error

ClearXattr deletes all the extended attributes of a file. If 'nm' points to a symlink, LSetXattr will delete the extended attributes of the symlink and *not* the target.

func LdelXattr

func LdelXattr(nm string, keys ...string) error

LDelXattr deletes one or more extended attributes of a file. If 'nm' points to a symlink, LSetXattr will delete the extended attributes of the symlink and *not* the target.

func LreplaceXattr

func LreplaceXattr(nm string, x Xattr) error

LReplaceXattr replaces all the extended attributes of 'nm' with new attributes in 'x'. This function is a combination of LclearXattr() and LsetXattr(). If 'nm' points to a symlink, LReplaceXattr will set/update the extended attributes of the symlink and *not* the target.

func LsetXattr

func LsetXattr(nm string, x Xattr) error

LSetXattr sets/updates the xattr list for a given file. If 'nm' points to a symlink, LSetXattr will set/update the extended attributes of the symlink and *not* the target.

func Lstatm

func Lstatm(nm string, fi *Info) error

Lstatm is like Lstat except it uses the caller's supplied memory.

func ReplaceXattr

func ReplaceXattr(nm string, x Xattr) error

ReplaceXattr replaces all the extended attributes of 'nm' with new attributes in 'x'. This function is a combination of ClearXattr() and SetXattr().

func SetXattr

func SetXattr(nm string, x Xattr) error

SetXattr sets/updates the xattr list for a given file.

func Statm

func Statm(nm string, fi *Info) error

Statm is like Stat above - except it uses caller supplied memory for the stat(2) info

func UpdateMetadata

func UpdateMetadata(dst string, fi *Info) error

UpdateMetadata writes new metadata of 'dst' from 'fi' The metadata that will be updated includes atime, mtime, uid/gid, mode/perm, xattr

Types

type Info

type Info struct {
	Ino  uint64
	Siz  int64
	Dev  uint64
	Rdev uint64

	Mod   fs.FileMode
	Uid   uint32
	Gid   uint32
	Nlink uint32

	Atim time.Time
	Mtim time.Time
	Ctim time.Time

	Nam   string
	Xattr Xattr
}

Info represents a file/dir metadata in a normalized form It satisfies the fs.FileInfo interface and notably supports extended file system attributes (`xattr(7)`). This type can also be safely marshaled and unmarshaled into a portable byte stream.

func Lstat

func Lstat(nm string) (*Info, error)

Lstat is like os.Lstat() but also returns xattr

func Stat

func Stat(nm string) (*Info, error)

Stat is like os.Stat() but also returns xattr

func (*Info) IsDir

func (ii *Info) IsDir() bool

IsDir returns true if this Info represents a directory entry

func (*Info) IsRegular

func (ii *Info) IsRegular() bool

IsRegular returns true if this Info represents a regular file

func (*Info) MarshalSize

func (ii *Info) MarshalSize() int

MarshalSize returns the marshaled size of _this_ instance of Info

func (*Info) MarshalTo

func (ii *Info) MarshalTo(b []byte) (int, error)

MarshalTo marshals 'ii' into the provided buffer 'b'. The buffer 'b' is expected to be sufficiently big to hold the marshaled data. It returns the number of marshaled bytes (ie exactly the value returned by the corresponding MarshalSize()).

func (*Info) ModTime

func (ii *Info) ModTime() time.Time

ModTime returns the file modification time

func (*Info) Mode

func (ii *Info) Mode() fs.FileMode

Mode returns the file mode bits

func (*Info) Name

func (ii *Info) Name() string

Name satisfies fs.FileInfo and returns the name of the fs entry.

func (*Info) Size

func (ii *Info) Size() int64

Size returns the fs entry's size

func (*Info) String

func (ii *Info) String() string

String is a string representation of Info

func (*Info) Sys

func (ii *Info) Sys() any

Sys returns the platform specific info - in our case it returns a pointer to the underlying Info instance.

func (*Info) Unmarshal

func (ii *Info) Unmarshal(b []byte) (int, error)

Unmarshal unmarshals the byte stream 'b' into a full rehydrated instance 'ii'. It returns the number of bytes consumed.

type SafeFile

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

SafeFile is an io.WriteCloser which uses a temporary file that will be atomically renamed when there are no errors and caller invokes Close(). The recommended usage is:

sf, err := NewSafeFile(...)
... error handling

defer sf.Abort()

... write to sf ..
sf.Close()

It is safe to call Abort on a closed SafeFile; the first call to Close() or Abort() seals the outcome. Similarly, it is safe to call Close() after Abort() - the first call to either takes precedence.

func NewSafeFile

func NewSafeFile(nm string, opts uint32, flag int, perm os.FileMode) (*SafeFile, error)

NewSafeFile creates a new temporary file that would either be aborted or safely renamed to the correct name. 'nm' is the name of the final file; if 'ovwrite' is true, then the file is overwritten if it exists.

func (*SafeFile) Abort

func (sf *SafeFile) Abort()

Abort the file write and remove any temporary artifacts; it is safe to call Close() on a different code path; the first call to Abort() or Close() takes precedence.

func (*SafeFile) Close

func (sf *SafeFile) Close() error

Close flushes all file data & metadata to disk, closes the file and atomically renames the temp file to the actual file - ONLY if there were no intervening errors.

func (*SafeFile) Write

func (sf *SafeFile) Write(b []byte) (int, error)

Attempt to write everything in 'b' and don't proceed if there was a previous error or the file was already closed.

func (*SafeFile) WriteAt

func (sf *SafeFile) WriteAt(b []byte, off int64) (int, error)

WriteAt writes 'b' at absolute offset 'off'

type Xattr

type Xattr map[string]string

Xattr is a collection of all the extended attributes of a given file

func GetXattr

func GetXattr(nm string) (Xattr, error)

GetXattr returns all the extended attributes of a file. This function will traverse symlinks.

func LgetXattr

func LgetXattr(nm string) (Xattr, error)

LGetXattr returns all the extended attributes of a file. If 'nm' points to a symlink, LGetXattr will return the extended attributes of the symlink and *not* the target.

func (Xattr) Equal

func (x Xattr) Equal(y Xattr) bool

Equal returns true if all xattr of 'x' is the same as all the xattr of 'y' and returns false otherwise.

func (Xattr) String

func (x Xattr) String() string

String returns the string representation of all the extended attributes