▼ |  | File: Racket File and Format Libraries

1 | Convertible: Data-Conversion Protocol
2 | gzip Compression and File Creation
3 | gzip Decompression
4 | zip File Creation
5 | zip File Extraction
6 | tar File Creation
7 | tar File Extraction
8 | tar+gzip File Extraction
9 | MD5 Message Digest
10 | SHA1 Message Digest
11 | GIF File Writing
12 | ICO File Reading and Writing
13 | Windows Registry
14 | Caching
15 | Globbing
| Bibliography
| Index

On this page:

untar
handle-tar-entry

top ← prev up next →

### 7`` tar File Extraction

(require file/untar) | package: base

The file/untar library provides a function to extract items from a TAR/USTAR archive using GNU and/or pax extensions to support long pathnames.

> > procedure

> > (untar |  | in |  |  |  |
> > | [ | #:dest dest-path |  |  |  |
> > |  | #:strip-count strip-count |  |  |  |
> > |  | #:permissive? permissive? |  |  |  |
> > |  | #:filter filter-proc |  |  |  |
> > |  | #:handle-entry handle-entry]) |  | → |  | void?

> in : (or/c path-string? input-port?)
> dest-path : (or/c path-string? #f) = #f
> strip-count : exact-nonnegative-integer? = 0
> permissive? : any/c = #f

> filter-proc

> :

> (path? (or/c path? #f)
> symbol? exact-integer? (or/c path? #f)
> exact-nonnegative-integer?
> exact-nonnegative-integer?
> . -> . any/c)

> |  |  | = |  | (lambda args #t)

> handle-entry

> :

> ((or/c 'file 'directory 'link)
> (and path? relative-path?)
> (or/c input-port? #f path?)
> exact-nonnegative-integer?
> (hash/c symbol? any/c)
> . -> . (listof (-> any)))

> |  |  | = |  | handle-tar-entry

Extracts TAR/USTAR content from in, recognizing POSIX.1-2001/pax and GNU extensions for long paths and long symbolic-link targets.

If dest-path is not #f, every path in the archive is prefixed to determine the destination path of the extracted item.

If strip-count is positive, then strip-count path elements are removed from the item path from the archive (before prefixing the path with dest-path); if the item’s path contains strip-count elements, then it is not extracted.

Unless permissive? is true, then archive items with paths containing an up-directory indicator are disallowed, and a link item whose target is an absolute path or contains an up-directory indicator is also disallowed. Absolute paths are always disallowed. A disallowed path triggers an exception.

For each item in the archive, filter-proc is applied to

- the item’s path as it appears in the archive;

- a destination path that is based on the path in the archive, strip-count, and dest-path–which can be #f if the item’s path does not have strip-count or more elements;

- a symbol representing the item’s type—'file, 'dir, 'link, 'hard-link, 'character-special, 'block-special, 'fifo, 'contiguous-file, 'extended-header, 'extended-header-for-next, or 'unknown—where only 'file, 'dir, or 'link can be unpacked by untar;

- an exact integer representing the item’s size;

- a target path for a 'link type or #f for any other type;

- an integer representing the item’s modification date; and

- an integer representing the item’s permissions

If the result of filter-proc is #f, then the item is not unpacked.

The handle-entry function is called to unpack one entry, and the default handle-tar-entry function for handle-entry creates a directory, file, or link on the filesystem. The handle-entry function must accept five arguments:

- kind — one of 'file, 'directory, or 'link.

- path — the relative path recorded in the TAR file.

- content — an input port that provides the content for a 'file entry, where exactly size bytes must be read from the port before handle-entry returns. For a 'directory entry, content is #f. For a 'link entry, content is a path for the link target.

- size — the number of bytes for a 'file entry, and 0 for other entries.

- attribs — an immutable hash table mapping symbols to attribute values. The available keys may change, but the currently included keys are the same ones as recognized in tar-entry.

The result of handle-entry is a list of thunks that are called in order after the TAR input is fully unpacked. A result thunk from handle-entry is useful, for example, to set a directory’s modification time after all files have been written to it.

Changed in version 6.3 of package base: Added the #:permissive? argument.
Changed in version 6.7.0.4: Support long paths and long symbolic-link targets using POSIX.1-2001/pax and GNU extensions.
Changed in version 8.1.0.5: Added the #:handle-entry argument.

> > procedure

> > (handle-tar-entry |  | kind |  |  |  |
> > |  | path |  |  |  |
> > |  | content |  |  |  |
> > |  | size |  |  |  |
> > |  | attribs) |  | → |  | (listof (-> any))

> kind : (or/c 'file 'directory 'link)
> path : (and path? relative-path?)
> content : (or/c input-port? #f path?)
> size : exact-nonnegative-integer?
> attribs : (hash/c symbol? any/c)

As the default entry handler for untar, handle-tar-entry creates directories and files and returns a list of thunks that complete unpacking by setting directory permissions and modification times.

Added in version 8.1.0.5 of package base.

top ← prev up next →