read -package:base-prelude package:tar

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.

Reads an entire Entry at the given TarEntryOffset in the tar file. The Handle must be open for reading and be seekable. This reads the whole entry into memory strictly, not incrementally. For more control, use hReadEntryHeader and then read the entry content manually.

Read the header for a Entry at the given TarEntryOffset in the tar file. The entryContent will contain the correct metadata but an empty file content. The Handle must be open for reading and be seekable. The Handle position is advanced to the beginning of the entry content (if any). You must check the entryContent to see if the entry is of type NormalFile. If it is, the NormalFile gives the content length and you are free to read this much data from the Handle.

entry <- Tar.hReadEntryHeader hnd
case Tar.entryContent entry of
Tar.NormalFile _ size -> do content <- BS.hGet hnd size
...

Of course you don't have to read it all in one go (as hReadEntry does), you can use any appropriate method to read it incrementally. In addition to I/O errors, this can throw a FormatError if the offset is wrong, or if the file is not valid tar format. There is also the lower level operation hSeekEntryOffset.

This is a low level variant on hReadEntryHeader, that can be used to iterate through a tar file, entry by entry. It has a few differences compared to hReadEntryHeader:

• It returns an indication when the end of the tar file is reached.
• It does not move the Handle position to the beginning of the entry content.
• It returns the TarEntryOffset of the next entry.

After this action, the Handle position is not in any useful place. If you want to skip to the next entry, take the TarEntryOffset returned and use hReadEntryHeaderOrEof again. Or if having inspected the Entry header you want to read the entry content (if it has one) then use hSeekEntryContentOffset on the original input TarEntryOffset.