1 .\" $OpenBSD: tar.1,v 1.50 2008/06/11 00:49:08 pvalchev 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.50 2008/06/11 00:49:08 pvalchev Exp $
28 .Dd $Mdocdate: June 11 2008 $
37 .No { Cm crtux No } Op Cm 014578befHhjLmOoPpqsvwXZz
40 .Op Ar blocking-factor | archive | replstr
46 .No { Ns Fl crtux Ns }
47 .Op Fl 014578eHhjLmOoPpqvwXZz
48 .Op Fl b Ar blocking-factor
57 command creates, adds files to, or extracts files from an
61 A tar archive is often stored on a magnetic tape, but can be
62 stored equally well on a floppy, CD-ROM, or in a regular disk file.
64 In the first (legacy) form, all option flags except for
68 must be contained within the first argument to
70 and must not be prefixed by a hyphen
72 Option arguments, if any, are processed as subsequent arguments to
74 and are processed in the order in which their corresponding option
75 flags have been presented on the command line.
77 In the second and preferred form, option flags may be given in any order
78 and are immediately followed by their corresponding option argument
81 One of the following flags must be present:
84 Create new archive, or overwrite an existing archive,
85 adding the specified files to it.
87 Append the named new files to existing archive.
88 Note that this will only work on media on which an end-of-file mark
91 List contents of archive.
92 If any files are named on the
93 command line, only those files will be listed.
96 arguments may be specified as glob patterns (see
98 for more information), in which case
100 will list all archive members that match each pattern.
105 Extract files from archive.
106 If any files are named on the
107 command line, only those files will be extracted from the
111 arguments may be specified as glob patterns (see
113 for more information), in which case
115 will extract all archive members that match each pattern.
117 If more than one copy of a file exists in the
118 archive, later copies will overwrite earlier copies during
120 The file mode and modification time are preserved
122 The file mode is subject to modification by the
126 In addition to the flags mentioned above, any of the following
129 .It Fl b Ar blocking-factor
130 Set blocking factor to use for the archive.
132 uses 512-byte blocks.
133 The default is 20, the maximum is 126.
134 Archives with a blocking factor larger than 63 violate the
136 standard and will not be portable to all systems.
137 .It Fl C Ar directory
138 This is a positional argument which sets the working directory for the
140 When extracting, files will be extracted into
141 the specified directory; when creating, the specified files will be matched
144 Stop after the first error.
146 Filename where the archive is stored.
150 Follow symlinks given on the command line only.
152 Follow symbolic links as if they were normal files
154 In extract mode this means that a directory entry in the archive
155 will not overwrite an existing symbolic link, but rather what the
156 link ultimately points to.
158 This is a positional argument which reads the names of files to
159 archive or extract from the given file, one per line.
161 Compress archive using bzip2.
162 The bzip2 utility must be installed separately.
168 Do not preserve modification time.
170 Write old-style (non-POSIX) archives.
172 Don't write directory information that the older (V7) style
179 Do not strip leading slashes
182 The default is to strip leading slashes.
184 Preserve user and group ID as well as file mode regardless of
187 The setuid and setgid bits are only preserved if the user is
189 Only meaningful in conjunction with the
193 Select the first archive member that matches each
196 No more than one archive member is matched for each
198 When members of type directory are matched, the file hierarchy rooted at that
199 directory is also matched.
201 Modify the archive member names according to the substitution expression
203 using the syntax of the
205 utility regular expressions.
207 arguments may be given to restrict the list of archive members to those
210 The format of these regular expressions is
217 is a basic regular expression (see
221 can contain an ampersand
226 is a digit) back-references,
227 or subexpression matching.
230 string may also contain newline characters.
231 Any non-null character can be used as a delimiter
238 expressions can be specified.
239 The expressions are applied in the order they are specified on the
240 command line, terminating with the first successful substitution.
242 The optional trailing
244 continues to apply the substitution expression to the pathname substring,
245 which starts with the first character following the end of the last successful
247 The first unsuccessful substitution stops the operation of the
250 The optional trailing
252 will cause the final result of a successful substitution to be written to
253 standard error in the following format:
255 .D1 Em original-pathname No >> Em new-pathname
257 File or archive member names that substitute to the empty string
258 are not selected and will be skipped.
260 Verbose operation mode.
262 Interactively rename files.
265 to prompt the user for the filename to use when storing or
266 extracting files in an archive.
268 Do not cross mount points in the file system.
270 Compress archive using
273 Compress archive using
279 can be used to select one of the compiled-in backup devices,
284 Path in which to store temporary files.
286 Default tape device to use instead of
290 .Bl -tag -width "/dev/rst0"
295 Create an archive on the default tape drive, containing the files named
300 .Dl $ tar c bonvole sekve
304 compressed archive containing the files
311 .Dl $ tar zcf foriru.tar.gz bonvole sekve
313 Verbosely create an archive, called
315 of all files matching the shell
320 .Dl $ tar zcvf backup.tar.gz *.c
322 Verbosely list, but do not extract, all files ending in
324 from a compressed archive named
326 Note that the glob pattern has been quoted to avoid expansion by the shell:
328 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
330 For more detailed examples, see
334 will exit with one of the following values:
335 .Bl -tag -width 2n -offset indent
337 All files were processed successfully.
344 cannot create a file or a link when extracting an archive or cannot
345 find a file while writing an archive, or cannot preserve the user
346 ID, group ID, file mode, or access and modification times when the
348 option is specified, a diagnostic message is written to standard
349 error and a non-zero exit value will be returned, but processing
353 cannot create a link to a file,
355 will not create a second copy of the file.
357 If the extraction of a file from an archive is prematurely terminated
358 by a signal or error,
360 may have only partially extracted the file the user wanted.
361 Additionally, the file modes of extracted files and directories may
362 have incorrect file bits, and the modification and access times may
365 If the creation of an archive is prematurely terminated by a signal
368 may have only partially created the archive, which may violate the
369 specific archive format specification.
376 command first appeared in
379 Keith Muller at the University of California, San Diego.
385 flags are not portable to other versions of
387 where they may have a different meaning.