Create a new ".tar" file from a directory of files.

It is equivalent to calling the standard tar program like so:

$ tar -f tarball.tar -C base -c dir

This assumes a directory ./base/dir with files inside, eg ./base/dir/foo.txt. The file names inside the resulting tar file will be relative to dir, eg dir/foo.txt.

This is a high level "all in one" operation. Since you may need variations on this function it is instructive to see how it is written. It is just:

import qualified Data.ByteString.Lazy as BL

BL.writeFile tar . Tar.write =<< Tar.pack base paths

Notes:

The files and directories must not change during this operation or the result is not well defined.

The intention of this function is to create tarballs that are portable between systems. It is not suitable for doing file system backups because file ownership and permissions are not fully preserved. File ownership is not preserved at all. File permissions are set to simple portable values:

• rw-r--r-- for normal files
• rwxr-xr-x for executable files
• rwxr-xr-x for directories

Extract all the files contained in a ".tar" file.

It is equivalent to calling the standard tar program like so:

$ tar -x -f tarball.tar -C dir

So for example if the tarball.tar file contains foo/bar.txt then this will extract it to dir/foo/bar.txt.

This is a high level "all in one" operation. Since you may need variations on this function it is instructive to see how it is written. It is just:

import qualified Data.ByteString.Lazy as BL

Tar.unpack dir . Tar.read =<< BL.readFile tar

Notes:

Extracting can fail for a number of reasons. The tarball may be incorrectly formatted. There may be IO or permission errors. In such cases an exception will be thrown and extraction will not continue.

Since the extraction may fail part way through it is not atomic. For this reason you may want to extract into an empty directory and, if the extraction fails, recursively delete the directory.

Security: only files inside the target directory will be written. Tarballs containing entries that point outside of the tarball (either absolute paths or relative paths) will be caught and an exception will be thrown.

Append new entries to a ".tar" file from a directory of files.

This is much like create, except that all the entries are added to the end of an existing tar file. Or if the file does not already exists then it behaves the same as create.

Convert a data stream in the tar file format into an internal data structure. Decoding errors are reported by the Fail constructor of the Entries type.

• The conversion is done lazily.

Create the external representation of a tar archive by serialising a list of tar entries.

• The conversion is done lazily.

Creates a tar archive from a list of directory or files. Any directories specified will have their contents included recursively. Paths in the archive will be relative to the given base directory.

This is a portable implementation of packing suitable for portable archives. In particular it only constructs NormalFile, Directory and SymbolicLink entries. Hard links are treated like ordinary files. Special files like FIFOs (named pipes), sockets or device files will cause problems.

• This function returns results lazily. Subdirectories are scanned and files are read one by one as the list of entries is consumed. Do not change their contents before the output of pack was consumed in full.

Like pack, but allows to specify additional sanity/security checks on the input filenames. This is useful if you know which check will be used on client side in unpack / unpackAndCheck.

Since: 0.6.0.0

Create local files and directories based on the entries of a tar archive.

This is a portable implementation of unpacking suitable for portable archives. It handles NormalFile and Directory entries and has simulated support for SymbolicLink and HardLink entries. Links are implemented by copying the target file. This therefore works on Windows as well as Unix. All other entry types are ignored, that is they are not unpacked and no exception is raised.

If the Entries ends in an error then it is raised an an exception. Any files or directories that have been unpacked before the error was encountered will not be deleted. For this reason you may want to unpack into an empty directory so that you can easily clean up if unpacking fails part-way.

On its own, this function only checks for security (using checkEntrySecurity). Use unpackAndCheck if you need more checks.

Like unpack, but run custom sanity/security checks instead of checkEntrySecurity. For example,

import Control.Exception (SomeException(..))
import Control.Applicative ((<|>))

unpackAndCheck (\x -> SomeException <$> checkEntryPortability x
                  <|> SomeException <$> checkEntrySecurity x) dir entries

Since: 0.6.0.0

Polymorphic tar archive entry. High-level interfaces commonly work with GenEntry FilePath FilePath, while low-level ones use GenEntry TarPath LinkTarget.

Since: 0.6.0.0

Monomorphic tar archive entry, ready for serialization / deserialization.

Low-level function to get a native FilePath of the file or directory within the archive, not accounting for long names. It's likely that you want to apply decodeLongNames and use entryTarPath afterwards instead of entryPath.

The real content of the entry. For NormalFile this includes the file data. An entry usually contains a NormalFile or a Directory.

Polymorphic content of a tar archive entry. High-level interfaces commonly work with GenEntryContent FilePath, while low-level ones use GenEntryContent LinkTarget.

Portable archives should contain only NormalFile and Directory.

Since: 0.6.0.0

Monomorphic content of a tar archive entry, ready for serialization / deserialization.

Polymorphic sequence of archive entries. High-level interfaces commonly work with GenEntries FilePath FilePath, while low-level ones use GenEntries TarPath LinkTarget.

The point of this type as opposed to just using a list is that it makes the failure case explicit. We need this because the sequence of entries we get from reading a tarball can include errors.

Converting from a list can be done with just foldr Next Done. Converting back into a list can be done with foldEntries however in that case you must be prepared to handle the Fail case inherent in the Entries type.

The Monoid instance lets you concatenate archives or append entries to an archive.

Since: 0.6.0.0

Monomorphic sequence of archive entries, ready for serialization / deserialization.

This is like the standard map function on lists, but for Entries. It includes failure as a extra possible outcome of the mapping function.

If your mapping function cannot fail it may be more convenient to use mapEntriesNoFail

Like mapEntries but the mapping function itself cannot fail.

This is like the standard foldr function on lists, but for Entries. Compared to foldr it takes an extra function to account for the possibility of failure.

This is used to consume a sequence of entries. For example it could be used to scan a tarball for problems or to collect an index of the contents.

A foldl-like function on Entries. It either returns the final accumulator result, or the failure along with the intermediate accumulator value.

This is like the standard unfoldr function on lists, but for Entries. It includes failure as an extra possibility that the stepper function may return.

It can be used to generate Entries from some other type. For example it is used internally to lazily unfold entries from a ByteString.

Translate high-level entries with POSIX FilePaths for files and symlinks into entries suitable for serialization by emitting additional OtherEntryType 'K' and OtherEntryType 'L' nodes.

Input FilePaths must be POSIX file names, not native ones.

Since: 0.6.0.0

Translate low-level entries (usually freshly deserialized) into high-level entries with POSIX FilePaths for files and symlinks by parsing and eliminating OtherEntryType 'K' and OtherEntryType 'L' nodes.

Resolved FilePaths are still POSIX file names, not native ones.

Since: 0.6.0.0

Errors raised by decodeLongNames.

Since: 0.6.0.0

Errors that can be encountered when parsing a Tar archive.