# (lispkit archive tar)

Library `(lispkit archive tar)` provides an API for creating and managing tar archives. `(lispkit archive tar)` manages tar archives fully in memory, i.e. they are created and mutated in memory and can be saved and loaded from disk. A tar archive is made up of file objects, also called *tar entries*, which consist of the actual file data, compressed or uncompressed, as well as metadata, such as creation and modification date and file permissions.

### Constructors

**(make-tar-archive)**  <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(make-tar-archive&#x20;*****bytevector*****)**\
\&#xNAN;**(make-tar-archive&#x20;*****bytevector start*****)**\
\&#xNAN;**(make-tar-archive&#x20;*****bytevector start end*****)**

Returns a new tar archive. If no argument is provided, a new, empty tar archive object is created. Otherwise, a tar archive is created from the binary data provided by *bytevector* between indices *start* and *end*.

If is an error if *bytevector*, between *start* and *end*, is not encoded using a supported tar encoding. At this point, the basic tar format and POSIX encodings *ustar* and *pax* are supported. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.

### Reading and writing archives

**(load-tar-archive&#x20;*****filepath*****)**   <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Loads the tar file at path *filepath* and stores its content in a new tar archive object in memory. This new object is returned by `load-tar-archive`. It is an error if the file at the given file path is not in a supported tar file format. Supported tar file formats are the basic tar format as well as the two POSIX encodings *ustar* and *pax*.

**(save-tar-archive&#x20;*****archive*****)**   <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(save-tar-archive&#x20;*****archive filepath*****)**

Saves the given tar *archive* at path *filepath* using the *pax* encoding. If the archive was previously loaded from disk, then it is possible to omit parameter *filepath* and overwrite the previously loaded archive at the same location on disk.

### Properties of archives

**tar-archive-type-tag**   <img src="/files/viHiVHsCY8Wn2TeCgWJj" alt="" data-size="line">

Symbol representing the `tar-archive` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all tar archive objects.

**(tar-archive?&#x20;*****obj*****)**   <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns `#t` if *obj* is a tar archive object; otherwise `#f` is returned.

**(tar-archive-path&#x20;*****archive*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the file path of *archive* or `#f` if *archive* was not loaded from disk, i.e. it was created via `make-tar-archive`.

**(tar-archive-bytevector&#x20;*****archive*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Procedure `tar-archive-bytevector` returns *archive* encoded using the *pax* format into a bytevector. This bytevector can be written to disk or used to create an in-memory copy of the tar archive via `make-tar-archive`.

**(tar-entry-count&#x20;*****archive*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the number of entries in tar *archive*.

**(tar-entries&#x20;*****archive*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(tar-entries&#x20;*****archive prefix*****)**

Returns a list of file paths for all entries of tar *archive* which have *prefix* as their file path prefix. If *prefix* is not given, the file paths of all entries are being returned as a list.

### Introspecting entries

Entries in zip archives are referred to via their relative file path in the archive. All procedures that provide information about a zip archive entry therefore expect two arguments: the zip archive and a file path.

**(tar-entry-exists?&#x20;*****archive path*****)**   <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(tar-entry-exists?&#x20;*****archive path prefix?*****)**

Returns `#t` if *archive* contains an entry for *path* (string) if *prefix?* is `#f`, or *archive* contains an entry whose path is a prefix of *path* if *prefix?* is `#t`.

**(tar-entry-file?&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns `#t` if *archive* contains an entry for the given path and this entry is a file. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-file?` fails with an error.

**(tar-entry-directory?&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns `#t` if *archive* contains an entry for the given path and this entry is a directory. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-directory?` fails with an error.

**(tar-entry-symlink?&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns `#t` if *archive* contains an entry for the given path and this entry is a symbolic link. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-symlink?` fails with an error.

**(tar-entry-linked&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

If *archive* contains an entry for the given *path* and this entry is a symbolic link, then procedure `tar-entry-linked` returns the path of the linked file as a string, otherwise `#f` is returned. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-linked` fails with an error.

**(tar-entry-creation-date&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the creation date of the entry to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.

**(tar-entry-modification-date&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the modification date of the entry to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.

**(tar-entry-permissions&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the access permissions of the entry to which *path* refers to in *archive* as a fixnum (Unix style). If there is no entry in *archive* for the given *path*, `#f` gets returned.

Permission numbers can be created by selecting from the following attributes and summing up the corresponding values: *Read by owner* (400), *Write by owner* (200), *Execute by owner* (100), *Read by group* (040), *Write by group* (020), *Execute by group* (010), *Read by others* (004), *Write by others* (002), *Execute by others* (001).

**(tar-entry-size&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the size of the entry in bytes to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.

**(tar-entry-data&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns the data of the entry to which *path* refers to in *archive* as a bytevector. If there is no entry in *archive* for the given *path*, `#f` gets returned.

### Adding and removing entries

**(add-tar-entry!&#x20;*****archive path base*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(add-tar-entry!&#x20;*****archive path base recursive?*****)**

Adds the file, directory, or symbolic link at *path* relative to path *base* to the given tar *archive*. The corresponding entry in *archive* is identified via *path*. If the entry is a directory and parameter *recursive?* is true, all entries in the directory are added to *archive* as well.

**(set-tar-entry!&#x20;*****archive path content*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(set-tar-entry!&#x20;*****archive path content mdate*****)**\
\&#xNAN;**(set-tar-entry!&#x20;*****archive path content mdate permissions*****)**

Adds or overwrites the entry in *archive* at *path*. Parameter *content* determines whether the new entry is a file, directory, or symbolic link. If *content* is a bytevector, the new entry is a file containing the data of the bytevector. If *content* is a string, it represents a path of a symbolic link. If *content* is `()`, the new entry is a directory.

The creation date of the new entry is the current date, the modification date is *mdate* or the current date if *mdate* is not provided. The permissions are *permissions* or an entry type specific default (`644` for files, and `755` otherwise).

**(delete-tar-entry!&#x20;*****archive path*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(delete-tar-entry!&#x20;*****archive path prefix?*****)**

Deletes the entry at *path* from *archive*. If argument *prefix?* is true, *path* is interpreted as a prefix and all entries with prefix *path* are deleted.

### Extracting entries

**(extract-tar-entry&#x20;*****archive path base*****)** <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">\
\&#xNAN;**(extract-tar-entry&#x20;*****archive path base prefix?*****)**

Extracts the entry at *path* in *archive* and stores it on the file system at *path* relative to path *base*. If *prefix?* is true, all entries with prefix *path* are extracted.

**(get-tar-entry&#x20;*****archive path*****)**   <img src="/files/STqjiJsrexexyFklGQwH" alt="" data-size="line">

Returns a representation of the entry at *path* in *archive*. If the entry is a file, `get-tar-entry` returns the content of this file as a bytevector. If the entry is a symbolic link, then the target of the link is returned as a string. If the entry is a directory, `()` is returned. The procedure fails if the entry does not exist.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.lisppad.app/libraries/lispkit/lispkit-archive-tar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.