On this page:
tar
tar->output
tar-gzip
tar-entry

6 tar File Creation

 (require file/tar) package: base
The file/tar library provides utilities to create archive files in USTAR format, like the archive that the Unix utility pax generates. Long paths are supported using either the POSIX.1-2001/pax or GNU format for long paths. The resulting archives contain only directories, files, and symbolic links, and owner information is not preserved; the owner that is stored in the archive is always “root.”
Symbolic links (on Unix and Mac OS) are not followed by default.

procedure

(tar tar-file 
  path-or-entry ... 
  [#:follow-links? follow-links? 
  #:exists-ok? exists-ok? 
  #:format format 
  #:path-prefix path-prefix 
  #:path-filter path-filter 
  #:timestamp timestamp 
  #:get-timestamp get-timestamp]) 
  exact-nonnegative-integer?
  tar-file : path-string?
  path-or-entry : (or/c path-string? tar-entry?)
  follow-links? : any/c = #f
  exists-ok? : any/c = #f
  format : (or/c 'pax 'gnu 'ustar) = 'pax
  path-prefix : (or/c #f path-string?) = #f
  path-filter : (or/c #f (path? . -> . any/c)) = #f
  timestamp : (or/c #f exact-integer?) = #f
  get-timestamp : (path? . -> . exact-integer?)
   = 
(if timestamp
    (lambda (p) timestamp)
    file-or-directory-modify-seconds)
Creates tar-file, which holds the complete content of all path-or-entrys. Each path-or-entry is either a path that refers to a file, directory, or link on the filesystem, or it is a tar-entry that describes such an entity without requiring it to exist on the filesystem.

The given paths among path-or-entrys are all expected to be relative paths for existing directories and files (i.e., relative to the current directory for a path-or-entry is a path). If a nested path is provided in a path-or-entry, its ancestor directories are also added to the resulting tar file, up to the current directory (using pathlist-closure). If follow-links? is false, then symbolic links are included in the resulting tar file as links.

If exists-ok? is #f, then an exception is raised if tar-file exists already. If exists-ok? is true, then tar-file is truncated or replaced if it exists already.

The format argument determines the handling of long paths and long symbolic-link targets. If format is 'pax, then POSIX.1-2001/pax extensions are used. If format is 'gnu, then GNU extensions are used. If format is 'ustar, then tar raises an error for too-long paths or symbolic-link targets.

If path-prefix is not #f, then it is prefixed to each path in the archive.

The get-timestamp function is used to obtain the modification date to record in the archive for each file or directory.

Changed in version 6.0.0.3 of package base: Added the #:get-timestamp argument.
Changed in version 6.1.1.1: Added the #:exists-ok? argument.
Changed in version 6.3.0.3: Added the #:follow-links? argument.
Changed in version 6.3.0.11: Added the #:path-filter argument.
Changed in version 6.7.0.4: Added the #:format argument and effectively changed its default from 'ustar to 'pax.
Changed in version 7.3.0.3: Added the #:timestamp argument.
Changed in version 8.1.0.5: Added support for tar-entry arguments.

procedure

(tar->output paths-and-entries 
  [out 
  #:follow-links? follow-links? 
  #:format format 
  #:path-prefix path-prefix 
  #:path-filter path-filter 
  #:timestamp timestamp 
  #:get-timestamp get-timestamp]) 
  exact-nonnegative-integer?
  paths-and-entries : (listof (or/c path? tar-entry?))
  out : output-port? = (current-output-port)
  follow-links? : any/c = #f
  format : (or/c 'pax 'gnu 'ustar) = 'pax
  path-prefix : (or/c #f path-string?) = #f
  path-filter : (or/c #f (path? . -> . any/c)) = #f
  timestamp : (or/c #f exact-integer?) = #f
  get-timestamp : (path? . -> . exact-integer?)
   = 
(if timestamp
    (lambda (p) timestamp)
    file-or-directory-modify-seconds)
Like tar, but packages each element of the given paths-and-entries in a tar format archive that is written directly to the out. The specified paths-and-entries are included as-is (except for adding path-prefix, if any); if a directory is specified, its content is not automatically added, and nested directories are added without parent directories.

Changed in version 6.0.0.3 of package base: Added the #:get-timestamp argument.
Changed in version 6.3.0.3: Added the #:follow-links? argument.
Changed in version 6.3.0.11: Added the #:path-filter argument.
Changed in version 6.7.0.4: Added the #:format argument and effectively changed its default from 'ustar to 'pax.
Changed in version 7.3.0.3: Added the #:timestamp argument.
Changed in version 8.1.0.5: Added support for tar-entry arguments.

procedure

(tar-gzip tar-file    
  paths-and-entries ...    
  [#:follow-links? follow-links?    
  #:exists-ok? exists-ok?    
  #:format format    
  #:path-prefix path-prefix    
  #:timestamp timestamp    
  #:get-timestamp get-timestamp])  void?
  tar-file : path-string?
  paths-and-entries : (and/c path-string? tar-entry?)
  follow-links? : any/c = #f
  exists-ok? : any/c = #f
  format : (or/c 'pax 'gnu 'ustar) = 'pax
  path-prefix : (or/c #f path-string?) = #f
  timestamp : (or/c #f exact-integer?) = #f
  get-timestamp : (path? . -> . exact-integer?)
   = 
(if timestamp
    (lambda (p) timestamp)
    file-or-directory-modify-seconds)
Like tar, but compresses the resulting file with gzip.

Changed in version 6.0.0.3 of package base: Added the #:get-timestamp argument.
Changed in version 6.1.1.1: Added the #:exists-ok? argument.
Changed in version 6.3.0.3: Added the #:follow-links? argument.
Changed in version 6.7.0.4: Added the #:format argument and effectively changed its default from 'ustar to 'pax.
Changed in version 7.3.0.3: Added the #:timestamp argument.
Changed in version 8.1.0.5: Added support for tar-entry arguments.

struct

(struct tar-entry (kind path content size attribs)
    #:extra-constructor-name make-tar-entry)
  kind : (or/c 'file 'directory 'link)
  path : (and/c path-string? relative-path?)
  content : (or/c input-port? (-> input-port?) #f path-string?)
  size : exact-nonnegative-integer?
  attribs : (hash/c symbol? any/c)
Represents a file, directory, or link to be included in a USTAR file or stream.

If kind is 'file, then content must be an input port or a thunk that produces an input port, and it must provide exactly size bytes. If kind is 'directory, then content and size are expected to be #f and 0. If kind is 'link, then content must be a path, and size is expected to be 0.

The attribs field contains a hash table providing additional properties of the entry. The following keys are currently used when writing a USTAR file or stream:

Added in version 8.1.0.5 of package base.