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 if you want this feature).
The library has two parts with this github.com/CalebQ42/squashfs being easy to use as it implements io/fs interfaces and doesn't expose unnecessary information. 95% this is the library you want. If you need lower level access to the information, use github.com/CalebQ42/squashfs/low where far more information is exposed.
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).
Build tags
As of v1.1.0 this library has two optional build tags: no_gpl and no_obsolete. no_gpl disables the ability to read archives with lzo compression due to the library's gpl license. no_obsolete removes "obsolete" compression types for a reduced compilation size; currently this only disable lzma compression since it's superseded by xz.
FUSE
As of v1.0, FUSE capabilities has been moved to a separate library.
Limitations
- No Xattr parsing.
- Socket files are not extracted.
- From my research, it seems like a socket file would be useless if it could be created.
- Fifo files are ignored on
darwin
Issues
- Noticably slower then
unsquashfsfor extraction, especially on larger images.- This seems to be related to above along with the general optimization of
unsquashfsand it's compression libraries. - Times seem to be largely dependent on file tree size and compression type.
- My main testing image (~100MB) using Zstd takes ~2x longer.
- An Arch Linux airootfs image (~780MB) using XZ compression with LZMA filters takes ~28x longer.
- A Tensorflow docker image (~3.3GB) using Zstd takes ~3x longer.
- This seems to be related to above along with the general optimization of
Note: These numbers are using FastOptions(). DefaultOptions() takes ~2x longer.
Recommendations on Usage
Due to the above performance consideration, this library should only be used to access files within the archive without extraction, or to mount it via Fuse.
- Neither of these use cases are largely effected by the issue above.
Documentation
¶
Index ¶
- type ExtractionOptions
- type FS
- func (f FS) Extract(folder string) error
- func (f FS) ExtractWithOptions(folder string, op *ExtractionOptions) error
- func (f FS) File() *File
- 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) (out []byte, err 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) Extract(folder string) error
- func (f File) ExtractWithOptions(path string, op *ExtractionOptions) error
- func (f File) FS() (FS, error)
- func (f File) GetSymlinkFile() fs.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(b []byte) (int, error)
- func (f *File) ReadDir(n int) ([]fs.DirEntry, error)
- func (f File) Stat() (fs.FileInfo, error)
- func (f File) SymlinkPath() string
- func (f *File) WriteTo(w io.Writer) (int64, error)
- type FileInfo
- func (f FileInfo) Gid() int
- func (f FileInfo) IsDevice() bool
- func (f FileInfo) IsDir() bool
- func (f FileInfo) IsFifo() bool
- func (f FileInfo) IsSocket() bool
- func (f FileInfo) IsSymlink() bool
- func (f FileInfo) ModTime() time.Time
- func (f FileInfo) Mode() fs.FileMode
- func (f FileInfo) Name() string
- func (f FileInfo) Size() int64
- func (f FileInfo) SymlinkPath() string
- func (f FileInfo) Sys() any
- func (f FileInfo) Uid() int
- type Reader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExtractionOptions ¶ added in v0.4.0
type ExtractionOptions struct {
LogOutput io.Writer //Where the verbose log should write.
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 file's permissions and instead use Perm.
Perm fs.FileMode //Permission to use when IgnorePerm. Defaults to 0777.
ExtractionRoutines uint16 //The number of threads to use during extraction. Defaults to a number based on runtime.NumCPU().
SimultaneousFiles uint16 //Depreciated: Only use ExtractionRoutines
// contains filtered or unexported fields
}
func DefaultOptions ¶ added in v0.4.0
func DefaultOptions() *ExtractionOptions
The default extraction options. Uses half of your CPU cores.
func FastOptions ¶ added in v1.0.0
func FastOptions() *ExtractionOptions
Faster extraction option. Uses all CPU cores.
type FS ¶ added in v0.4.0
type FS struct {
LowDir squashfslow.Directory
// 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) Extract ¶ added in v1.0.0
Extract the FS to the given folder. If the file is a folder, the folder's contents will be extracted to the folder. Uses default extraction options.
func (FS) ExtractWithOptions ¶ added in v0.4.0
func (f FS) ExtractWithOptions(folder string, op *ExtractionOptions) error
Extract the FS to the given folder. If the file is a folder, the folder's contents will be extracted to the folder. Allows setting various extraction options via ExtractionOptions.
func (*FS) Glob ¶ added in v0.4.0
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) ReadDir ¶ added in v0.4.0
Returns all DirEntry's for the directory at name. If name is not a directory, returns an error.
type File ¶ added in v0.2.0
type File struct {
Low squashfslow.FileBase
// contains filtered or unexported fields
}
File represents a file inside a squashfs archive.
func (*File) Close ¶ added in v0.2.0
Closes the underlying readers. Further calls to Read and WriteTo will re-create the readers. Never returns an error.
func (File) Extract ¶ added in v1.0.0
Extract the file to the given folder. If the file is a folder, the folder's contents will be extracted to the folder. Uses default extraction options.
func (File) ExtractWithOptions ¶ added in v0.3.0
func (f File) ExtractWithOptions(path string, op *ExtractionOptions) error
Extract the file to the given folder. If the file is a folder, the folder's contents will be extracted to the folder. Allows setting various extraction options via ExtractionOptions.
func (File) GetSymlinkFile ¶ added in v0.2.1
Returns the file the symlink points to. If the file isn't a symlink, or points to a file outside the archive, returns nil.
func (*File) Read ¶ added in v0.2.0
Read reads the data from the file. Only works if file is a normal file.
func (*File) ReadDir ¶ added in v0.4.0
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) SymlinkPath ¶ added in v0.2.1
SymlinkPath returns the symlink's target path. Is the File isn't a symlink, returns an empty string.
type FileInfo ¶ added in v0.4.0
type FileInfo struct {
// contains filtered or unexported fields
}
func (FileInfo) SymlinkPath ¶ added in v1.1.0
type Reader ¶
type Reader struct {
FS
Low squashfslow.Reader
}
func NewReaderAtOffset ¶ added in v0.7.2
func (*Reader) FSFromDirectory ¶ added in v1.0.0
func (r *Reader) FSFromDirectory(d squashfslow.Directory, parent FS) FS
Creates a new *FS from the given squashfs.directory
func (*Reader) FileFromBase ¶ added in v1.0.0
func (r *Reader) FileFromBase(b squashfslow.FileBase, parent FS) File
Creates a new *File from the given *squashfs.Base
Source Files
Directories