| ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
Description | ||||||||||||||||||||||||||||||||
Reading, writing and manipulating ".tar" archive files. This module uses common names and so is designed to be imported qualified: import qualified Codec.Archive.Tar as Tar | ||||||||||||||||||||||||||||||||
Synopsis | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
Documentation | ||||||||||||||||||||||||||||||||
Tar archive files are used to store a collection of other files in a single file. They consists of a sequence of entries. Each entry describes a file or directory (or some other special kind of file). The entry stores a little bit of meta-data, in particular the file or directory name. Unlike some other archive formats, a tar file contains no index. The information about each entry is stored next to the entry. Because of this, tar files are almost always processed linearly rather than in a random-access fashion. The functions in this package are designed for working on tar files linearly and lazily. This makes it possible to do many operations in constant space rather than having to load the entire archive into memory. It can read and write standard POSIX tar files and also the GNU and old Unix V7 tar formats. The convenience functions that are provided in the Codec.Archive.Tar.Entry module for creating archive entries are primarily designed for standard portable archives. If you need to construct GNU format archives or exactly preserve file ownership and permissions then you will need to write some extra helper functions. This module contains just the simple high level operations without exposing the all the details of tar files. If you need to inspect tar entries in more detail or construct them directly then you also need the module Codec.Archive.Tar.Entry. | ||||||||||||||||||||||||||||||||
High level "all in one" operations | ||||||||||||||||||||||||||||||||
create | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
extract | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
Notes | ||||||||||||||||||||||||||||||||
Compressed tar archives | ||||||||||||||||||||||||||||||||
Tar files are commonly used in conjunction with gzip compression, as in ".tar.gz" or ".tar.bz2" files. This module does not directly handle compressed tar files however they can be handled easily by composing functions from this module and the modules Codec.Compression.GZip or Codec.Compression.BZip. Creating a compressed ".tar.gz" file is just a minor variation on the create function, but where throw compression into the pipeline: BS.writeFile tar . GZip.compress . Tar.write =<< Tar.pack base dir Similarly, extracting a compressed ".tar.gz" is just a minor variation on the extract function where we use decompression in the pipeline: Tar.unpack dir . Tar.read . GZip.decompress =<< BS.readFile tar | ||||||||||||||||||||||||||||||||
Tarbombs | ||||||||||||||||||||||||||||||||
A "tarbomb" is a .tar file where not all entries are in a subdirectory but instead files extract into the top level directory. The extract function does not check for these however if you want to do that you can use the checkTarbomb function like so: Tar.unpack dir . Tar.checkTarbomb expectedDir . Tar.read =<< BS.readFile tar In this case extraction will fail if any file is outside of expectedDir. | ||||||||||||||||||||||||||||||||
Security | ||||||||||||||||||||||||||||||||
This is pretty important. A maliciously constructed tar archives could contain entries that specify bad file names. It could specify absolute file names like "/etc/passwd" or relative files outside of the archive like "../../../something". This security problem is commonly called a "directory traversal vulnerability". Historically, such vulnerabilities have been common in packages handling tar archives. The extract and unpack functions check for bad file names. See the checkSecurity function for more details. If you need to do any custom unpacking then you should use this. | ||||||||||||||||||||||||||||||||
Converting between internal and external representation | ||||||||||||||||||||||||||||||||
Note, you cannot expect write . read to give exactly the same output as input. You can expect the information to be preserved exactly however. This is because read accepts common format variations while write produces the standard format. | ||||||||||||||||||||||||||||||||
read :: ByteString -> Entries | ||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||
write :: [Entry] -> ByteString | ||||||||||||||||||||||||||||||||
Create the external representation of a tar archive by serialising a list of tar entries.
| ||||||||||||||||||||||||||||||||
Packing and unpacking files to/from internal representation | ||||||||||||||||||||||||||||||||
These functions are for packing and unpacking portable archives. They are not suitable in cases where it is important to preserve file ownership and permissions or to archive special files like named pipes and Unix device files. | ||||||||||||||||||||||||||||||||
pack | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
unpack :: FilePath -> Entries -> IO () | ||||||||||||||||||||||||||||||||
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 IO error. 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 checkSecurity). You can do other checks by applying checking functions to the Entries that you pass to this function. For example: unpack dir (checkTarbomb expectedDir entries) If you care about the priority of the reported errors then you may want to use checkSecurity before checkTarbomb or other checks. | ||||||||||||||||||||||||||||||||
Types | ||||||||||||||||||||||||||||||||
Tar entry type | ||||||||||||||||||||||||||||||||
This module provides only very simple and limited read-only access to the Entry type. If you need access to the details or if you need to construct your own entries then also import Codec.Archive.Tar.Entry. | ||||||||||||||||||||||||||||||||
data Entry | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
entryPath :: Entry -> FilePath | ||||||||||||||||||||||||||||||||
Native FilePath of the file or directory within the archive. | ||||||||||||||||||||||||||||||||
entryContent :: Entry -> EntryContent | ||||||||||||||||||||||||||||||||
The real content of the entry. For NormalFile this includes the file data. An entry usually contains a NormalFile or a Directory. | ||||||||||||||||||||||||||||||||
data EntryContent | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
Sequences of tar entries | ||||||||||||||||||||||||||||||||
data Entries | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
mapEntries :: (Entry -> Either String Entry) -> Entries -> Entries | ||||||||||||||||||||||||||||||||
This is like the standard map function on lists, but for Entries. It includes failure as a extra possible outcome of the mapping function. | ||||||||||||||||||||||||||||||||
foldEntries :: (Entry -> a -> a) -> a -> (String -> a) -> Entries -> a | ||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||
unfoldEntries :: (a -> Either String (Maybe (Entry, a))) -> a -> Entries | ||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||
Produced by Haddock version 2.7.2 |