squashfs

README

squashfs

A PURE Go library to read squashfs. There is currently no plans to add archive creation support as it will almost always be better to just call mksquashfs. I could see some possible use cases, but probably won't spend time on it unless it's requested (open a discussion fi you want this feature).

Currently has support for reading squashfs files and extracting files and folders.

Special thanks to https://dr-emann.github.io/squashfs/ for some VERY important information in an easy to understand format. Thanks also to distri's squashfs library as I referenced it to figure some things out (and double check others).

TODO

Limitations

• No Xattr parsing. This is simply because I haven't done any research on it and how to apply these in a pure go way.

Performance

Testing on a zstd compressed file, my library is anywhere from 5x ~ 7x slower then unsquashfs

Documentation

Index

• Constants
• Variables
• type ExtractionOptions
  • func DefaultOptions() ExtractionOptions
• type FS
  • func (f FS) Glob(pattern string) (out []string, err error)
  • func (f FS) Open(name string) (fs.File, error)
  • func (f FS) OpenFile(name string) (*File, error)
  • func (f FS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (f FS) ReadFile(name string) ([]byte, error)
  • func (f FS) Stat(name string) (fs.FileInfo, error)
  • func (f FS) Sub(dir string) (fs.FS, error)
• type File
  • func (f *File) Close() error
  • func (f File) ExtractSymlink(folder string) error
  • func (f File) ExtractTo(folder string) error
  • func (f File) ExtractWithOptions(folder string, op ExtractionOptions) error
  • func (f *File) FS() (*FS, error)
  • func (f File) GetSymlinkFile() *File
  • func (f File) IsDir() bool
  • func (f File) IsRegular() bool
  • func (f File) IsSymlink() bool
  • func (f File) Mode() fs.FileMode
  • func (f File) Read(p []byte) (int, error)
  • func (f File) ReadAt(p []byte, off int64) (int, error)
  • func (f *File) ReadDir(n int) (out []fs.DirEntry, err error)
  • func (f File) Stat() (fs.FileInfo, error)
  • func (f File) SymlinkPath() string
  • func (f File) WriteTo(w io.Writer) (int64, error)
• type Reader
  • func NewReader(r io.ReaderAt) (*Reader, error)
  • func NewReaderAtOffset(r io.ReaderAt, off int64) (*Reader, error)
  • func NewReaderFromReader(r io.Reader) (*Reader, error)
  • func (r Reader) ModTime() time.Time
  • func (r *Reader) Mount(mountpoint string) (err error)
  • func (r *Reader) MountFuse2(mountpoint string) (err error)
  • func (r *Reader) MountWait()
  • func (r *Reader) MountWaitFuse2()
  • func (r *Reader) Unmount() error
  • func (r *Reader) UnmountFuse2() error

Constants

const (
	GZipCompression = uint16(iota + 1)
	LZMACompression
	LZOCompression
	XZCompression
	LZ4Compression
	ZSTDCompression
)

The types of compression supported by squashfs

Variables

var (
	ErrorMagic   = errors.New("magic incorrect. probably not reading squashfs archive")
	ErrorLog     = errors.New("block log is incorrect. possible corrupted archive")
	ErrorVersion = errors.New("squashfs version of archive is not 4.0")
)

var ENODATA = fuse.ENODATA

var (
	ErrReadNotFile = errors.New("read called on non-file")
)

Types

type ExtractionOptions

type ExtractionOptions struct {
	LogOutput          io.Writer   //Where error log should write. If nil, uses os.Stdout. Has no effect if verbose is false.
	DereferenceSymlink bool        //Replace symlinks with the target file.
	UnbreakSymlink     bool        //Try to make sure symlinks remain unbroken when extracted, without changing the symlink.
	Verbose            bool        //Prints extra info to log on an error.
	IgnorePerm         bool        //ignore the file's permission and instead use FolderPerm.
	FolderPerm         fs.FileMode //The permissions used when creating the extraction folder. Defaults to 0755.
}

ExtractionOptions are available options on how to extract.

func DefaultOptions

func DefaultOptions() ExtractionOptions

DefaultOptions is the default ExtractionOptions.

type FS

type FS struct {
	*File
	// contains filtered or unexported fields
}

FS is a fs.FS representation of a squashfs directory. Implements fs.GlobFS, fs.ReadDirFS, fs.ReadFileFS, fs.StatFS, and fs.SubFS

func (FS) Glob

func (f FS) Glob(pattern string) (out []string, err error)

Glob returns the name of the files at the given pattern. All paths are relative to the FS. Uses filepath.Match to compare names.

func (FS) Open

func (f FS) Open(name string) (fs.File, error)

Opens the file at name. Returns a io/fs.File.

func (FS) OpenFile

func (f FS) OpenFile(name string) (*File, error)

Opens the file at name. Returns a squashfs.File.

func (FS) ReadDir

func (f FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir returns all the DirEntry returns all DirEntry's for the directory at name. If name is not a directory, returns an error.

func (FS) ReadFile

func (f FS) ReadFile(name string) ([]byte, error)

ReadFile returns the data (in []byte) for the file at name.

func (FS) Stat

func (f FS) Stat(name string) (fs.FileInfo, error)

Stat returns the fs.FileInfo for the file at name.

func (FS) Sub

func (f FS) Sub(dir string) (fs.FS, error)

Sub returns the FS at dir

type File

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

File represents a file inside a squashfs archive.

func (*File) Close

func (f *File) Close() error

Close simply nils the underlying reader.

func (File) ExtractSymlink

func (f File) ExtractSymlink(folder string) error

ExtractSymlink extracts the File to the folder with the DereferenceSymlink option. If the File is a directory, it instead extracts the directory's contents to the folder.

func (File) ExtractTo

func (f File) ExtractTo(folder string) error

ExtractTo extracts the File to the given folder with the default options. If the File is a directory, it instead extracts the directory's contents to the folder.

func (File) ExtractWithOptions

func (f File) ExtractWithOptions(folder string, op ExtractionOptions) error

ExtractWithOptions extracts the File to the given folder with the given ExtrationOptions. If the File is a directory, it instead extracts the directory's contents to the folder.

func (*File) FS

func (f *File) FS() (*FS, error)

FS returns the File as a FS.

func (File) GetSymlinkFile

func (f File) GetSymlinkFile() *File

GetSymlinkFile returns the File the symlink is pointing to. If not a symlink, or the target is unobtainable (such as it being outside the archive or it's absolute) returns nil

func (File) IsDir

func (f File) IsDir() bool

IsDir Yep.

func (File) IsRegular

func (f File) IsRegular() bool

IsRegular yep.

func (File) IsSymlink

func (f File) IsSymlink() bool

IsSymlink yep.

func (File) Mode

func (f File) Mode() fs.FileMode

Mode returns the file's fs.FileMode

func (File) Read

func (f File) Read(p []byte) (int, error)

Read reads the data from the file. Only works if file is a normal file.

func (File) ReadAt

func (f File) ReadAt(p []byte, off int64) (int, error)

func (*File) ReadDir

func (f *File) ReadDir(n int) (out []fs.DirEntry, err error)

ReadDir returns n fs.DirEntry's that's contained in the File (if it's a directory). If n <= 0 all fs.DirEntry's are returned.

func (File) Stat

func (f File) Stat() (fs.FileInfo, error)

Stat returns the File's fs.FileInfo

func (File) SymlinkPath

func (f File) SymlinkPath() string

SymlinkPath returns the symlink's target path. Is the File isn't a symlink, returns an empty string.

func (File) WriteTo

func (f File) WriteTo(w io.Writer) (int64, error)

WriteTo writes all data from the file to the writer. This is multi-threaded. The underlying reader is seperate from the one used with Read and can be reused.

type Reader

type Reader struct {
	*FS
	// contains filtered or unexported fields
}

func NewReader

func NewReader(r io.ReaderAt) (*Reader, error)

Creates a new squashfs.Reader from the given io.ReaderAt.

func NewReaderAtOffset

func NewReaderAtOffset(r io.ReaderAt, off int64) (*Reader, error)

func NewReaderFromReader

func NewReaderFromReader(r io.Reader) (*Reader, error)

Creates a new squashfs.Reader from the given io.Reader. NOTE: All data from the io.Reader will be read and stored in memory.

func (Reader) ModTime

func (r Reader) ModTime() time.Time

Returns the last time the archive was modified.

func (*Reader) Mount

func (r *Reader) Mount(mountpoint string) (err error)

Mounts the archive to the given mountpoint using fuse3. Non-blocking. If Unmount does not get called, the mount point must be unmounted using umount before the directory can be used again.

func (*Reader) MountFuse2

func (r *Reader) MountFuse2(mountpoint string) (err error)

Mounts the archive to the given mountpoint using fuse2. Non-blocking. If Unmount does not get called, the mount point must be unmounted using umount before the directory can be used again.

func (*Reader) MountWait

func (r *Reader) MountWait()

Blocks until the mount ends.

func (*Reader) MountWaitFuse2

func (r *Reader) MountWaitFuse2()

Blocks until the mount ends. Fuse2 version.

func (*Reader) Unmount

func (r *Reader) Unmount() error

Unmounts the archive.

func (*Reader) UnmountFuse2

func (r *Reader) UnmountFuse2() error

Unmounts the archive. Fuse2 version.