6 tar File Creation

▼ |  | 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:

tar
tar->output
tar-gzip
tar-entry

Racket
top contents ← prev up next →

## 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 9.2.0.3: 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 9.2.0.3: 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:

- 'permissions — an integer representing read, write, and execute permissions in the form accepted by file-or-directory-permissions.

- 'modify-seconds — an integer representing a modification time, which is consistent with file-or-directory-modify-seconds.

- 'owner — an exact integer presenting a file owner ID.

- 'owner-bytes — a byte string representing a file owner name.

- 'group — an exact integer presenting a file group ID.

- 'group-bytes — a byte string representing a file group name.

Added in version 8.1.0.5 of package base.

top contents ← prev up next →