Tar File Manual

1 Opening and Closing Tar Files
2 Tar Archive Types
3 Entries
4 Conditions

[in package TAR-FILE]

This project provides functionality to read and write a variety of tar archive formats. Currently supported are the POSIX ustar, PAX (ustar with a few new entry types), GNU, and v7 (very old) formats.

This project is rather low level and is focused exclusively on reading and writing physical tar file entries using streams. Therefore, it contains no functionality to automatically build archives from a set of files on the filesystem or write the contents of a file to the filesystem. Additionally, there are no smarts that read multiple physical entries and combine them into a single logical entry (e.g., with PAX extended headers or GNU long link/path name support). This approach is taken to both improve portability (the CL spec has no facility for things like detecting symlinks or modifying/reading file owners, etc.) and properly separate concerns.

For a higher level library that reads and writes logical entries, as well as includes file system integration, see cl-tar.

This project is a fork of Nathan Froyd's archive library. Much code remains, but the non-portable bits have been stripped, better support for multiple archive types (and autodetection) has been added, better blocking support added (tar readers/writers are supposed to read/write in multiples of 512 bytes), cpio support removed, and a test suite added, along with other miscellaneous fixes and improvements.

One major user visible difference between this library and the original archive is that there is no need to discard entries when you are finished with them and support has been added for seeking within a stream (using FILE-POSITION under the hood). This means you can do something like iterate over all entries in one go and then get a stream containing the contents of an arbitrary entry.

However, care must be taken if you hop around in a tar file as it will only work if the underlying stream containing the tar archive is seekable. Typically, streams backed by files are seekable, but all other input streams (including stdin) are not. Therefore if there is any chance your code that uses tar-file will read files from non-seekable streams, you should process entries sequentially and completely before moving on to the next one. Alternatively, you can set the blocking factor high enough that the entire file is read into memory at once (yikes!).

← ↑ → ↺

1 Opening and Closing Tar Files

[variable] *DEFAULT-HEADER-ENCODING* :LATIN-1

The default encoding to use for strings read from/written to tar headers. Must be recognized by Babel.

[macro] WITH-OPEN-TAR-FILE (TAR-FILE-VAR PATHNAME-OR-STREAM &KEY (DIRECTION :INPUT) (IF-EXISTS NIL) (IF-DOES-NOT-EXIST NIL) (TYPE :AUTO) (BLOCKING-FACTOR 20) (HEADER-ENCODING '*DEFAULT-HEADER-ENCODING*)) &BODY BODY

Bind TAR-FILE-VAR to a newly opened TAR-FILE, backed by PATHNAME-OR-STREAM. If PATHNAME-OR-STREAM evaluates to a stream, that stream is used directly, otherwise, it is opened via OPEN. If PATHNAME-OR-STREAM is a stream, that stream is not closed upon exiting the body of the macro.

DIRECTION must be either :INPUT or :OUTPUT.

IF-EXISTS and IF-DOES-NOT-EXIST are passed to OPEN if PATHNAME-OR-STREAM is not a stream.

See OPEN-TAR-FILE for a description of TYPE, BLOCKING-FACTOR, and HEADER-ENCODING.

[function] OPEN-TAR-FILE STREAM &KEY (DIRECTION :INPUT) (TYPE :AUTO) (BLOCKING-FACTOR 20) (HEADER-ENCODING *DEFAULT-HEADER-ENCODING*)

Create a TAR-FILE object backed by STREAM. The STREAM should not be read from or written to any more.

DIRECTION is either :INPUT or :OUTPUT.

BLOCKING-FACTOR is an integer that specifies how many 512-byte blocks should be read from or written to STREAM at any one time.

TYPE is either AUTO or a class designator for a subclass of TAR-FILE. If :AUTO, the appropriate class will be determined by looking at the first tar header.

HEADER-ENCODING is an encoding specifier recognized by Babel.

[generic-function] FINALIZE-TAR-FILE TAR-FILE

Perform any necessary processing for finalizing TAR-FILE. This function must be called prior to calling CLOSE-TAR-FILE.

[generic-function] CLOSE-TAR-FILE TAR-FILE

Closes the stream associated with TAR-FILE and the tar-file itself. Further operations on the tar-file are undefined.

Does NOT close the underlying STREAM that backed the TAR-FILE.

← ↑ → ↺

2 Tar Archive Types

There are three different types of tar archives that this system can handle, with a common base class.

[class] TAR-FILE

Base class of a tar file.

[class] USTAR-TAR-FILE TAR-FILE

A ustar tar file.

[class] GNU-TAR-FILE TAR-FILE

A gnu tar file.

[class] V7-TAR-FILE TAR-FILE

A v7 tar file.

← ↑ → ↺

3 Entries

[macro] DO-ENTRIES (ENTRY TAR-FILE &OPTIONAL RESULT) &BODY BODY

Iterate over the entries in TAR-FILE. For each entry, ENTRY is bound to an ENTRY representing the entry. RESULT is used as in DOTIMES.

[generic-function] READ-ENTRY TAR-FILE

Return the next entry in TAR-FILE or NIL if there is no next entry

[class] ENTRY

Base class for all entries in a tar file.

[generic-function] ENTRY-HAS-DATA-P ENTRY

Returns non-NIL if ENTRY has associated data that can be read using MAKE-ENTRY-STREAM.

[generic-function] MAKE-ENTRY-STREAM ENTRY

Returns a new binary stream that contains ENTRY's data.

[generic-function] NAME ENTRY

Return the name of the ENTRY (a string).

[generic-function] SIZE ENTRY

Return the size of the ENTRY (an integer).

[generic-function] UNAME ENTRY

Return the uname of the ENTRY (a string).

[generic-function] GNAME ENTRY

Return the gname of the ENTRY (a string).

[generic-function] MODE ENTRY

Return the mode of the ENTRY (an integer).

[generic-function] MTIME ENTRY

Return the mtime of the ENTRY (an integer).

[generic-function] UID ENTRY

Return the uid of the ENTRY (an integer).

[generic-function] GID ENTRY

Return the gid of the ENTRY (an integer).

[generic-function] LINKNAME ENTRY

Return the linkname of the ENTRY (a string).

[generic-function] DEVMAJOR ENTRY

Return the major device of the ENTRY (an integer).

[generic-function] DEVMINOR ENTRY

Return the minor device of the ENTRY (an integer).

[generic-function] PREFIX ENTRY

Return the prefix of the ENTRY (a string).

[generic-function] ATIME ENTRY

Return the atime of the ENTRY (an integer).

[generic-function] CTIME ENTRY

Return the ctime of the ENTRY (an integer).

[generic-function] OFFSET ENTRY

Return the offset of the ENTRY (an integer).

[generic-function] OFFSET-SPARSE-0 ENTRY

Return the offset of the first sparse block of the ENTRY (an integer).

[generic-function] NUMBYTES-SPARSE-0 ENTRY

Return the numbytes of the first sparse block of the ENTRY (an integer).

[generic-function] OFFSET-SPARSE-1 ENTRY

Return the offset of the second sparse block of the ENTRY (an integer).

[generic-function] NUMBYTES-SPARSE-1 ENTRY

Return the numbytes of the second sparse block of the ENTRY (an integer).

[generic-function] OFFSET-SPARSE-2 ENTRY

Return the offset of the third sparse block of the ENTRY (an integer).

[generic-function] NUMBYTES-SPARSE-2 ENTRY

Return the numbytes of the third sparse block of the ENTRY (an integer).

[generic-function] OFFSET-SPARSE-3 ENTRY

Return the offset of the fourth sparse block of the ENTRY (an integer).

[generic-function] NUMBYTES-SPARSE-3 ENTRY

Return the numbytes of the fourth sparse block of the ENTRY (an integer).

[generic-function] ISEXTENDED ENTRY

Return the isextended field of the ENTRY (an integer).

[generic-function] REALSIZE ENTRY

Return the realsize of the ENTRY (an integer).

[generic-function] ATTRIBUTE ENTRY NAME &OPTIONAL DEFAULT

Get the NAME attribute from ENTRY.

[generic-function] ATTRIBUTE-NAMES ENTRY

Return a list of attribute names contained within ENTRY.

[macro] DO-ATTRIBUTES (NAME VALUE ENTRY &OPTIONAL RESULT) &BODY BODY

Given a PAX ENTRY with attributes, execute BODY for every attribute, with NAME bound to the attribute name and VALUE bound to the attribute value.

← ↑ → ↺

3.1 File Entry

[class] FILE-ENTRY ENTRY HAS-DATA-MIXIN

A regular file.

[generic-function] WRITE-FILE-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID SIZE DATA PREFIX

Write a FILE-ENTRY to TAR-FILE.

DATA can be either NIL (no data is written), an octet vector (written as is), a string (encoded using UTF-8 and written), or a PATHNAME (opened, read, and written to the archive).

[generic-function] ENTRY-FILE-P ENTRY

Returns non-NIL if ENTRY denotes a regular file.

← ↑ → ↺

3.2 Symbolic Link Entry

[class] SYMBOLIC-LINK-ENTRY ENTRY

A symbolic link.

[generic-function] WRITE-SYMBOLIC-LINK-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID LINKNAME PREFIX

Write a SYMBOLIC-LINK-ENTRY to TAR-FILE.

[generic-function] ENTRY-SYMBOLIC-LINK-P ENTRY

Returns non-NIL if ENTRY denotes a symbolic link.

← ↑ → ↺

3.3 Hard Link Entry

[class] HARD-LINK-ENTRY ENTRY

A hard link.

[generic-function] WRITE-HARD-LINK-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID LINKNAME PREFIX

Write a HARD-LINK-ENTRY to TAR-FILE.

[generic-function] ENTRY-HARD-LINK-P ENTRY

← ↑ → ↺

3.4 Character Device Entry

[class] CHARACTER-DEVICE-ENTRY ENTRY

A character device.

[generic-function] WRITE-CHARACTER-DEVICE-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID DEVMAJOR DEVMINOR PREFIX

Write a CHARACTER-DEVICE-ENTRY to TAR-FILE.

[generic-function] ENTRY-CHARACTER-DEVICE-P ENTRY

Returns non-NIL if ENTRY denotes a character device.

← ↑ → ↺

3.5 Block Device Entry

[class] BLOCK-DEVICE-ENTRY ENTRY

A block device.

[generic-function] WRITE-BLOCK-DEVICE-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID DEVMAJOR DEVMINOR PREFIX

Write a BLOCK-DEVICE-ENTRY to TAR-FILE.

[generic-function] ENTRY-BLOCK-DEVICE-P ENTRY

Returns non-NIL if ENTRY denotes a block device.

← ↑ → ↺

3.6 Fifo Entry

[class] FIFO-ENTRY ENTRY

A FIFO.

[generic-function] WRITE-FIFO-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID PREFIX

Write a FIFO-ENTRY to TAR-FILE.

[generic-function] ENTRY-FIFO-P ENTRY

Returns non-NIL if ENTRY denotes a fifo.

← ↑ → ↺

3.7 Directory Entry

[class] DIRECTORY-ENTRY ENTRY

A directory.

[generic-function] WRITE-DIRECTORY-ENTRY TAR-FILE NAME &REST ARGS &KEY UNAME GNAME MODE MTIME UID GID SIZE PREFIX

Write a DIRECTORY-ENTRY to TAR-FILE.

[generic-function] ENTRY-DIRECTORY-P ENTRY

Returns non-NIL if ENTRY denotes a directory.

← ↑ → ↺

3.8 Pax Extended Attributes Entry

[class] PAX-EXTENDED-ATTRIBUTES-ENTRY PAX-ATTRIBUTES-ENTRY

Extended attributes for the subsequent record.

[generic-function] WRITE-PAX-EXTENDED-ATTRIBUTES-ENTRY TAR-FILE NAME &REST ARGS &KEY ATTRIBUTES

Write a PAX-EXTENDED-ATTRIBUTES-ENTRY to TAR-FILE.

ATTRIBUTES must be either a hash table mapping strings to strings or an alist mapping strings to strings. If it is an alist, ordering is preserved.

[generic-function] ENTRY-PAX-EXTENDED-ATTRIBUTES-P ENTRY

Returns non-NIL if ENTRY contains PAX extended attributes.

← ↑ → ↺

3.9 Pax Global Attributes Entry

[class] PAX-GLOBAL-ATTRIBUTES-ENTRY PAX-ATTRIBUTES-ENTRY

Extended attributes for all subsequent records.

[generic-function] WRITE-PAX-GLOBAL-ATTRIBUTES-ENTRY TAR-FILE NAME &REST ARGS &KEY ATTRIBUTES

Write a PAX-GLOBAL-ATTRIBUTES-ENTRY to TAR-FILE.

ATTRIBUTES must be either a hash table mapping strings to strings or an alist mapping strings to strings. If it is an alist, ordering is preserved.

[generic-function] ENTRY-PAX-GLOBAL-ATTRIBUTES-P ENTRY

Returns non-NIL if ENTRY contains PAX global attributes.

← ↑ → ↺

3.10 Gnu Long Link Name Entry

[class] GNU-LONG-LINK-NAME-ENTRY ENTRY HAS-DATA-MIXIN

[generic-function] WRITE-GNU-LONG-LINK-NAME-ENTRY TAR-FILE NAME &REST ARGS &KEY DATA

Write a GNU-LONG-LINK-NAME-ENTRY to TAR-FILE.

DATA must be either a string (which is then UTF-8 encoded) or a byte vector.

[generic-function] ENTRY-GNU-LONG-LINK-NAME-P ENTRY

Returns non-NIL if ENTRY contains a GNU long link name.

← ↑ → ↺

3.11 Gnu Long Name Entry

[class] GNU-LONG-NAME-ENTRY ENTRY HAS-DATA-MIXIN

[generic-function] WRITE-GNU-LONG-NAME-ENTRY TAR-FILE NAME &REST ARGS &KEY DATA

Write a GNU-LONG-NAME-ENTRY to TAR-FILE.

DATA must be either a string (which is then UTF-8 encoded) or a byte vector.

[generic-function] ENTRY-GNU-LONG-NAME-P ENTRY

Returns non-NIL if ENTRY contains a GNU long name.

← ↑ → ↺

3.12 Gnu Directory Dump Entry

[class] GNU-DIRECTORY-DUMP-ENTRY ENTRY HAS-DATA-MIXIN

[generic-function] ENTRY-GNU-DIRECTORY-DUMP-P ENTRY

Returns non-NIL if ENTRY contains a GNU directory dump.

← ↑ → ↺

3.13 Gnu-Sparse-File Entry

[class] GNU-SPARSE-FILE-ENTRY ENTRY HAS-DATA-MIXIN

[generic-function] ENTRY-GNU-SPARSE-FILE-P ENTRY

Returns non-NIL if ENTRY contains a GNU sparse file.

← ↑ → ↺

3.14 Gnu Volume Header Name Entry

[class] GNU-VOLUME-HEADER-NAME-ENTRY ENTRY

[generic-function] ENTRY-GNU-VOLUME-HEADER-NAME-P ENTRY

Returns non-NIL if ENTRY contains a GNU volume header name.

← ↑ → ↺

3.15 Unknown Entry

[class] UNKNOWN-ENTRY ENTRY HAS-DATA-MIXIN

An unknown entry.

[generic-function] ENTRY-UNKNOWN-P ENTRY

Returns non-NIL if ENTRY is unknown.

← ↑ ↺

4 Conditions

[condition] TAR-FILE-ERROR ERROR

All errors signaled are of this type.

[condition] INVALID-CHECKSUM-ERROR TAR-FILE-ERROR

Signaled when the checksum in a tar header is invalid.

[condition] MALFORMED-PAX-ATTRIBUTE-ENTRY TAR-FILE-ERROR

Table of Contents

[in package TAR-FILE]