.. _cartridge.tar:

===============================================================================
Module *cartridge.tar*
===============================================================================

Handle basic tar format.



<http://www.gnu.org/software/tar/manual/html_node/Standard.html>

While an archive may contain many files, the archive itself is a
single ordinary file. Physically, an archive consists of a series of
file entries terminated by an end-of-archive entry, which consists of
two 512 blocks of zero bytes. A file entry usually describes one of
the files in the archive (an archive member), and consists of a file
header and the contents of the file. File headers contain file names
and statistics, checksum information which tar uses to detect file
corruption, and information about file types.

A tar archive file contains a series of blocks. Each block contains
exactly 512 (`BLOCKSIZE`) bytes:

.. code-block:: lua 
 
    +---------+-------+-------+-------+---------+-------+-----
    | header1 | file1 |  ...  |  ...  | header2 | file2 | ...
    +---------+-------+-------+-------+---------+-------+-----
    

All characters in header blocks are represented by using 8-bit
characters in the local variant of ASCII. Each field within the
structure is contiguous; that is, there is no padding used within the
structure. Each character on the archive medium is stored
contiguously. Bytes representing the contents of files (after the
header block of each file) are not translated in any way and are not
constrained to represent characters in any character set. The tar
format does not distinguish text files from binary files, and no
translation of file contents is performed.


-------------------------------------------------------------------------------
Functions
-------------------------------------------------------------------------------


.. _cartridge.tar.pack:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pack (files)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create TAR archive.


**Parameters:**

- *files:* (`{string=string} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) The archive


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.tar.unpack:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
unpack (tar)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Parse TAR archive. 

Only regular files are extracted, directories are ommitted.



**Parameters:**

- *tar:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(`{string=string} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Extracted files (their names and content)


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


