Documentation

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

Since: 0.6.0.0

Monomorphic tar archive entry, ready for serialization / deserialization.

Native FilePath of the file or directory within the archive.

Polymorphic content of a tar archive entry. High-level interfaces commonly work with GenEntryContent FilePath, while low level uses 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.

The number of seconds since the UNIX epoch

There have been a number of extensions to the tar file format over the years. They all share the basic entry fields and put more meta-data in different extended headers.

An GenEntry with all default values except for the file name and type. It uses the portable USTAR/POSIX format (see UstarFormat).

You can use this as a basis and override specific fields, eg:

(emptyEntry name HardLink) { linkTarget = target }

GNU extension to store a filepath too long to fit into entryTarPath as OtherEntryType 'L' with the full filepath as entryContent. The next entry must contain the actual data with truncated entryTarPath.

See What exactly is the GNU tar ..@LongLink "trick"?

Since: 0.6.0.0

GNU extension to store a link target too long to fit into entryTarPath as OtherEntryType 'K' with the full filepath as entryContent. The next entry must contain the actual data with truncated entryTarPath.

Since: 0.6.0.0

A tar GenEntry for a file.

Entry fields such as file permissions and ownership have default values.

You can use this as a basis and override specific fields. For example if you need an executable file you could use:

(fileEntry name content) { fileMode = executableFileMode }

A tar GenEntry for a symbolic link.

A tar GenEntry for a directory.

Entry fields such as file permissions and ownership have default values.

rw-r--r-- for normal files

rw-r--r-- for normal files

Since: 0.6.0.0

rwxr-xr-x for executable files

rwxr-xr-x for directories

The classic tar format allowed just 100 characters for the file name. The USTAR format extended this with an extra 155 characters, however it uses a complex method of splitting the name between the two sections.

Instead of just putting any overflow into the extended area, it uses the extended area as a prefix. The aggravating insane bit however is that the prefix (if any) must only contain a directory prefix. That is the split between the two areas must be on a directory separator boundary. So there is no simple calculation to work out if a file name is too long. Instead we have to try to find a valid split that makes the name fit in the two areas.

The rationale presumably was to make it a bit more compatible with old tar programs that only understand the classic format. A classic tar would be able to extract the file name and possibly some dir prefix, but not the full dir prefix. So the files would end up in the wrong place, but that's probably better than ending up with the wrong names too.

So it's understandable but rather annoying.

• Tar paths use Posix format (ie '/' directory separators), irrespective of the local path conventions.
• The directory separator between the prefix and name is not stored.

Convert a native FilePath to a TarPath.

The conversion may fail if the FilePath is empty or too long. Use toTarPath' for a structured output.

Convert a native FilePath to a TarPath. Directory paths must always have a trailing /, this is not checked.

Since: 0.6.0.0

Return type of toTarPath'.

Since: 0.6.0.0

Convert a TarPath to a native FilePath.

The native FilePath will use the native directory separator but it is not otherwise checked for validity or sanity. In particular:

• The tar path may be invalid as a native path, eg the file name "nul" is not valid on Windows.
• The tar path may be an absolute path or may contain ".." components. For security reasons this should not usually be allowed, but it is your responsibility to check for these conditions (e.g., using checkEntrySecurity).

Convert a TarPath to a Unix/Posix FilePath.

The difference compared to fromTarPath is that it always returns a Unix style path irrespective of the current operating system.

This is useful to check how a TarPath would be interpreted on a specific operating system, eg to perform portability checks.

Convert a TarPath to a Windows FilePath.

The only difference compared to fromTarPath is that it always returns a Windows style path irrespective of the current operating system.

This is useful to check how a TarPath would be interpreted on a specific operating system, eg to perform portability checks.

Convert a unix FilePath to a native FilePath.

The tar format allows just 100 ASCII characters for the SymbolicLink and HardLink entry types.

Convert a native FilePath to a tar LinkTarget. string is longer than 100 characters or if it contains non-portable characters.

Convert a tar LinkTarget to a native FilePath.

Convert a tar LinkTarget to a Unix/POSIX FilePath ('/' path separators).

Convert a tar LinkTarget to a Windows FilePath ('\\' path separators).

Convert a unix FilePath to a Windows FilePath.

Polymorphic sequence of archive entries. High-level interfaces commonly work with GenEntries FilePath FilePath, while low level uses 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.