tarhelper

Documentation

Index

• Constants
• func AddDecompressor(name string, comp Decompressor)
• func DetectArchiveCompression(r io.Reader) (*tar.Reader, error)
• type Bzip2Decompressor
  • func (c *Bzip2Decompressor) Detect(br *bufio.Reader) bool
  • func (c *Bzip2Decompressor) NewReader(src io.Reader) (io.Reader, error)
• type Compression
• type Decompressor
• type DirStack
• type GzipDecompressor
  • func (c *GzipDecompressor) Detect(br *bufio.Reader) bool
  • func (c *GzipDecompressor) NewReader(src io.Reader) (io.Reader, error)
• type Tar
  • func NewTar(w io.Writer, targetDir string) *Tar
  • func (t *Tar) Archive() error
  • func (t *Tar) ExcludePath(pathRE string)
  • func (t *Tar) ExcludeRegexp(re *regexp.Regexp, dirOnly bool)
  • func (t *Tar) IncludePath(pathRE string)
  • func (t *Tar) IncludeRegexp(re *regexp.Regexp, dirOnly bool)
• type TarCustomHandler
• type TarCustomHook
• type Untar
  • func NewUntar(r io.Reader, targetDir string) *Untar
  • func (u *Untar) Extract() error
• type UntarCustomHandler
• type UserOption

Constants

const (
	NONE   = Compression("")
	BZIP2  = Compression("bzip2")
	GZIP   = Compression("gzip")
	DETECT = Compression("detect")

	WindowsMaxPathLen = 260 // characters
)

Functions

func AddDecompressor

func AddDecompressor(name string, comp Decompressor)

func DetectArchiveCompression

func DetectArchiveCompression(r io.Reader) (*tar.Reader, error)

DetectArchiveCompression takes a source reader and will determine the compression type to use, if any. It will return a *tar.Reader that can be used to read the archive.

Types

type Bzip2Decompressor

type Bzip2Decompressor struct{}

func (*Bzip2Decompressor) Detect

func (c *Bzip2Decompressor) Detect(br *bufio.Reader) bool

func (*Bzip2Decompressor) NewReader

func (c *Bzip2Decompressor) NewReader(src io.Reader) (io.Reader, error)

type Compression

type Compression string

The type of compression that this archive will be us

type Decompressor

type Decompressor interface {
	Detect(*bufio.Reader) bool
	NewReader(io.Reader) (io.Reader, error)
}

type DirStack

type DirStack []string

DirStack tracks circular symbolic links for the dereference archive option. Declaring a type here to highlight the semantics.

type GzipDecompressor

type GzipDecompressor struct{}

func (*GzipDecompressor) Detect

func (c *GzipDecompressor) Detect(br *bufio.Reader) bool

func (*GzipDecompressor) NewReader

func (c *GzipDecompressor) NewReader(src io.Reader) (io.Reader, error)

type Tar

type Tar struct {

	// The Compression being used in this tar.
	Compression Compression

	// Set to true if archiving should attempt to preserve
	// permissions as it was on the filesystem. If this is false then
	// files will be archived with basic file/directory permissions.
	IncludePermissions bool

	// Set to true to perserve ownership of files and directories. If set to
	// false, the Uid and Gid will be set as 500, which is the first Uid/Gid
	// reserved for normal users.
	IncludeOwners bool

	// If set, this will be a virtual path that is prepended to the
	// file location.  This allows the target to be under a temp directory
	// but have it packaged as though it was under another directory, such as
	// taring /tmp/build, and having
	//   /tmp/build/bin/foo be /var/lib/build/bin/foo
	// in the tar archive.
	VirtualPath string

	// OwnerMappingFunc is used to give the caller the ability to control the
	// mapping of UIDs in the tar into what they should be on the host. The
	// function is only used when IncludeOwners is true. The function is passed in
	// the UID of the file on the filesystem and is expected to return a UID to
	// use within the tar file. It can also return an error if it is unable to
	// choose a UID or the UID is not allowed.
	OwnerMappingFunc func(int) (int, error)

	// GroupMappingFunc is used to give the caller the ability to control the
	// mapping of GIDs in the tar into what they should be on the host. The
	// function is only used when IncludeOwners is true. The function is passed in
	// the GID of the file on the filesystem and is expected to return a GID to
	// use within the tar file. It can also return an error if it is unable to
	// choose a GID or the GID is not allowed.
	GroupMappingFunc func(int) (int, error)

	// ExcludeRootPath ensures the resulting tarball does not include
	// a header entry for "./". This prevents untarring from modifying
	// the parent directory.
	ExcludeRootPath bool

	// User provided control options. UserOption enum has the
	// definitions and explanations for the various flags.
	UserOptions UserOption

	// CustomHandlers is used to allow the code calling tarhelper to inject custom
	// logic for how to handle certain entries being written to the tar file. The
	// Tar handler will loop over and call to these functions. They return a
	// boolean which should be true when the built in logic for handling the file
	// should be skipped. They also return an error which will cause the tar
	// function to abort and bubble up the handler's error. The functions are
	// passed the path where the entry are located on disk, the os.FileInfo for
	// the file, and the *tar.Header entry for it.
	CustomHandlers []TarCustomHandler

	// PrefixHook executes before the file system is traversed and can be used to inject
	// content into the archive which does not exist within the file system tree. This
	// content will be extracted before any file system data.
	PrefixHook TarCustomHook

	// SuffixHook executes after the file system is traversed and like PrefixHook can be
	// used to inject additional content into the archive. This content will be extracted
	// after data from the file system.
	SuffixHook TarCustomHook
	// contains filtered or unexported fields
}

Tar manages state for a TAR archive.

func NewTar

func NewTar(w io.Writer, targetDir string) *Tar

NewTar returns a Tar ready to write the contents of targetDir to w.

func (*Tar) Archive

func (t *Tar) Archive() error

func (*Tar) ExcludePath

func (t *Tar) ExcludePath(pathRE string)

ExcludePath appends a path, file, or pattern relative to the toplevel path to be archived that is then excluded from the final archive. pathRE is a regex that will be anchored at the start and end then applied to the entire filename (full path and basename)

func (*Tar) ExcludeRegexp

func (t *Tar) ExcludeRegexp(re *regexp.Regexp, dirOnly bool)

ExcludeRegexp adds a Regexp into the list to consider when selectiong files to exclude. Files or directories matching the regexp will be excluded, even if they matched a previous Regexp from IncludeRegexp. Files are only considered a match if they match the Regexp and isDir is false.

func (*Tar) IncludePath

func (t *Tar) IncludePath(pathRE string)

IncludePath appends a path, file, or pattern relative to the toplevel path to be archived that is then excluded from the final archive. pathRE is a regex that will be anchored at the start and end then applied to the entire filename (full path and basename)

func (*Tar) IncludeRegexp

func (t *Tar) IncludeRegexp(re *regexp.Regexp, dirOnly bool)

IncludeRegexp adds a Regexp into the list to consider when selectiong files to exclude. Files or directories matching the regexp will _not_ be excluded, even if they matched a previous Regexp. Files are only considered a match if they match the Regexp and isDir is false.

type TarCustomHandler

type TarCustomHandler func(fullpath string, fi os.FileInfo, header *tar.Header) (bool, error)

TarCustomHandler are used to inject custom behavior for handling file entries going into a tar file. For more information, see Tar.CustomerHandlers description.

type TarCustomHook

type TarCustomHook func(archive *tar.Writer) error

TarCustomHook can inject additional header and file data into the archive. For more information, see Tar.PrefixHook and Tar.SuffixHook.

type Untar

type Untar struct {

	// The AbsoluteRoot is intended to be the root of the target and allows us
	// to create files that follow through links that are absolute paths, but
	// ensure the file is created relative to the AbsoluteRoot and not the root
	// on the host system.
	AbsoluteRoot string

	// The Compression being used in this tar.
	Compression Compression

	// Set to true if extraction should attempt to preserve
	// permissions as recorded in the tar file. If this is false then
	// files will be created with a default of 755 for directories and 644
	// for files.
	PreservePermissions bool

	// Set to true if extraction should attempt to restore owners of files
	// and directories from the archive.  Any Uid/Gid over 500 will be set
	// to the MappedUserID/MappedGroupID setting.  If this is set to false
	// it will default to all files going to the MappedUserID/MappedGroupID.
	PreserveOwners bool

	// SkipSpecialDevices can be used to skip extracting special devices defiend
	// within the tarball. This includes things like character or block devices.
	SkipSpecialDevices bool

	// The default UID to set files with an owner over 500 to. If PreserveOwners
	// is false, this will be the UID assigned for all files in the archive.
	// This defaults to the UID of the current running user.
	MappedUserID int

	// The default GID to set files with an owner over 500 to. If PreserveOwners
	// is false, this will be the GID assigned for all files in the archive.
	// This defaults to the GID of the current running user.
	MappedGroupID int

	// IncludedPermissionMask is combined with the uploaded file mask as a way to
	// ensure a base level of permissions for all objects.
	IncludedPermissionMask os.FileMode

	// PathWhitelist provides a list of files that will only be extracted from the
	// provided tarball. If PathWhitelist is not set, then all files will be
	// allowed. If it is set, then only files matching the specified files
	// (/etc/file) or directories (/etc/dir/) will be allowed.
	PathWhitelist []string

	// OwnerMappingFunc is used to give the caller the ability to control the
	// mapping of UIDs in the tar into what they should be on the host. It is only
	// used when PreserveOwners is true. The function is passed in the UID of the
	// file being extracted and is expected to return a UID to use for the actual
	// file. It can also return an error if it is unable to choose a UID or the
	// UID is not allowed.
	OwnerMappingFunc func(int) (int, error)

	// GroupMappingFunc is used to give the caller the ability to control the
	// mapping of GIDs in the tar into what they should be on the host. It is only
	// used when PreserveOwners is true. The function is passed in the GID of the
	// file being extracted and is expected to return a GID to use for the actual
	// file. It can also return an error if it is unable to choose a GID or the
	// GID is not allowed.
	GroupMappingFunc func(int) (int, error)

	// CustomHandlers is used to allow the code calling tarhelper to inject custom
	// logic for how to handle certain entries within the tar file. The Untar
	// handler will loop over and call to these functions. They return a boolean
	// which should be true when the built in logic for handling the tar entry
	// should be skipped. They also return an error which will cause the untar
	// function to abort and bubble up the handler's error. The functions are
	// passed the root path where the tar is being extracted on disk, the
	// *tar.Header entry, and an io.Reader to the entry's contents (if it is a
	// file).
	CustomHandlers []UntarCustomHandler
	// contains filtered or unexported fields
}

Untar manages state of a TAR archive to be extracted.

func NewUntar

func NewUntar(r io.Reader, targetDir string) *Untar

NewUntar returns an Untar to use to extract the contents of r into targetDir. Extraction is handled by Extract().

func (*Untar) Extract

func (u *Untar) Extract() error

Extract unpacks the tar reader that was passed into New(). This is broken out from new to give the caller time to set various settings in the Untar object.

type UntarCustomHandler

type UntarCustomHandler func(rootpath string, header *tar.Header, reader io.Reader) (bool, error)

UntarCustomHandler are used to inject custom behavior for handling in a tar file. For more information, see Untar.CustomerHandlers description.

type UserOption

type UserOption int

User options enumeration type. This encodes the control options provided by user.