paxmirabilis/src/tar.1

.\"     $MirOS: src/bin/pax/tar.1,v 1.8 2006/07/21 17:34:59 tg Exp $
.\"     $OpenBSD: tar.1,v 1.47 2005/05/24 16:33:45 jaredy Exp $
.\"
.\" Copyright (c) 1996 SigmaSoft, Th. Lockert
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"     $OpenBSD: tar.1,v 1.47 2005/05/24 16:33:45 jaredy Exp $
.\"
.Dd July 21, 2006
.Dt TAR 1
.Os MirBSD
.\" for portability
.de Mx
.nr cF \\n(.f
.nr cZ \\n(.s
.ds aa \&\f\\n(cF\s\\n(cZ
.if \\n(aC==0 \{\
.       if \\n(.$==0 \&MirBSD\\*(aa
.\}
.if \\n(.$==1 \{\
.       if "\\$1"."  \&MirBSD\\$1\\*(aa
.       if "\\$1","  \&MirBSD\\$1\\*(aa
.\}
..
.Sh NAME
.Nm tar
.Nd tape archiver
.Sh SYNOPSIS
.Nm tar
.Sm off
.No { Cm crtux No } Op Cm 014578befHhLmOoPRSpqsvwXZz
.Sm on
.Bk -words
.Op Ar blocking-factor | archive | replstr
.Op Fl C Ar directory
.Op Fl I Ar file
.Op Ar file ...
.Ek
.Pp
.Nm tar
.No { Ns Fl crtux Ns }
.Op Fl 014578eHhLmOoPpqvwXZz
.Op Fl b Ar blocking-factor
.Op Fl C Ar directory
.Op Fl f Ar archive
.Op Fl I Ar file
.Op Fl M Ar value
.Op Fl s Ar replstr
.Op Ar file ...
.Sh DESCRIPTION
The
.Nm
command creates, adds files to, or extracts files from an
archive file in
.Dq tar
format.
A tar archive is often stored on a magnetic tape, but can be
stored equally well on a floppy, CD-ROM, or in a regular disk file.
.Pp
In the first (legacy) form, all option flags except for
.Fl C
and
.Fl I
must be contained within the first argument to
.Nm
and must not be prefixed by a hyphen
.Pq Sq - .
Option arguments, if any, are processed as subsequent arguments to
.Nm
and are processed in the order in which their corresponding option
flags have been presented on the command line.
.Pp
In the second and preferred form, option flags may be given in any order
and are immediately followed by their corresponding option argument
values.
.Pp
One of the following flags must be present:
.Bl -tag -width Ds
.It Fl c
Create new archive, or overwrite an existing archive,
adding the specified files to it.
.It Fl r
Append the named new files to existing archive.
Note that this will only work on media on which an end-of-file mark
can be overwritten.
.It Fl t
List contents of archive.
If any files are named on the
command line, only those files will be listed.
The
.Ar file
arguments may be specified as glob patterns (see
.Xr glob 3
for more information), in which case
.Nm
will list all archive members that match each pattern.
.It Fl u
Alias for
.Fl r .
.It Fl x
Extract files from archive.
If any files are named on the
command line, only those files will be extracted from the
archive.
The
.Ar file
arguments may be specified as glob patterns (see
.Xr glob 3
for more information), in which case
.Nm
will extract all archive members that match each pattern.
.Pp
If more than one copy of a file exists in the
archive, later copies will overwrite earlier copies during
extraction.
The file mode and modification time are preserved
if possible.
The file mode is subject to modification by the
.Xr umask 2 .
.El
.Pp
In addition to the flags mentioned above, any of the following
flags may be used:
.Bl -tag -width Ds
.It Fl b Ar blocking-factor
Set blocking factor to use for the archive.
.Nm
uses 512-byte blocks.
The default is 20, the maximum is 126.
Archives with a blocking factor larger than 63 violate the
.Tn POSIX
standard and will not be portable to all systems.
.It Fl C Ar directory
This is a positional argument which sets the working directory for the
following files.
When extracting, files will be extracted into
the specified directory; when creating, the specified files will be matched
from the directory.
.It Fl e
Stop after the first error.
.It Fl f Ar archive
Filename where the archive is stored.
Defaults to
.Pa /dev/rst0 .
.It Fl H
Follow symlinks given on the command line only.
.It Fl h
Follow symbolic links as if they were normal files
or directories.
In extract mode this means that a directory entry in the archive
will not overwrite an existing symbolic link, but rather what the
link ultimately points to.
.It Fl I Ar file
This is a positional argument which reads the names of files to
archive or extract from the given file, one per line.
.It Fl L
Synonym for the
.Fl h
option.
.It Fl M Ar value
Configure the archive normaliser.
.Ar value
is either a number or a string, optionally prefixed with
.Dq no-
to turn the flag off.
See
.Xr cpio 1
for a comprehensive list and compatibility notes.
.Pp
.Bl -tag -width xxxxxx -compact
.It Ar inodes
0x0001: Serialise inodes, zero device info.
.It Ar links
0x0002: Store content of hard links only once.
.It Ar mtime
0x0004: Zero out the file modification time.
.It Ar uidgid
0x0008: Set owner to 0:0 (root:wheel).
.El
.Pp
This option is only implemented for the cpio, sv4cpio,
sv4crc, and ustar file format writing routines.
For the ustar format, the
.Ar inodes
and
.Ar links
specifiers are ignored.
.It Fl m
Do not preserve modification time.
.It Fl O
If reading, extract files to standard output.
.br
If writing, write old-style (non-POSIX) archives.
.It Fl o
Don't write directory information that the older (V7) style
.Nm
is unable to decode.
This implies the
.Fl O
flag.
.It Fl P
Do not strip leading slashes
.Pq Sq /
from pathnames.
The default is to strip leading slashes.
.It Fl p
Preserve user and group ID as well as file mode regardless of
the current
.Xr umask 2 .
The setuid and setgid bits are only preserved if the user is
the superuser.
Only meaningful in conjunction with the
.Fl x
flag.
.It Fl q
Select the first archive member that matches each
.Ar file
operand.
No more than one archive member is matched for each
.Ar file .
When members of type directory are matched, the file hierarchy rooted at that
directory is also matched.
.It Fl R
Write SysVR4 CPIO files instead of tar or POSIX ustar files.
Serialise inode numbers, zero out device information.
The file content of hard links is stored only once.
.It Fl S
Write SysVR4 CPIO files with CRC instead of tar or POSIX ustar files.
Serialise inode numbers, zero out device information.
The file content of hard links is stored only once.
.It Fl s Ar replstr
Modify the archive member names according to the substitution expression
.Ar replstr ,
using the syntax of the
.Xr ed 1
utility regular expressions.
.Ar file
arguments may be given to restrict the list of archive members to those
specified.
.Pp
The format of these regular expressions is
.Pp
.Dl /old/new/[gp]
.Pp
As in
.Xr ed 1 ,
.Va old
is a basic regular expression (see
.Xr re_format 7 )
and
.Va new
can contain an ampersand
.Pq Ql & ,
.Ql \e Ns Em n
(where
.Em n
is a digit) back-references,
or subexpression matching.
The
.Va old
string may also contain newline characters.
Any non-null character can be used as a delimiter
.Po
.Ql /
is shown here
.Pc .
Multiple
.Fl s
expressions can be specified.
The expressions are applied in the order they are specified on the
command line, terminating with the first successful substitution.
.Pp
The optional trailing
.Cm g
continues to apply the substitution expression to the pathname substring,
which starts with the first character following the end of the last successful
substitution.
The first unsuccessful substitution stops the operation of the
.Cm g
option.
The optional trailing
.Cm p
will cause the final result of a successful substitution to be written to
standard error in the following format:
.Pp
.D1 Em original-pathname No >> Em new-pathname
.Pp
File or archive member names that substitute to the empty string
are not selected and will be skipped.
.It Fl v
Verbose operation mode.
.It Fl w
Interactively rename files.
This option causes
.Nm
to prompt the user for the filename to use when storing or
extracting files in an archive.
.It Fl X
Do not cross mount points in the file system.
.It Fl Z
Compress archive using
.Xr compress 1 .
.It Fl z
Compress archive using
.Xr gzip 1 .
.El
.Pp
The options
.Op Fl 014578
can be used to select one of the compiled-in backup devices,
.Pa /dev/rstN .
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It Ev TMPDIR
Path in which to store temporary files.
.It Ev TAPE
Default tape device to use instead of
.Pa /dev/rst0 .
.El
.Sh FILES
.Bl -tag -width "/dev/rst0"
.It Pa /dev/rst0
default archive name
.El
.Sh EXAMPLES
Create an archive on the default tape drive, containing the files named
.Pa bonvole
and
.Pa sekve :
.Pp
.Dl $ tar c bonvole sekve
.Pp
Output a
.Xr gzip 1
compressed archive containing the files
.Pa bonvole
and
.Pa sekve
to a file called
.Pa foriru.tar.gz :
.Pp
.Dl $ tar zcf foriru.tar.gz bonvole sekve
.Pp
Verbosely create an archive, called
.Pa backup.tar.gz ,
of all files matching the shell
.Xr glob 3
function
.Pa *.c :
.Pp
.Dl $ tar zcvf backup.tar.gz *.c
.Pp
Verbosely list, but do not extract, all files ending in
.Pa .jpeg
from a compressed archive named
.Pa backup.tar.gz .
Note that the glob pattern has been quoted to avoid expansion by the shell:
.Pp
.Dl $ tar tvzf backup.tar.gz '*.jpeg'
.Pp
For more detailed examples, see
.Xr pax 1 .
.Sh DIAGNOSTICS
.Nm
will exit with one of the following values:
.Bl -tag -width 2n -offset indent
.It 0
All files were processed successfully.
.It 1
An error occurred.
.El
.Pp
Whenever
.Nm
cannot create a file or a link when extracting an archive or cannot
find a file while writing an archive, or cannot preserve the user
ID, group ID, file mode, or access and modification times when the
.Fl p
option is specified, a diagnostic message is written to standard
error and a non-zero exit value will be returned, but processing
will continue.
In the case where
.Nm
cannot create a link to a file,
.Nm
will not create a second copy of the file.
.Pp
If the extraction of a file from an archive is prematurely terminated
by a signal or error,
.Nm
may have only partially extracted the file the user wanted.
Additionally, the file modes of extracted files and directories may
have incorrect file bits, and the modification and access times may
be wrong.
.Pp
If the creation of an archive is prematurely terminated by a signal
or error,
.Nm
may have only partially created the archive, which may violate the
specific archive format specification.
.Sh SEE ALSO
.Xr cpio 1 ,
.Xr pax 1
.Sh HISTORY
A
.Nm
command first appeared in
.At v7 .
.Sh AUTHORS
Keith Muller at the University of California, San Diego.
.Sh CAVEATS
The
.Fl L
flag is not portable to other versions of
.Nm
where it may have a different meaning.
The
.Fl R ,
.Fl S ,
and
.Fl M
options are extensions specific to
.Mx .
// Log In
// CVSweb
Project: FreeWRT
// Summary // Activity // Search // Tracker // Lists // News // SCM // Wiki
1	.\" $MirOS: src/bin/pax/tar.1,v 1.8 2006/07/21 17:34:59 tg Exp $
2	.\" $OpenBSD: tar.1,v 1.47 2005/05/24 16:33:45 jaredy Exp $
3	.\"
4	.\" Copyright (c) 1996 SigmaSoft, Th. Lockert
5	.\" All rights reserved.
6	.\"
7	.\" Redistribution and use in source and binary forms, with or without
8	.\" modification, are permitted provided that the following conditions
9	.\" are met:
10	.\" 1. Redistributions of source code must retain the above copyright
11	.\" notice, this list of conditions and the following disclaimer.
12	.\" 2. Redistributions in binary form must reproduce the above copyright
13	.\" notice, this list of conditions and the following disclaimer in the
14	.\" documentation and/or other materials provided with the distribution.
15	.\"
16	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19	.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26	.\"
27	.\" $OpenBSD: tar.1,v 1.47 2005/05/24 16:33:45 jaredy Exp $
28	.\"
29	.Dd July 21, 2006
30	.Dt TAR 1
31	.Os MirBSD
32	.\" for portability
33	.de Mx
34	.nr cF \\n(.f
35	.nr cZ \\n(.s
36	.ds aa \&\f\\n(cF\s\\n(cZ
37	.if \\n(aC==0 \{\
38	. if \\n(.$==0 \&MirBSD\\*(aa
39	.\}
40	.if \\n(.$==1 \{\
41	. if "\\$1"." \&MirBSD\\$1\\*(aa
42	. if "\\$1"," \&MirBSD\\$1\\*(aa
43	.\}
44	..
45	.Sh NAME
46	.Nm tar
47	.Nd tape archiver
48	.Sh SYNOPSIS
49	.Nm tar
50	.Sm off
51	.No { Cm crtux No } Op Cm 014578befHhLmOoPRSpqsvwXZz
52	.Sm on
53	.Bk -words
54	.Op Ar blocking-factor \| archive \| replstr
55	.Op Fl C Ar directory
56	.Op Fl I Ar file
57	.Op Ar file ...
58	.Ek
59	.Pp
60	.Nm tar
61	.No { Ns Fl crtux Ns }
62	.Op Fl 014578eHhLmOoPpqvwXZz
63	.Op Fl b Ar blocking-factor
64	.Op Fl C Ar directory
65	.Op Fl f Ar archive
66	.Op Fl I Ar file
67	.Op Fl M Ar value
68	.Op Fl s Ar replstr
69	.Op Ar file ...
70	.Sh DESCRIPTION
71	The
72	.Nm
73	command creates, adds files to, or extracts files from an
74	archive file in
75	.Dq tar
76	format.
77	A tar archive is often stored on a magnetic tape, but can be
78	stored equally well on a floppy, CD-ROM, or in a regular disk file.
79	.Pp
80	In the first (legacy) form, all option flags except for
81	.Fl C
82	and
83	.Fl I
84	must be contained within the first argument to
85	.Nm
86	and must not be prefixed by a hyphen
87	.Pq Sq - .
88	Option arguments, if any, are processed as subsequent arguments to
89	.Nm
90	and are processed in the order in which their corresponding option
91	flags have been presented on the command line.
92	.Pp
93	In the second and preferred form, option flags may be given in any order
94	and are immediately followed by their corresponding option argument
95	values.
96	.Pp
97	One of the following flags must be present:
98	.Bl -tag -width Ds
99	.It Fl c
100	Create new archive, or overwrite an existing archive,
101	adding the specified files to it.
102	.It Fl r
103	Append the named new files to existing archive.
104	Note that this will only work on media on which an end-of-file mark
105	can be overwritten.
106	.It Fl t
107	List contents of archive.
108	If any files are named on the
109	command line, only those files will be listed.
110	The
111	.Ar file
112	arguments may be specified as glob patterns (see
113	.Xr glob 3
114	for more information), in which case
115	.Nm
116	will list all archive members that match each pattern.
117	.It Fl u
118	Alias for
119	.Fl r .
120	.It Fl x
121	Extract files from archive.
122	If any files are named on the
123	command line, only those files will be extracted from the
124	archive.
125	The
126	.Ar file
127	arguments may be specified as glob patterns (see
128	.Xr glob 3
129	for more information), in which case
130	.Nm
131	will extract all archive members that match each pattern.
132	.Pp
133	If more than one copy of a file exists in the
134	archive, later copies will overwrite earlier copies during
135	extraction.
136	The file mode and modification time are preserved
137	if possible.
138	The file mode is subject to modification by the
139	.Xr umask 2 .
140	.El
141	.Pp
142	In addition to the flags mentioned above, any of the following
143	flags may be used:
144	.Bl -tag -width Ds
145	.It Fl b Ar blocking-factor
146	Set blocking factor to use for the archive.
147	.Nm
148	uses 512-byte blocks.
149	The default is 20, the maximum is 126.
150	Archives with a blocking factor larger than 63 violate the
151	.Tn POSIX
152	standard and will not be portable to all systems.
153	.It Fl C Ar directory
154	This is a positional argument which sets the working directory for the
155	following files.
156	When extracting, files will be extracted into
157	the specified directory; when creating, the specified files will be matched
158	from the directory.
159	.It Fl e
160	Stop after the first error.
161	.It Fl f Ar archive
162	Filename where the archive is stored.
163	Defaults to
164	.Pa /dev/rst0 .
165	.It Fl H
166	Follow symlinks given on the command line only.
167	.It Fl h
168	Follow symbolic links as if they were normal files
169	or directories.
170	In extract mode this means that a directory entry in the archive
171	will not overwrite an existing symbolic link, but rather what the
172	link ultimately points to.
173	.It Fl I Ar file
174	This is a positional argument which reads the names of files to
175	archive or extract from the given file, one per line.
176	.It Fl L
177	Synonym for the
178	.Fl h
179	option.
180	.It Fl M Ar value
181	Configure the archive normaliser.
182	.Ar value
183	is either a number or a string, optionally prefixed with
184	.Dq no-
185	to turn the flag off.
186	See
187	.Xr cpio 1
188	for a comprehensive list and compatibility notes.
189	.Pp
190	.Bl -tag -width xxxxxx -compact
191	.It Ar inodes
192	0x0001: Serialise inodes, zero device info.
193	.It Ar links
194	0x0002: Store content of hard links only once.
195	.It Ar mtime
196	0x0004: Zero out the file modification time.
197	.It Ar uidgid
198	0x0008: Set owner to 0:0 (root:wheel).
199	.El
200	.Pp
201	This option is only implemented for the cpio, sv4cpio,
202	sv4crc, and ustar file format writing routines.
203	For the ustar format, the
204	.Ar inodes
205	and
206	.Ar links
207	specifiers are ignored.
208	.It Fl m
209	Do not preserve modification time.
210	.It Fl O
211	If reading, extract files to standard output.
212	.br
213	If writing, write old-style (non-POSIX) archives.
214	.It Fl o
215	Don't write directory information that the older (V7) style
216	.Nm
217	is unable to decode.
218	This implies the
219	.Fl O
220	flag.
221	.It Fl P
222	Do not strip leading slashes
223	.Pq Sq /
224	from pathnames.
225	The default is to strip leading slashes.
226	.It Fl p
227	Preserve user and group ID as well as file mode regardless of
228	the current
229	.Xr umask 2 .
230	The setuid and setgid bits are only preserved if the user is
231	the superuser.
232	Only meaningful in conjunction with the
233	.Fl x
234	flag.
235	.It Fl q
236	Select the first archive member that matches each
237	.Ar file
238	operand.
239	No more than one archive member is matched for each
240	.Ar file .
241	When members of type directory are matched, the file hierarchy rooted at that
242	directory is also matched.
243	.It Fl R
244	Write SysVR4 CPIO files instead of tar or POSIX ustar files.
245	Serialise inode numbers, zero out device information.
246	The file content of hard links is stored only once.
247	.It Fl S
248	Write SysVR4 CPIO files with CRC instead of tar or POSIX ustar files.
249	Serialise inode numbers, zero out device information.
250	The file content of hard links is stored only once.
251	.It Fl s Ar replstr
252	Modify the archive member names according to the substitution expression
253	.Ar replstr ,
254	using the syntax of the
255	.Xr ed 1
256	utility regular expressions.
257	.Ar file
258	arguments may be given to restrict the list of archive members to those
259	specified.
260	.Pp
261	The format of these regular expressions is
262	.Pp
263	.Dl /old/new/[gp]
264	.Pp
265	As in
266	.Xr ed 1 ,
267	.Va old
268	is a basic regular expression (see
269	.Xr re_format 7 )
270	and
271	.Va new
272	can contain an ampersand
273	.Pq Ql & ,
274	.Ql \e Ns Em n
275	(where
276	.Em n
277	is a digit) back-references,
278	or subexpression matching.
279	The
280	.Va old
281	string may also contain newline characters.
282	Any non-null character can be used as a delimiter
283	.Po
284	.Ql /
285	is shown here
286	.Pc .
287	Multiple
288	.Fl s
289	expressions can be specified.
290	The expressions are applied in the order they are specified on the
291	command line, terminating with the first successful substitution.
292	.Pp
293	The optional trailing
294	.Cm g
295	continues to apply the substitution expression to the pathname substring,
296	which starts with the first character following the end of the last successful
297	substitution.
298	The first unsuccessful substitution stops the operation of the
299	.Cm g
300	option.
301	The optional trailing
302	.Cm p
303	will cause the final result of a successful substitution to be written to
304	standard error in the following format:
305	.Pp
306	.D1 Em original-pathname No >> Em new-pathname
307	.Pp
308	File or archive member names that substitute to the empty string
309	are not selected and will be skipped.
310	.It Fl v
311	Verbose operation mode.
312	.It Fl w
313	Interactively rename files.
314	This option causes
315	.Nm
316	to prompt the user for the filename to use when storing or
317	extracting files in an archive.
318	.It Fl X
319	Do not cross mount points in the file system.
320	.It Fl Z
321	Compress archive using
322	.Xr compress 1 .
323	.It Fl z
324	Compress archive using
325	.Xr gzip 1 .
326	.El
327	.Pp
328	The options
329	.Op Fl 014578
330	can be used to select one of the compiled-in backup devices,
331	.Pa /dev/rstN .
332	.Sh ENVIRONMENT
333	.Bl -tag -width Fl
334	.It Ev TMPDIR
335	Path in which to store temporary files.
336	.It Ev TAPE
337	Default tape device to use instead of
338	.Pa /dev/rst0 .
339	.El
340	.Sh FILES
341	.Bl -tag -width "/dev/rst0"
342	.It Pa /dev/rst0
343	default archive name
344	.El
345	.Sh EXAMPLES
346	Create an archive on the default tape drive, containing the files named
347	.Pa bonvole
348	and
349	.Pa sekve :
350	.Pp
351	.Dl $ tar c bonvole sekve
352	.Pp
353	Output a
354	.Xr gzip 1
355	compressed archive containing the files
356	.Pa bonvole
357	and
358	.Pa sekve
359	to a file called
360	.Pa foriru.tar.gz :
361	.Pp
362	.Dl $ tar zcf foriru.tar.gz bonvole sekve
363	.Pp
364	Verbosely create an archive, called
365	.Pa backup.tar.gz ,
366	of all files matching the shell
367	.Xr glob 3
368	function
369	.Pa *.c :
370	.Pp
371	.Dl $ tar zcvf backup.tar.gz *.c
372	.Pp
373	Verbosely list, but do not extract, all files ending in
374	.Pa .jpeg
375	from a compressed archive named
376	.Pa backup.tar.gz .
377	Note that the glob pattern has been quoted to avoid expansion by the shell:
378	.Pp
379	.Dl $ tar tvzf backup.tar.gz '*.jpeg'
380	.Pp
381	For more detailed examples, see
382	.Xr pax 1 .
383	.Sh DIAGNOSTICS
384	.Nm
385	will exit with one of the following values:
386	.Bl -tag -width 2n -offset indent
387	.It 0
388	All files were processed successfully.
389	.It 1
390	An error occurred.
391	.El
392	.Pp
393	Whenever
394	.Nm
395	cannot create a file or a link when extracting an archive or cannot
396	find a file while writing an archive, or cannot preserve the user
397	ID, group ID, file mode, or access and modification times when the
398	.Fl p
399	option is specified, a diagnostic message is written to standard
400	error and a non-zero exit value will be returned, but processing
401	will continue.
402	In the case where
403	.Nm
404	cannot create a link to a file,
405	.Nm
406	will not create a second copy of the file.
407	.Pp
408	If the extraction of a file from an archive is prematurely terminated
409	by a signal or error,
410	.Nm
411	may have only partially extracted the file the user wanted.
412	Additionally, the file modes of extracted files and directories may
413	have incorrect file bits, and the modification and access times may
414	be wrong.
415	.Pp
416	If the creation of an archive is prematurely terminated by a signal
417	or error,
418	.Nm
419	may have only partially created the archive, which may violate the
420	specific archive format specification.
421	.Sh SEE ALSO
422	.Xr cpio 1 ,
423	.Xr pax 1
424	.Sh HISTORY
425	A
426	.Nm
427	command first appeared in
428	.At v7 .
429	.Sh AUTHORS
430	Keith Muller at the University of California, San Diego.
431	.Sh CAVEATS
432	The
433	.Fl L
434	flag is not portable to other versions of
435	.Nm
436	where it may have a different meaning.
437	The
438	.Fl R ,
439	.Fl S ,
440	and
441	.Fl M
442	options are extensions specific to
443	.Mx .