1 .\" $OpenBSD: tar.1,v 1.51 2008/12/27 13:35:34 sobrado Exp $
3 .\" Copyright (c) 1996 SigmaSoft, Th. Lockert
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 .\" $OpenBSD: tar.1,v 1.51 2008/12/27 13:35:34 sobrado Exp $
28 .Dd $Mdocdate: December 27 2008 $
37 .No { Cm crtux No } Op Cm 014578befHhjLmOoPpqsvwXZz
40 .Op Ar blocking-factor | archive | replstr
46 .No { Ns Fl crtux Ns }
48 .Op Fl 014578eHhjLmOoPpqvwXZz
49 .Op Fl b Ar blocking-factor
59 command creates, adds files to, or extracts files from an
63 A tar archive is often stored on a magnetic tape, but can be
64 stored equally well on a floppy, CD-ROM, or in a regular disk file.
66 In the first (legacy) form, all option flags except for
70 must be contained within the first argument to
72 and must not be prefixed by a hyphen
74 Option arguments, if any, are processed as subsequent arguments to
76 and are processed in the order in which their corresponding option
77 flags have been presented on the command line.
79 In the second and preferred form, option flags may be given in any order
80 and are immediately followed by their corresponding option argument
83 One of the following flags must be present:
86 Create new archive, or overwrite an existing archive,
87 adding the specified files to it.
89 Append the named new files to existing archive.
90 Note that this will only work on media on which an end-of-file mark
93 List contents of archive.
94 If any files are named on the
95 command line, only those files will be listed.
98 arguments may be specified as glob patterns (see
100 for more information), in which case
102 will list all archive members that match each pattern.
107 Extract files from archive.
108 If any files are named on the
109 command line, only those files will be extracted from the
113 arguments may be specified as glob patterns (see
115 for more information), in which case
117 will extract all archive members that match each pattern.
119 If more than one copy of a file exists in the
120 archive, later copies will overwrite earlier copies during
122 The file mode and modification time are preserved
124 The file mode is subject to modification by the
128 In addition to the flags mentioned above, any of the following
131 .It Fl b Ar blocking-factor
132 Set blocking factor to use for the archive.
134 uses 512-byte blocks.
135 The default is 20, the maximum is 126.
136 Archives with a blocking factor larger than 63 violate the
138 standard and will not be portable to all systems.
139 .It Fl C Ar directory
140 This is a positional argument which sets the working directory for the
142 When extracting, files will be extracted into
143 the specified directory; when creating, the specified files will be matched
146 Stop after the first error.
148 Filename where the archive is stored.
152 Follow symlinks given on the command line only.
154 Follow symbolic links as if they were normal files
156 In extract mode this means that a directory entry in the archive
157 will not overwrite an existing symbolic link, but rather what the
158 link ultimately points to.
160 This is a positional argument which reads the names of files to
161 archive or extract from the given file, one per line.
163 Compress archive using bzip2.
164 The bzip2 utility must be installed separately.
170 Do not preserve modification time.
172 Write old-style (non-POSIX) archives.
174 Don't write directory information that the older (V7) style
181 Do not strip leading slashes
184 The default is to strip leading slashes.
186 Preserve user and group ID as well as file mode regardless of
189 The setuid and setgid bits are only preserved if the user is
191 Only meaningful in conjunction with the
195 Select the first archive member that matches each
198 No more than one archive member is matched for each
200 When members of type directory are matched, the file hierarchy rooted at that
201 directory is also matched.
203 Modify the archive member names according to the substitution expression
205 using the syntax of the
207 utility regular expressions.
209 arguments may be given to restrict the list of archive members to those
212 The format of these regular expressions is
219 is a basic regular expression (see
223 can contain an ampersand
228 is a digit) back-references,
229 or subexpression matching.
232 string may also contain newline characters.
233 Any non-null character can be used as a delimiter
240 expressions can be specified.
241 The expressions are applied in the order they are specified on the
242 command line, terminating with the first successful substitution.
244 The optional trailing
246 continues to apply the substitution expression to the pathname substring,
247 which starts with the first character following the end of the last successful
249 The first unsuccessful substitution stops the operation of the
252 The optional trailing
254 will cause the final result of a successful substitution to be written to
255 standard error in the following format:
257 .D1 Em original-pathname No >> Em new-pathname
259 File or archive member names that substitute to the empty string
260 are not selected and will be skipped.
262 Verbose operation mode.
264 Interactively rename files.
267 to prompt the user for the filename to use when storing or
268 extracting files in an archive.
270 Do not cross mount points in the file system.
272 Compress archive using
275 Compress archive using
281 can be used to select one of the compiled-in backup devices,
286 Path in which to store temporary files.
288 Default tape device to use instead of
292 .Bl -tag -width "/dev/rst0"
297 Create an archive on the default tape drive, containing the files named
302 .Dl $ tar c bonvole sekve
306 compressed archive containing the files
313 .Dl $ tar zcf foriru.tar.gz bonvole sekve
315 Verbosely create an archive, called
317 of all files matching the shell
322 .Dl $ tar zcvf backup.tar.gz *.c
324 Verbosely list, but do not extract, all files ending in
326 from a compressed archive named
328 Note that the glob pattern has been quoted to avoid expansion by the shell:
330 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
332 For more detailed examples, see
336 will exit with one of the following values:
337 .Bl -tag -width 2n -offset indent
339 All files were processed successfully.
346 cannot create a file or a link when extracting an archive or cannot
347 find a file while writing an archive, or cannot preserve the user
348 ID, group ID, file mode, or access and modification times when the
350 option is specified, a diagnostic message is written to standard
351 error and a non-zero exit value will be returned, but processing
355 cannot create a link to a file,
357 will not create a second copy of the file.
359 If the extraction of a file from an archive is prematurely terminated
360 by a signal or error,
362 may have only partially extracted the file the user wanted.
363 Additionally, the file modes of extracted files and directories may
364 have incorrect file bits, and the modification and access times may
367 If the creation of an archive is prematurely terminated by a signal
370 may have only partially created the archive, which may violate the
371 specific archive format specification.
378 command first appeared in
381 Keith Muller at the University of California, San Diego.
387 flags are not portable to other versions of
389 where they may have a different meaning.