Tar File Manual¶

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!).

Opening and Closing Tar Files¶

• [variable]
  tar-file:*default-header-encoding*
  :latin-1

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

• [macro]
  tar-file:with-open-tar-file
  (tar-file-var pathname-or-stream &key (direction :input) (if-exists nil) (if-does-not-exist nil) (type :auto) (compression :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, HEADER-ENCODING, and COMPRESSION.

• [function]
  tar-file:open-tar-file
  stream &key (direction :input) (type :auto) (blocking-factor 20) (header-encoding \*default-header-encoding\*) (compression :auto)

  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.

  COMPRESSION determines what compression scheme is used, if any. It can be either :AUTO (the default), NIL (no compression), or :GZIP. If :AUTO, the compression type is determined using the PATHNAME of the stream (for :OUTPUT) or by peeking at the stream for magic numbers (for :INPUT).

• [generic-function]
  tar-file: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]
  tar-file: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.

Tar Archive Types¶

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

• [class]
  tar-file:tar-file

  Base class of a tar file.

• [class]
  tar-file:ustar-tar-file

  A ustar tar file.

• [class]
  tar-file:gnu-tar-file

  A gnu tar file.

• [class]
  tar-file:v7-tar-file

  A v7 tar file.

Entries¶

• [macro]
  tar-file: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]
  tar-file:read-entry
  tar-file

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

• [class]
  tar-file:entry

  Base class for all entries in a tar file.

• [generic-function]
  tar-file:entry-has-data-p
  entry

  Returns non-NIL if ENTRY has associated data that can be read using make-entry-stream.

• [generic-function]
  tar-file:make-entry-stream
  entry

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

• [generic-function]
  tar-file:name
  entry

  Return the name of the ENTRY (a string).

• [generic-function]
  tar-file:size
  entry

  Return the size of the ENTRY (an integer).

• [generic-function]
  tar-file:uname
  entry

  Return the uname of the ENTRY (a string).

• [generic-function]
  tar-file:gname
  entry

  Return the gname of the ENTRY (a string).

• [generic-function]
  tar-file:mode
  entry

  Return the mode of the ENTRY (an integer).

• [generic-function]
  tar-file:mtime
  entry

  Return the mtime of the ENTRY (an integer).

• [generic-function]
  tar-file:uid
  entry

  Return the uid of the ENTRY (an integer).

• [generic-function]
  tar-file:gid
  entry

  Return the gid of the ENTRY (an integer).

• [generic-function]
  tar-file:linkname
  entry

  Return the linkname of the ENTRY (a string).

• [generic-function]
  tar-file:devmajor
  entry

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

• [generic-function]
  tar-file:devminor
  entry

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

• [generic-function]
  tar-file:prefix
  entry

  Return the prefix of the ENTRY (a string).

• [generic-function]
  tar-file:atime
  entry

  Return the atime of the ENTRY (an integer).

• [generic-function]
  tar-file:ctime
  entry

  Return the ctime of the ENTRY (an integer).

• [generic-function]
  tar-file:offset
  entry

  Return the offset of the ENTRY (an integer).

• [generic-function]
  tar-file:offset-sparse-0
  entry

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

• [generic-function]
  tar-file:numbytes-sparse-0
  entry

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

• [generic-function]
  tar-file:offset-sparse-1
  entry

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

• [generic-function]
  tar-file:numbytes-sparse-1
  entry

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

• [generic-function]
  tar-file:offset-sparse-2
  entry

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

• [generic-function]
  tar-file:numbytes-sparse-2
  entry

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

• [generic-function]
  tar-file:offset-sparse-3
  entry

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

• [generic-function]
  tar-file::numbytes-sparse-3
  entry

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

• [generic-function]
  tar-file:isextended
  entry

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

• [generic-function]
  tar-file:realsize
  entry

  Return the realsize of the ENTRY (an integer).

• [generic-function]
  tar-file:attribute
  entry name &optional default

  Get the NAME attribute from ENTRY.

• [generic-function]
  tar-file:attribute-names
  entry

  Return a list of attribute names contained within ENTRY.

• [macro]
  tar-file: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.

File Entry¶

• [class]
  tar-file:file-entry

  A regular file.

• [generic-function]
  tar-file: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]
  tar-file:entry-file-p
  entry

  Returns non-NIL if ENTRY denotes a regular file.

Symbolic Link Entry ¶

• [class]
  tar-file:symbolic-link-entry

  A symbolic link.

• [generic-function]
  tar-file: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]
  tar-file:entry-symbolic-link-p
  entry

  Returns non-NIL if ENTRY denotes a symbolic link.

Hard Link Entry¶

• [class]
  tar-file:hard-link-entry

  A hard link.

• [generic-function]
  tar-file: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]
  tar-file:entry-hard-link-p
  entry

Character Device Entry ¶

• [class]
  tar-file:character-device-entry

  A character device.

• [generic-function]
  tar-file: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]
  tar-file:entry-character-device-p
  entry

  Returns non-NIL if ENTRY denotes a character device.

Block Device Entry ¶

• [class]
  tar-file:block-device-entry

  A block device.

• [generic-function]
  tar-file: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]
  tar-file:entry-block-device-p
  entry

  Returns non-NIL if ENTRY denotes a block device.

Fifo Entry¶

• [class]
  tar-file:fifo-entry

  A FIFO.

• [generic-function]
  tar-file: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]
  tar-file:entry-fifo-p
  entry

  Returns non-NIL if ENTRY denotes a fifo.

Directory Entry¶

• [class]
  tar-file:directory-entry

  A directory.

• [generic-function]
  tar-file: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]
  tar-file:entry-directory-p
  entry

  Returns non-NIL if ENTRY denotes a directory.

Pax Extended Attributes Entry ¶

• [class]
  tar-file:pax-extended-attributes-entry

  Extended attributes for the subsequent record.

• [generic-function]
  tar-file: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]
  tar-file:entry-pax-extended-attributes-p
  entry

  Returns non-NIL if ENTRY contains PAX extended attributes.

Pax Global Attributes Entry ¶

• [class]
  tar-file:pax-global-attributes-entry

  Extended attributes for all subsequent records.

• [generic-function]
  tar-file: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]
  tar-file:entry-pax-global-attributes-p
  entry

  Returns non-NIL if ENTRY contains PAX global attributes.

Gnu Long Link Name Entry ¶

• [class]
  tar-file:gnu-long-link-name-entry

• [generic-function]
  tar-file: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]
  tar-file:entry-gnu-long-link-name-p
  entry

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

Gnu Long Name Entry ¶

• [class]
  tar-file:gnu-long-name-entry

• [generic-function]
  tar-file: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]
  tar-file:entry-gnu-long-name-p
  entry

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

Gnu Directory Dump Entry ¶

• [class]
  tar-file:gnu-directory-dump-entry

• [generic-function]
  tar-file:entry-gnu-directory-dump-p
  entry

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

Gnu-Sparse-File Entry ¶

• [class]
  tar-file:gnu-sparse-file-entry

• [generic-function]
  tar-file:entry-gnu-sparse-file-p
  entry

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

Gnu Volume Header Name Entry ¶

• [class]
  tar-file:gnu-volume-header-name-entry

• [generic-function]
  tar-file:entry-gnu-volume-header-name-p
  entry

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

Unknown Entry¶

• [class]
  tar-file:unknown-entry

  An unknown entry.

• [generic-function]
  tar-file:entry-unknown-p
  entry

  Returns non-NIL if ENTRY is unknown.

Conditions¶

• [condition]
  tar-file:tar-file-error

  All errors signaled are of this type.

• [condition]
  tar-file:invalid-checksum-error

  Signaled when the checksum in a tar header is invalid.

• [condition]
  tar-file:malformed-pax-attribute-entry