On this page:
untar
handle-tar-entry

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

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.