filesys

Documentation

Overview

Package filesys provides functions to operate general files and file systems.

The functions in this package are for abstract files and file systems defined in package io/fs. To get functions for local files and file systems, see its subpackage local.

For better performance, all functions in this package and its subpackages are unsafe for concurrency unless otherwise specified.

Index

• Variables
• func VerifyChecksum(file fs.File, closeFile bool, cs ...HashChecksum) bool
• func VerifyChecksumFromFS(fsys fs.FS, name string, cs ...HashChecksum) bool
• type HashChecksum
• type ReadOptions
• type Reader
  • func Read(file fs.File, opts *ReadOptions, closeFile bool) (r Reader, err error)
  • func ReadFromFS(fsys fs.FS, name string, opts *ReadOptions) (r Reader, err error)

Variables

var ErrNotTar = errors.AutoNewCustom("file is not archived by tar, or is opened in raw mode",
	errors.PrependFullPkgName, 0)

ErrNotTar is an error indicating that the file is not archived by tar, or is opened in raw mode.

The client should use errors.Is to test whether an error is ErrNotTar.

Functions

func VerifyChecksum

func VerifyChecksum(file fs.File, closeFile bool, cs ...HashChecksum) bool

VerifyChecksum verifies a file by checksum.

To ensure that this function can work as expected, the input file must be ready to be read from the beginning and must not be operated by anyone else during the call to this function.

closeFile indicates whether this function should close the file. If closeFile is false, the client is responsible for closing file after use. If closeFile is true and file is not nil, file will be closed by this function.

It returns true if the file can be read and matches all checksums.

Note that it returns false if file is nil, or anyone of cs contains a nil NewHash or an empty ExpHex. And it returns true if file is not nil and len(cs) is 0.

func VerifyChecksumFromFS

func VerifyChecksumFromFS(fsys fs.FS, name string, cs ...HashChecksum) bool

VerifyChecksumFromFS verifies a file by checksum, where the file is opened from fsys by the specified name.

It returns true if and only if the file can be read and matches all checksums.

Note that it returns false if fsys is nil, or anyone of cs contains a nil NewHash or an empty ExpHex. And it returns true if len(cs) is 0 and the file can be opened for reading.

Types

type HashChecksum

type HashChecksum struct {
	// A function that creates a new hash function (e.g., crypto/sha256.New).
	NewHash func() hash.Hash

	// Expected checksum, in hexadecimal representation.
	ExpHex string
}

HashChecksum is a combination of a hash function maker and an expected checksum.

type ReadOptions

type ReadOptions struct {
	// Offset of the file to read, in bytes,
	// relative to the origin of the file for positive values,
	// and relative to the end of the file for negative values.
	Offset int64

	// Limit of the file to read, in bytes. Non-positive values for no limit.
	Limit int64

	// True if not to decompress when the file is compressed by gzip or bzip2,
	// and not to restore when the file is archived by tar (i.e., tape archive).
	Raw bool

	// Size of the buffer for reading the file at least.
	// Non-positive values for using default value.
	BufSize int
}

ReadOptions are options for Read functions.

type Reader

type Reader interface {
	inout.Closer
	inout.BufferedReader

	// TarEnabled returns true if the file is archived by tar
	// (i.e., tape archive) and is not opened in raw mode.
	TarEnabled() bool

	// TarNext advances to the next entry in the tar archive.
	//
	// The tar.Header.Size determines how many bytes can be read
	// for the next file.
	// Any remaining data in current file is automatically discarded.
	//
	// io.EOF is returned at the end of the input.
	//
	// If the file is not archived by tar, or the file is opened in raw mode,
	// it does nothing and reports ErrNotTar.
	// (To test whether err is ErrNotTar, use function errors.Is.)
	TarNext() (header *tar.Header, err error)

	// Options returns a copy of options used by this reader.
	Options() *ReadOptions

	// FileInfo returns the information of the file.
	FileInfo() (info fs.FileInfo, err error)
}

Reader is a device to read data from a file.

Its method Close closes all closable objects opened by this reader (may include the file). After successfully closing this reader, its method Close will do nothing and return nil.

func Read

func Read(file fs.File, opts *ReadOptions, closeFile bool) (r Reader, err error)

Read creates a reader on the specified file with options opts.

If opts are nil, a zero-value ReadOptions will be used.

To ensure that this function and the returned reader can work as expected, the input file must not be operated by anyone else before closing the returned reader. If the option Offset is non-zero and the file is not an io.Seeker, the file must be ready to be read from the beginning.

closeFile indicates whether the reader should close the file when calling its method Close. If closeFile is false, the client is responsible for closing file after closing the reader. If closeFile is true, the client should not close the file, even if this function reports an error. In this case, the file will be closed during the method Close of the reader, and it will also be closed by this function when encountering an error.

This function panics if file is nil.

func ReadFromFS

func ReadFromFS(fsys fs.FS, name string, opts *ReadOptions) (r Reader, err error)

ReadFromFS opens a file from fsys with specified name and options opts for reading.

If opts are nil, a zero-value ReadOptions will be used.

The file will be closed when the returned reader is closed.

This function panics if fsys is nil.