Tar¶

This project provides a high level interface for interacting with tar archives. It consists of several systems that provide different levels of functionality.

NOTE: In order to load tar/create on Windows you need a version of osicat with commits from this PR.

Quickstart

If you want to extract a tar archive, without caring about preserving all the metadata, run the following:

(asdf:load-system "tar/simple-extract")

(tar:with-open-archive (a "/path/to/file.tar")
  (tar-simple-extract:simple-extract-archive a :directory "/path/to/extraction/point/"))

If you want to extract a tar archive, attempting to preserve symbolic links and as much metadata as possible, evaluate the following:

(asdf:load-system "tar/extract")

(tar:with-open-archive (a "/path/to/file.tar")
  (tar-extract:extract-archive a :directory "/path/to/extraction/point/"))

If you want to create a tar archive, attempting to preserve symbolic links and as much metadata as possible, evaluate the following:

(asdf:load-system "tar/create")

(let ((*default-pathname-defaults* #p"/path/to/parent/"))
  (tar:with-open-archive (a "/path/to/file.tar" :direction :output)
    (tar-create:create-archive a '("directory/") :recursep t)))

Systems

tar

The tar system is a thin layer on top of the tar-file system. While tar-file is focused on reading and writing physical entries, tar places an emphasis on reading and writing logical entries.

The practical effect of this is that when using tar, any single object stored in a tar archive (regular file, symlink, etc.) is always represented as a single entry (tar:file-entry, tar:symbolic-link-entry, etc.). This is in contrast to tar-file where a regular file with a long name could be either unrepresentable, a single tar-file:file-entry with a ustar header, a tar-file:pax-extended-attributes-entry followed by a tar-file:file-entry, or a tar-file:gnu-long-name-entry followed by a tar-file:file-entry. tar takes care of generating and interpreting the correct sequence of physical entries, depending on the type of the archive being used.

While this system is useful for reading and writing tar archives, its primary purpose is for the inspection of archives and creating archives whose content does not come directly from the file system. For file system integration, see the remaining systems.

tar/simple-extract

The tar/simple-extract system provides functionality to extract a tar archive to your filesystem. Unfortunately, faithfully extracting tar files onto the filesystem is a complex task and is impossible to perform using only the functionality mandated by the Common Lisp specification.

Therefore, this system does not try to faithfully reproduce the contents of the tar file. This means that it should work on any CL implementation that tar and tar-file does, but the cost is there is information loss.

This system does not support extracting the following entry types:

• Symbolic links. They can be skipped or dereferenced.

• Hard links. They can be skipped or dereferenced.

• Character devices. They can be skipped.

• Block devices. They can be skipped.

• FIFO. They can be skipped.

Additionally, metadata such as file owner, permissions, and modification time are not set.

It is recommended that this extraction method is used only to extract an archive to an empty folder. If that is done with default settings, the extraction process should be fairly safe and predictable. Otherwise, you run the risk of existing symlinks being followed and overwriting arbitrary files on your machine.

tar/extract

The tar/extract system attempts to provide full extraction functionality. As such, it is a much more complex beast and likely does not work on all implementation/OS combinations. Patches are always welcome to make it more portable.

This system does not support extracting the following entry types on Windows:

• Symbolic links. They can be skipped or dereferenced.

• Hard links. They can be skipped or dereferenced.

• Character devices. They can be skipped.

• Block devices. They can be skipped.

• FIFO. They can be skipped.

While it is possible to create symbolic links on Windows, it requires special user permissions and many Windows applications are not designed with symlinks in mind. This makes it both very unlikely that an arbitrary user can create symlinks and very likely that the creation of symlinks would pose a risk to other applications running on the same machine. Hard link support is also possible, but I've rarely seen it and need to do more research before attempting to support it.

While there is much less information loss when extracting an archive using this system, that comes at the cost of increased security concerns when given an untrusted archive as input. For example, a typical attack vector is to write a symlink that points to an arbitrary file on your system and then using that symlink to modify the target.

The goal of this system is to provide default extraction options so that it is safe to extract an untrusted archive into an empty directory and have no way for the extraction process to modify any file that exists outside of that directory. Bug reports and patches are always welcome if you find this goal is not met.

The safety goal is paramount, and as such, the performance of this system is likely not the best. A primary reason is that we want to be robust to the different file systems that are out there (e.g., case insensitive or unicode normalizing), so we (currently) do not rely on caches to determine if a path is safe to write to. The result is that there are many syscalls that happen during extraction. There are probably ways this can be improved and patches are always welcome.

tar/create

The tar/create system produces a tar file from your file system that faithfully reproduces all the metadata. It is a fairly complex beast and might not work on all implementation/OS combinations. Patches are always welcome to make it more portable.

See the docstring for tar-create:create-archive to understand its options.

FAQ

Can I create/extract compressed tar files?

Yes! It supports transparent gzip comporession. On input streams, the first few bytes are examined for magic bytes. On output streams, the pathname is used as a hint. You can override this behavior using the :compression argument to with-open-archive or open-archive.

Tar¶

This section describes the high level tar archive support.

Tar Archives¶

• [class]
  tar:archive

  The base class of all archives.

• [class]
  tar:gnu-archive

  An archive that uses GNU specific extensions.

• [class]
  tar:pax-archive

  An archive as specified by POSIX. Uses multiple physical entries to represent a single logical entry when values do not fit into the standard ustar-archive header.

• [class]
  tar:ustar-archive

  A ustar archive that adds more fields to the header when compared to v7-archives.

• [class]
  tar:v7-archive

  A very early archive format.

• [function]
  tar:open-archive
  stream-or-path &key (type :auto) (direction :input) (if-exists nil if-exists-supplied-p) (if-does-not-exist nil if-does-not-exist-supplied-p) (blocking-factor 20) (compression :auto) (header-encoding tar-file:\*default-header-encoding\*)

  Create a tar archive object backed by STREAM-OR-PATH. If a stream, it 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 archive. 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:close-archive
  archive

  Close the ARCHIVE, performing any finalization as necessary. If a pathname was passed to open-archive, then the underlying stream is closed, otherwise it remains open.

• [macro]
  tar:with-open-archive
  (archive-var stream-or-path &rest args &key type direction if-exists if-does-not-exist blocking-factor header-encoding compression) &body body

  Evaluate BODY with ARCHIVE-VAR bound to an instance of archive. See open-archive for more discussion of the arguments. If STREAM-OR-PATH is a path, the underlying stream is closed upon exiting the macro. If it is a stream, it remains open.

Tar Entries¶

This section describes the various entry types and how to read/write them from/to an archive.

• [generic-function]
  tar:read-entry
  archive

  Read an entry from ARCHIVE.

• [generic-function]
  tar:write-entry
  archive entry

  Write ENTRY to ARCHIVE.

• [macro]
  tar:do-entries
  (entry archive &optional result) &body body

  Iterate over the entries in archive. For each entry, entry is bound to an entry representing the entry. RESULT is returned.

• [type]
  tar:mode-list

  A list consisting of a subset of: (:SET-USER-ID :SET-GROUP-ID :STICKY :USER-READ :USER-WRITE :USER-EXEC :GROUP-READ :GROUP-WRITE :GROUP-EXEC :OTHER-READ :OTHER-WRITE :OTHER-EXEC)

• [class]
  tar:entry

  The base class of all entry types. Each entry must contain a name, mode, uid, gid, and mtime. Other common properties are uname, gname, atime, and ctime.

• [class]
  tar:directory-entry

  An entry representing a directory.

• [class]
  tar:file-entry

  An entry representing a regular file.

• [class]
  tar:symbolic-link-entry

  An entry representing a symbolic link.

• [class]
  tar:hard-link-entry

  An entry representing a hard link.

• [class]
  tar:fifo-entry

  An entry representing a FIFO.

• [class]
  tar:block-device-entry

  An entry representing a block device.

• [class]
  tar:character-device-entry

  An entry representing a character device.

• [generic-function]
  tar:name
  entry

  The name of ENTRY. Returns a STRING.

• [generic-function]
  tar:size
  entry

  The size of ENTRY. Returns a (INTEGER 0).

• [generic-function]
  tar:uname
  entry

  The uname of ENTRY. Returns a STRING.

• [generic-function]
  tar:gname
  entry

  The gname of ENTRY. Returns a STRING.

• [generic-function]
  tar:mode
  entry

  The mode of ENTRY. Returns a mode-list.

• [generic-function]
  tar:mtime
  entry

  The mtime of ENTRY. Returns a TIMESTAMP.

• [generic-function]
  tar:atime
  entry

  The atime of ENTRY. Returns a TIMESTAMP.

• [generic-function]
  tar:ctime
  entry

  The ctime of ENTRY. Returns a TIMESTAMP.

• [generic-function]
  tar:uid
  entry

  The uid of ENTRY. Returns a (INTEGER 0).

• [generic-function]
  tar:gid
  entry

  The gid of ENTRY. Returns a (INTEGER 0).

• [generic-function]
  tar:linkname
  entry

  The linkname of ENTRY. Returns a STRING.

• [generic-function]
  tar:devmajor
  entry

  The devmajor of ENTRY. Returns a (INTEGER 0).

• [generic-function]
  tar:devminor
  entry

  The devminor of ENTRY. Returns a (INTEGER 0).

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

  Return a binary stream with the contents of ENTRY. Depending on the the type of stream underlying the archive (if it is seekable or not) and the BLOCKING-FACTOR given to open-archive, this may be callable either once or multiple times per entry, may or may not be callable after the next call to read-entry, and the the returned stream may or may not be readable after the next call to read-entry.

  For maximum compatibility, you should call this only once per ENTRY and completely read from the stream before calling read-entry again.

Tar Conditions¶

This section describes the various conditions and restarts in the tar system.

• [condition]
  tar:tar-condition

  The base condition.

• [condition]
  tar:tar-error

  The base error condition.

• [condition]
  tar:unsupported-property

  Signaled when a property is set or accessed that the underlying tar file cannot represent.

• [condition]
  tar:required-property-missing

  Signaled when trying to write-entry with a required property that is missing.

• [reader]
  tar:required-property-missing-name
  (:name)

• [condition]
  tar:unsupported-property-value

  Signaled when trying to write-entry with a property that is unsupported by the underlying archive type.

• [reader]
  tar:unsupported-property-value-name
  (:name)

• [reader]
  tar:unsupported-property-value-value
  (:value)

• [condition]
  tar:property-value-too-long

  Signaled when trying to write-entry with a property that is too long for the underlying archive type.

• [function]
  tar:ignore-unsupported-property
  &optional value condition

  A restart to ignore an unsupported-property CONDITION. Either returns VALUE from the accessor or silently ignores the attempt to set the value.

• [function]
  tar:truncate-value
  &optional condition

  Truncate the value and write it to the archive.

• [macro]
  tar:with-ignored-unsupported-properties
  (&optional value) &body body

  Execute BODY in a context where unsupported-property errors are ignored and VALUE is returned from any attempt to access them.

• [macro]
  tar:with-truncated-unsupported-values
  (&key (properties t)) &body body

  Evaluate BODY in a context where truncatable values are automatically truncated.

Simple Extraction ¶

This section describes the support for simple extraction to the filesystem.

• [function]
  tar-simple-extract:simple-extract-archive
  archive &key (directory \*default-pathname-defaults\*) (absolute-pathnames :error) (device-pathnames :error) (dot-dot :error) (strip-components 0) (if-exists :error) (if-newer-exists :error) (symbolic-links :dereference) (hard-links :dereference) (character-devices :skip) (block-devices :skip) (fifos :skip) (filter (constantly t))

  Extract all entries in ARCHIVE to DIRECTORY.

  DIRECTORY defaults to *DEFAULT-PATHNAME-DEFAULTS* and must be a directory pathname.

  The following options configure how the final pathname of each entry is computed:

  ABSOLUTE-PATHANMES controls what happens when an entry is discovered that has an absolute pathname. It defaults to :ERROR. The possible values are:

  • :ALLOW : Allow the pathname as is.

  • :SKIP : Silently skip the entry.

  • :RELATIVIZE : Strip the leading / and treat it as a relative pathname.

  • :ERROR : Signal an entry-name-is-absolute-error, with the restarts CONTINUE, skip-entry, and relativize-entry-name active.

  DEVICE-PATHNAMES controls what happens when an entry is discovered that has a non-NIL device. It defaults to :ERROR. The possible values are:

  • :ALLOW : Allow the pathname as is.

  • :SKIP : Silently skip the entry.

  • :RELATIVIZE : Strip the device.

  • :ERROR : Signal an entry-name-contains-device-error, with the restarts CONTINUE, skip-entry, and relativize-entry-name active.

  DOT-DOT controls what happens when an entry is discovered that has a name containing .. in a directory component. It defaults to :ERROR. The possible values are:

  • :BACK : Allow the pathname as is, treating .. as :BACK.

  • :SKIP : Silently skip the entry.

  • :ERROR : Signal an ENTRY-NAME-CONTAINS-..-ERROR, with the restarts TREAT-..-AS-BACK and skip-entry active.

  STRIP-COMPONENTS is an integer specifying how many directory and file components to strip. Defaults to 0.

  The following options configure what happens to files that already exist on the filesystem.

  IF-NEWER-EXISTS controls what happens to files that already exist within DIRECTORY if extracting ARCHIVE would overwrite them and the existing file has a more recent mtime. It defaults to :ERROR. The possible values are:

  • NIL, :KEEP : existing files are skipped

  • :SUPERSEDE, :RENAME, :RENAME-AND-DELETE, :NEW-VERSION, :ERROR : Same behavior as OPEN.

  IF-EXISTS controls what happens to files that already exist within DIRECTORY. It defaults to :ERROR. The possible values are:

  • NIL, :KEEP : existing files are skipped

  • :SUPERSEDE, :RENAME, :RENAME-AND-DELETE, :NEW-VERSION, :ERROR : Same behavior as OPEN.

  The following options configure how certain types of entries are extracted.

  SYMBOLIC-LINKS controls how symbolic links are extracted from ARCHIVE. It defaults to :DEREFERENCE. The possible values are:

  • :DEREFERENCE : any symlink entries are instead written as normal files with the contents of the file they point to.

  • :SKIP : Skip the symlink.

  • :ERROR : Signal a extract-symbolic-link-entry-error with the restarts dereference-link and skip-entry active.

  HARD-LINKS controls how hard links are extracted from ARCHIVE. It defaults to :DEREFERENCE. The possible values are:

  • :DEREFERENCE : any hard link entries are instead written as normal files with the contents of the file they point to.

  • :SKIP : Skip the hard link.

  • :ERROR : Signal a extract-hard-link-entry-error with the restarts dereference-link and skip-entry active.

  CHARACTER-DEVICES controls how character devices are extracted from ARCHIVE. It defaults to :SKIP. The possible values are:

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-character-device-entry-error with the restart SKIP-ENTRY active.

  BLOCK-DEVICES controls how block devices are extracted from ARCHIVE. It defaults to :SKIP. The possible values are:

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-block-device-entry-error with the restart SKIP-ENTRY active.

  FIFOS controls how FIFOs are extracted from ARCHIVE. It defaults to :SKIP. The possible values are:

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-fifo-entry-error with the restart SKIP-ENTRY active.

  The following option controls what entries are extracted.

  FILTER defaults to (CONSTANTLY T). Must be a function designator that takes two arguments (the entry and the pathname were it will be extracted) and returns non-NIL if the entry should be extracted.

  If symbolic and hard links are dereferenced, there may be broken or circular links. If that is detected, a broken-or-circular-links-error is signalled with the CONTINUE restart active.

Simple Extraction Conditions ¶

This section describes the conditions that can occur during simple-extract-archive.

• [condition]
  tar-common-extract:extraction-error

  Base class of all errors signaled during archive extraction.

• [condition]
  tar-common-extract:extraction-entry-error

  An extraction error that is specific to an ENTRY.

• [reader]
  tar-common-extract:extraction-entry-error-entry
  (:entry = '\*current-entry\*)

• [condition]
  tar-common-extract:entry-name-contains-device-error

  An entry contains a device in its pathname.

• [condition]
  tar-common-extract:entry-name-contains-..-error

  An entry contains .. in its pathname.

• [condition]
  tar-common-extract:entry-name-is-absolute-error

  An entry pathname is absolute.

• [condition]
  tar-common-extract:extract-character-device-entry-error

  A character device that cannot be extracted.

• [condition]
  tar-common-extract:extract-block-device-entry-error

  A block device that cannot be extracted.

• [condition]
  tar-common-extract:extract-fifo-entry-error

  A FIFO that cannot be extracted.

• [condition]
  tar-common-extract:extract-symbolic-link-entry-error

  A symbolic link that cannot be extracted.

• [condition]
  tar-common-extract:extract-hard-link-entry-error

  A hard link that cannot be extracted.

• [condition]
  tar-common-extract:broken-or-circular-links-error

  A series of symbolic or hard links is broken or circular.

• [function]
  tar-common-extract:dereference-link
  &optional c

  Handle condition C by dereferencing the link.

• [function]
  tar-common-extract:skip-entry
  &optional c

  Handle condition C by skipping the entry.

• [function]
  tar-common-extract:relativize-entry-name
  &optional c

  Handle condition C by relativizing the pathname.

• [function]
  tar-common-extract:treat-..-as-back
  &optional c

  Handle condition C by treating .. as :BACK.

Extraction¶

This section describes the support for non-portable extraction to the filesystem.

• [function]
  tar-extract:extract-archive
  archive &key (directory \*default-pathname-defaults\*) (absolute-pathnames :error) (device-pathnames :error) (dot-dot :error) (strip-components 0) (if-exists :error) (if-newer-exists :error) (if-symbolic-link-exists :error) (if-directory-symbolic-link-exists :error) keep-directory-metadata touch (no-same-owner (rootp)) numeric-uid mask (symbolic-links t) (hard-links t) (character-devices (if (rootp) t :error)) (block-devices (if (rootp) t :error)) (fifos t) (filter (constantly t))

  Extract all entries in ARCHIVE to DIRECTORY.

  DIRECTORY defaults to *DEFAULT-PATHNAME-DEFAULTS* and must be a directory pathname.

  The following options configure how the final pathname of each entry is computed:

  ABSOLUTE-PATHANMES controls what happens when an entry is discovered that has an absolute pathname. It defaults to :ERROR. The possible values are:

  • :ALLOW : Allow the pathname as is.

  • :SKIP : Silently skip the entry.

  • :RELATIVIZE : Strip the leading / and treat it as a relative pathname.

  • :ERROR : Signal an entry-name-is-absolute-error, with the restarts CONTINUE, skip-entry, and relativize-entry-name active.

  DEVICE-PATHNAMES controls what happens when an entry is discovered that has a non-NIL device. It defaults to :ERROR. The possible values are:

  • :ALLOW : Allow the pathname as is.

  • :SKIP : Silently skip the entry.

  • :RELATIVIZE : Strip the device.

  • :ERROR : Signal an entry-name-contains-device-error, with the restarts CONTINUE, skip-entry, and relativize-entry-name active.

  DOT-DOT controls what happens when an entry is discovered that has a name containing .. in a directory component. It defaults to :ERROR. The possible values are:

  • :BACK : Allow the pathname as is, treating .. as :BACK.

  • :SKIP : Silently skip the entry.

  • :ERROR : Signal an ENTRY-NAME-CONTAINS-..-ERROR, with the restarts TREAT-..-AS-BACK and skip-entry active.

  STRIP-COMPONENTS is an integer specifying how many directory and file components to strip. Defaults to 0.

  The following options configure what happens to files that already exist on the filesystem.

  IF-DIRECTORY-SYMBOLIC-LINK-EXISTS controls what happens to existing directories that are symlinks. This includes any symlink on the destination path of the entry. Defaults to :ERROR. The possible values are:

  • :ERROR : Signal a extraction-through-symbolic-link-error with the restarts follow-symbolic-link, replace-symbolic-link, and skip-entry active.

  • NIL, :SKIP : Skip the entry.

  • :SUPERSEDE : replace the symlink with a new, empty directory.

  • :FOLLOW : keep the existing symlink.

  IF-SYMBOLIC-LINK-EXISTS controls what happesn to existing files that are symlinks. Defaults to :ERROR. The possible values are:

  • :ERROR : Signal a extraction-through-symbolic-link-error with the restarts follow-symbolic-link, replace-symbolic-link, and skip-entry active.

  • NIL, :SKIP : Skip the entry.

  • :FOLLOW : Follow the symlink and write the contents of the entry, respecting IF-NEWER-EXISTS and IF-EXISTS.

  • :SUPERSEDE : Replace the symlink.

  IF-NEWER-EXISTS controls what happens to files that already exist within DIRECTORY if extracting ARCHIVE would overwrite them and the existing file has a more recent mtime. It defaults to :ERROR. The possible values are:

  • :ERROR : A destination-exists-error is signaled, with the restarts supersede-file, remove-file, and skip-entry active

  • NIL, :SKIP, :KEEP : existing files are skipped

  • :SUPERSEDE : Overwrite the file

  • :REPLACE : Delete file and replace it, atomically if possible.

  IF-EXISTS controls what happens to files that already exist within DIRECTORY. It defaults to :ERROR. The possible values are:

  • :ERROR : A destination-exists-error is signaled, with the restarts supersede-file, remove-file, and skip-entry active

  • NIL, :SKIP, :KEEP : existing files are skipped

  • :SUPERSEDE : Overwrite the file

  • :REPLACE : Delete file and replace it, atomically if possible.

  The following options configure how metadata is extracted.

  If KEEP-DIRECTORY-METADATA is non-NIL, then metadata for existing directories is kept.

  If TOUCH is non-NIL, file mtimes will not be set on extraction.

  If NO-SAME-OWNER is non-NIL, then the owner and group of extracted entries will not be set. Defaults to T for non-root users and Windows. Must be T on Windows.

  If NUMERIC-UID is non-NIL, UIDs and GIDs are preferred over UNAMEs and GNAMEs.

  MASK is a list of permissions to remove from all entries.

  The following options configure how certain types of entries are extracted.

  SYMBOLIC-LINKS controls how symbolic links are extracted from ARCHIVE. It defaults to T on non-Windows platforms and :DEREFERENCE on Windows. The possible values are:

  • T : Extract the symlink as normal.

  • :DEREFERENCE : any symlink entries are instead written as normal files with the contents of the file they point to.

  • :SKIP : Skip the symlink.

  • :ERROR : Signal a extract-symbolic-link-entry-error with the restarts extract-link, dereference-link and skip-entry active.

  HARD-LINKS controls how hard links are extracted from ARCHIVE. It defaults to T on non-WINDOWS platforms and :DEREFERENCE on Windows. The possible values are:

  • T : Extract the hard link as normal.

  • :DEREFERENCE : any hard link entries are instead written as normal files with the contents of the file they point to.

  • :SKIP : Skip the hard link.

  • :ERROR : Signal a extract-hard-link-entry-error with the restarts extract-link, dereference-link and skip-entry active.

  CHARACTER-DEVICES controls how character devices are extracted from ARCHIVE. It defaults to :ERROR on Windows or non-Windows and the current user is not root, T otherwise. The possible values are:

  • T : Extract the character device.

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-character-device-entry-error with the restarts extract-device and skip-entry active.

  BLOCK-DEVICES controls how block devices are extracted from ARCHIVE. It defaults to :ERROR on Windows or non-Windows and the current user is not root, T otherwise. The possible values are:

  • T : Extract the block device.

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-block-device-entry-error with the restarts extract-device and skip-entry active.

  FIFOS controls how FIFOs are extracted from ARCHIVE. It defaults to T on non-Windows platforms and :ERROR on Windows. The possible values are:

  • T : Extract the FIFO.

  • :SKIP : Skip the entry.

  • :ERROR : Signal a extract-fifo-entry-error with the restarts extract-fifo and skip-entry active.

  The following option controls what entries are extracted.

  FILTER defaults to (CONSTANTLY T). Must be a function designator that takes two arguments (the entry and the pathname were it will be extracted) and returns non-NIL if the entry should be extracted.

  If symbolic and hard links are dereferenced, there may be broken or circular links. If that is detected, a broken-or-circular-links-error is signalled with the CONTINUE restart active.

Extraction Conditions ¶

This section describes the conditions that can occur during extract-archive.

• [condition]
  tar-common-extract:extraction-error

  Base class of all errors signaled during archive extraction.

• [condition]
  tar-common-extract:extraction-entry-error

  An extraction error that is specific to an ENTRY.

• [reader]
  tar-common-extract:extraction-entry-error-entry
  (:entry = '\*current-entry\*)

• [condition]
  tar-common-extract:entry-name-contains-device-error

  An entry contains a device in its pathname.

• [condition]
  tar-common-extract:entry-name-contains-..-error

  An entry contains .. in its pathname.

• [condition]
  tar-common-extract:entry-name-is-absolute-error

  An entry pathname is absolute.

• [condition]
  tar-common-extract:extract-character-device-entry-error

  A character device that cannot be extracted.

• [condition]
  tar-common-extract:extract-block-device-entry-error

  A block device that cannot be extracted.

• [condition]
  tar-common-extract:extract-fifo-entry-error

  A FIFO that cannot be extracted.

• [condition]
  tar-common-extract:extract-symbolic-link-entry-error

  A symbolic link that cannot be extracted.

• [condition]
  tar-common-extract:extract-hard-link-entry-error

  A hard link that cannot be extracted.

• [condition]
  tar-common-extract:broken-or-circular-links-error

  A series of symbolic or hard links is broken or circular.

• [condition]
  tar-extract:destination-exists-error

  Signaled when the destination of an entry exists.

• [condition]
  tar-extract:extraction-through-symbolic-link-error

  Signaled when attempting to extract through a symbolic link.

• [condition]
  tar-extract:file-exists-in-place-of-directory-error

  Signaled when attempting to create a directory when a file already exists.

• [function]
  tar-common-extract:dereference-link
  &optional c

  Handle condition C by dereferencing the link.

• [function]
  tar-common-extract:skip-entry
  &optional c

  Handle condition C by skipping the entry.

• [function]
  tar-common-extract:relativize-entry-name
  &optional c

  Handle condition C by relativizing the pathname.

• [function]
  tar-common-extract:treat-..-as-back
  &optional c

  Handle condition C by treating .. as :BACK.

• [function]
  tar-extract:remove-file
  &optional c

  Handle C by deleting the file.

• [function]
  tar-extract:follow-symbolic-link
  &optional c

  Handle C by following the symbolic link.

• [function]
  tar-extract:replace-symbolic-link
  &optional c

  Handle C by replacing the symbolic link

• [function]
  tar-extract:supersede-file
  &optional c

  Handle C by truncating the file and overwriting it.

• [function]
  tar-extract:extract-link
  &optional c

  Handle C by extracting the link.

• [function]
  tar-extract:extract-device
  &optional c

  Handle C by extracting the device.

• [function]
  tar-extract:extract-fifo
  &optional c

  Handle C by extracting the fifo.

Create¶

This section describes the support for non-portable creation of archives from the filesystem.

• [function]
  tar-create:create-archive
  archive file-list &key prefix recursep dereference-hardlinks-p (filter (constantly t))

  Add all files in FILE-LIST to ARCHIVE. FILE-LIST may be a string, pathname, or a list of strings or pathnames. All relative pathname designators are relative to *DEFAULT-PATHNAME-DEFAULTS*. If an item in FILE-LIST designates an absolute pathname, the corresponding entry in the tar file will be absolute as well.

  PREFIX must be a string which is prepended to every entry name in the archive.

  If RECURSEP is true, then any entries in FILE-LIST naming directories (and not symlinks to directories) will be recursed into.

  If DEREFERENCE-HARDLINKS-P is true, then hardlinks will be followed and saved as regular file entries instead of hardlink entries.

  The following option controls what entries are created.

  FILTER defaults to (CONSTANTLY T). Must be a function designator that takes two arguments (the entry and the pathname were it will be extracted) and returns non-NIL if the entry should be extracted.