| blob | ff66ccbefa57fcfbc9322e73a71d6d21f730ae91 |
1 .\"-
2 .\" Copyright (c) 1996 SigmaSoft, Th. Lockert
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\" must display the following acknowledgement:
15 .\" This product includes software developed by SigmaSoft, Th. Lockert.
16 .\" 4. The name of the author may not be used to endorse or promote products
17 .\" derived from this software without specific prior written permission
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .\" $OpenBSD: tar.1,v 1.33 2001/05/01 17:58:01 aaron Exp $
31 .\" $FreeBSD$
32 .\"
33 .Dd February 7, 2001
34 .Dt TAR 1
35 .Os
36 .Sh NAME
37 .Nm tar
38 .Nd tape archiver
39 .Sh SYNOPSIS
40 .Nm
41 .Sm off
42 .Op Fl
43 .Brq Cm crtux
44 .Op Cm befhjmopqsvwyzHLOPXZ014578
45 .Sm on
46 .Op Ar blocksize
47 .Op Ar archive
48 .Op Ar replstr
49 .\" XXX how to do this right?
50 .Op Fl C Ar directory
51 .Op Fl I Ar file
52 .Op Ar
53 .Sh DESCRIPTION
54 The
55 .Nm
56 command creates, adds files to, or extracts files from an
57 archive file in
58 .Nm
59 format.
60 A
61 .Nm
62 archive is often stored on a magnetic tape, but can be
63 stored equally well on a floppy, CD-ROM, or in a regular disk file.
64 .Pp
65 One of the following flags must be present:
66 .Bl -tag -width indent
67 .It Fl c
68 Create new archive, or overwrite an existing archive,
69 adding the specified files to it.
70 .It Fl r
71 Append the named new files to existing archive.
72 Note that this will only work on media on which an end-of-file mark
73 can be overwritten.
74 .It Fl t
75 List contents of archive.
76 If any files are named on the
77 command line, only those files will be listed.
78 .It Fl u
79 Alias for
80 .Fl r .
81 .It Fl x
82 Extract files from archive.
83 If any files are named on the
84 command line, only those files will be extracted from the
85 archive.
86 If more than one copy of a file exists in the
87 archive, later copies will overwrite earlier copies during
88 extraction.
89 The file mode and modification time are preserved
90 if possible.
91 The file mode is subject to modification by the
92 .Xr umask 2 .
93 .El
94 .Pp
95 In addition to the flags mentioned above, any of the following
96 flags may be used:
97 .Bl -tag -width indent
98 .It Fl b Ar "blocking factor"
99 Set blocking factor to use for the archive, with 512 byte blocks.
100 The default is 20, the maximum is 126.
101 Archives with a blocking factor larger 63 violate the
102 .Tn POSIX
103 standard and will not be portable to all systems.
104 .It Fl e
105 Stop after first error.
106 .It Fl f Ar archive
107 Filename where the archive is stored.
108 Defaults to
109 .Pa /dev/sa0 .
110 .It Fl h
111 Follow symbolic links as if they were normal files
112 or directories.
113 .It Fl j
114 Compress archives using
115 .Xr bzip2 1 .
116 .It Fl m
117 Do not preserve modification time.
118 .It Fl O
119 Write old-style
120 .Pq non- Ns Tn POSIX
121 archives.
122 .It Fl o
123 Do not write directory information that the older (V7) style
124 .Nm
125 is unable to decode.
126 This implies the
127 .Fl O
128 flag.
129 .It Fl p
130 Preserve user and group ID as well as file mode regardless of
131 the current
132 .Xr umask 2 .
133 The setuid and setgid bits are only preserved if the user is
134 the superuser.
135 Only meaningful in conjunction with the
136 .Fl x
137 flag.
138 .It Fl q
139 Select the first archive member that matches each
140 .Ar pattern
141 operand.
142 No more than one archive member is matched for each
143 .Ar pattern .
144 When members of type directory are matched, the file hierarchy rooted at that
145 directory is also matched.
146 .It Fl s Ar replstr
147 Modify the file or archive member names specified by the
148 .Ar pattern
149 or
150 .Ar file
151 operands according to the substitution expression
152 .Ar replstr ,
153 using the syntax of the
154 .Xr ed 1
155 utility regular expressions.
156 The format of these regular expressions are:
157 .Dl /old/new/[gp]
158 As in
159 .Xr ed 1 ,
160 .Cm old
161 is a basic regular expression and
162 .Cm new
163 can contain an ampersand
164 .Pq Ql & ,
165 .Li \e Ns Ar n
166 (where
167 .Ar n
168 is a digit) back-references,
169 or subexpression matching.
170 The
171 .Cm old
172 string may also contain newline characters.
173 Any non-null character can be used as a delimiter
174 .Ql ( /
175 is shown here).
176 Multiple
177 .Fl s
178 expressions can be specified.
179 The expressions are applied in the order they are specified on the
180 command line, terminating with the first successful substitution.
181 The optional trailing
182 .Cm g
183 continues to apply the substitution expression to the pathname substring
184 which starts with the first character following the end of the last successful
185 substitution.
186 The first unsuccessful substitution stops the operation of the
187 .Cm g
188 option.
189 The optional trailing
190 .Cm p
191 will cause the final result of a successful substitution to be written to
192 standard error
193 in the following format:
194 .Pp
195 .Dl <original pathname> >> <new pathname>
196 .Pp
197 File or archive member names that substitute to the empty string
198 are not selected and will be skipped.
199 .It Fl v
200 Verbose operation mode.
201 .It Fl w
202 Interactively rename files.
203 This option causes
204 .Nm
205 to prompt the user for the filename to use when storing or
206 extracting files in an archive.
207 .It Fl y
208 Compress archives using
209 .Xr bzip2 1 .
210 .It Fl z
211 Compress archive using
212 .Xr gzip 1 .
213 .It Fl C Ar directory
214 This is a positional argument which sets the working directory for the
215 following files.
216 When extracting, files will be extracted into
217 the specified directory; when creating, the specified files will be matched
218 from the directory.
219 .It Fl H
220 Follow symlinks given on command line only.
221 .It Fl L
222 Follow all symlinks.
223 .It Fl P
224 Do not strip leading slashes
225 .Pq Ql /
226 from pathnames.
227 The default is to strip leading slashes.
228 .It Fl I Ar file
229 This is a positional argument which reads the names of files to
230 archive or extract from the given file, one per line.
231 .It Fl X
232 Do not cross mount points in the file system.
233 .It Fl Z
234 Compress archive using
235 .Xr compress 1 .
236 .El
237 .Pp
238 The options
239 .Op Fl 014578
240 can be used to select one of the compiled-in backup devices,
241 .Pa /dev/rst Ns Ar N .
242 .Sh ENVIRONMENT
243 .Bl -tag -width TMPDIR
244 .It Ev TMPDIR
245 Path in which to store temporary files.
246 .It Ev TAPE
247 Default tape device to use instead of
248 .Pa /dev/sa0 .
249 .El
250 .Sh FILES
251 .Bl -tag -width "/dev/sa0"
252 .It Pa /dev/sa0
253 default archive name
254 .El
255 .Sh EXIT STATUS
256 The
257 .Nm
258 utility will exit with one of the following values:
259 .Bl -tag -width 2n
260 .It 0
261 All files were processed successfully.
262 .It 1
263 An error occurred.
264 .El
265 .Pp
266 Whenever
267 .Nm
268 cannot create a file or a link when extracting an archive or cannot
269 find a file while writing an archive, or cannot preserve the user
270 ID, group ID, file mode, or access and modification times when the
271 .Fl p
272 option is specified, a diagnostic message is written to standard
273 error and a non-zero exit value will be returned, but processing
274 will continue.
275 In the case where
276 .Nm
277 cannot create a link to a file,
278 .Nm
279 will not create a second copy of the file.
280 .Pp
281 If the extraction of a file from an archive is prematurely terminated
282 by a signal or error,
283 .Nm
284 may have only partially extracted the file the user wanted.
285 Additionally, the file modes of extracted files and directories may
286 have incorrect file bits, and the modification and access times may
287 be wrong.
288 .Pp
289 If the creation of an archive is prematurely terminated by a signal
290 or error,
291 .Nm
292 may have only partially created the archive which may violate the
293 specific archive format specification.
294 .Sh COMPATIBILITY
295 The
296 .Fl L
297 flag is not portable to other versions of
298 .Nm
299 where it may have a different meaning.
300 .Sh SEE ALSO
301 .Xr cpio 1 ,
302 .Xr pax 1
303 .Sh HISTORY
304 A
305 .Nm
306 command first appeared in
307 .At v7 .
308 .Sh AUTHORS
309 .An Keith Muller
310 at the University of California, San Diego.