reflink

README

reflink

Perform reflink operation on compatible filesystems (btrfs or xfs).

What is a reflink?

There are a number of type of links existing on Linux:

• symlinks
• hardlinks
• reflinks

Reflinks are a new kind of links found in btrfs and xfs which act similar to hard links, except modifying one of the two files will not change the other, and typically only the changed data will take space on the disk (copy-on-write).

Can I use reflinks?

A machine needs to have a compatible OS and filesystem to perform reflinks. Known to work are:

• btrfs on Linux
• xfs on Linux

Other OSes have similar features, to be implemented in the future.

• Windows has DUPLICATE_EXTENTS_TO_FILE
• Solaris has reflink
• MacOS has clonefile

Usage

err := reflink.Always("original_file.bin", "snapshot-001.bin")

// or

err := reflink.Auto("source_img.png", "modified_img.png")

reflink.Always will fail if reflink is not supported or didn't work for any reason, while reflink.Auto will fallback to a regular file copy.

Notes

• The arguments have been put in the same order as os.Link or os.Rename rather than io.Copy as we are dealing with filenames.

Documentation

Index

• Variables
• func Always(src, dst string) error
• func Auto(src, dst string) error
• func Partial(dst, src *os.File, dstOffset, srcOffset, n int64, fallback bool) error
• func Reflink(dst, src *os.File, fallback bool) error

Variables

var (
	ErrReflinkUnsupported = errors.New("reflink is not supported on this OS")
	ErrReflinkFailed      = errors.New("reflink is not supported on this OS or file")
)

ErrReflinkUnsupported is returned by Always() if the operation is not supported on the current operating system. Auto() will never return this error.

Functions

func Always

func Always(src, dst string) error

Always will perform a reflink operation and fail on error.

This is equivalent to command cp --reflink=always

func Auto

func Auto(src, dst string) error

Auto will attempt to perform a reflink operation and fallback to normal data copy if reflink is not supported.

This is equivalent to cp --reflink=auto

func Partial

func Partial(dst, src *os.File, dstOffset, srcOffset, n int64, fallback bool) error

Partial performs a range reflink operation on the passed files, replacing part of dst's contents with data from src. If fallback is true and reflink fails, copy_file_range will be used first, and if that fails too io.CopyN will be used to copy the data.

func Reflink

func Reflink(dst, src *os.File, fallback bool) error

Reflink performs the reflink operation on the passed files, replacing dst's contents with src. If fallback is true and reflink fails, copy_file_range will be used first, and if that fails too io.Copy will be used to copy the data.