1 .TH TAR 1
2 .SH NAME
3 tar \- archiver
4 .SH SYNOPSIS
5 .B tar
6 .I key
7 [
8 .I file ...
9 ]
10 .SH DESCRIPTION
11 .PP
12 .I Tar
13 saves and restores file trees.
14 It is most often used to transport a tree of files from one
15 system to another.
16 The
17 .I key
18 is a string that contains
19 at most one function letter plus optional modifiers.
20 Other arguments to the command are names of
21 files or directories to be dumped or restored.
22 A directory name implies all the contained
23 files and subdirectories (recursively).
24 .PP
25 The function is one of the following letters:
26 .TP
27 .B  c
28 Create a new archive with the given files as contents.
29 .TP
30 .B  x
31 Extract the named files from the archive.
32 If a file is a directory, the directory is extracted recursively.
33 Modes are restored if possible.
34 If no file argument is given, extract the entire archive.
35 If the archive contains multiple entries for a file,
36 the latest one wins.
37 .TP
38 .B  t
39 List all occurrences of each 
40 .I file
41 in the archive, or of all files if there are no
42 .I file
43 arguments.
44 .TP
45 .B  r
46 The named files
47 are appended to the archive.
48 .PP
49 The modifiers are:
50 .TP
51 .B  v
52 (verbose)
53 Print the name of each file treated
54 preceded by the function letter.
55 With 
56 .BR t ,
57 give more details about the
58 archive entries.
59 .TP
60 .B f
61 Use the next argument as the name of the archive instead of
62 the default standard input (for keys
63 .B x
64 and
65 .BR t )
66 or standard output (for keys
67 .B c
68 and
69 .BR r ).
70 .TP
71 .B u
72 Use the next (numeric) argument as the user id for files in
73 the output archive.  This is only useful when moving files to
74 a non-Plan 9 system.
75 .TP
76 .B g
77 Use the next (numeric) argument as the group id for files in
78 the output archive.
79 .TP
80 .B p
81 Create archive in POSIX ustar format,
82 which raises the maximum pathname length from 100 to 256 bytes.
83 Ustar archives are recognised automatically by
84 .I tar
85 when reading archives.
86 .TP
87 .B R
88 When extracting, ignore leading slash on file names,
89 i.e., extract all files relative to the current directory.
90 .TP
91 .B T
92 Modifies the behavior of
93 .B x
94 to set the mode and modified time
95 of each file to that specified in the archive.
96 .SH EXAMPLES
97 .I Tar
98 can be used to copy hierarchies thus:
99 .IP
100 .EX
101 @{cd fromdir && tar cp .} | @{cd todir && tar xT}
102 .EE
103 .SH SOURCE
104 .B /usr/local/plan9/src/cmd/tar.c
105 .SH SEE ALSO
106 .IR ar (1),
107 .IR bundle (1),
108 .IR tapefs (1)
109 .SH BUGS
110 There is no way to ask for any but the last
111 occurrence of a file.
112 .br
113 File path names are limited to
114 100 characters
115 (256 when using ustar format).
116 .br
117 The tar format allows specification of links and symbolic links,
118 concepts foreign to Plan 9: they are ignored.