1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
4 .\" Copyright 2012 Milan Jurik. All rights reserved.
5 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH TAR 1 "May 9, 2012"
14 .SH NAME
15 tar \- create tape archives and add or extract files
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fBtar\fR c[BDeEFhilnopPqTvw@/[0-7]][bfk][X...][a|j|J|z|Z] [\fIblocksize\fR]
20 [\fItarfile\fR] [\fIsize\fR] [\fIexclude-file\fR]...
21 {\fIfile\fR | \(miI \fIinclude-file\fR | \(miC \fIdirectory\fR \fIfile\fR}...
22 .fi
23
24 .LP
25 .nf
26 \fBtar\fR r[BDeEFhilnqTvw@/[0-7]][bfk][j|J|z|Z] [\fIblocksize\fR] [\fItarfile\fR]
27 [\fIsize\fR]
28 {\fIfile\fR | \(miI \fIinclude-file\fR | \(miC \fIdirectory\fR \fIfile\fR}...
29 .fi
30
31 .LP
32 .nf
33 \fBtar\fR t[BeFhilnqTv[0-7]][fk][X...][j|J|z|Z] [\fItarfile\fR] [\fIsize\fR]
34 [\fIexclude-file\fR]... {\fIfile\fR | \(miI \fIinclude-file\fR}...
35 .fi
36
37 .LP
38 .nf
39 \fBtar\fR u[BDeEFhilnqTvw@/[0-7]][bfk][j|J|z|Z] [\fIblocksize\fR] [\fItarfile\fR]
40 [\fIsize\fR] \fIfile\fR...
41 .fi
42
43 .LP
44 .nf
45 \fBtar\fR x[BeFhilmnopqTvw@/[0-7]][fk][X...][j|J|z|Z] [\fItarfile\fR] [\fIsize\fR]
46 [\fIexclude-file\fR]... [\(miC \fIdirectory\fR] [\fIfile\fR]...
47 .fi
48
49 .SH DESCRIPTION
50 .sp
51 .LP
52 The \fBtar\fR command archives and extracts files to and from a single file
53 called a \fItarfile\fR. A tarfile is usually a magnetic tape, but it can be any
54 file. \fBtar\fR's actions are controlled by the \fIkey\fR argument. The
55 \fIkey\fR is a string of characters containing exactly one function letter
56 (\fBc\fR, \fBr\fR, \fBt\fR , \fBu\fR, or \fBx\fR) and zero or more function
57 modifiers (letters or digits), depending on the function letter used. The
58 \fIkey\fR string contains no SPACE characters. Function modifier arguments are
59 listed on the command line in the same order as their corresponding function
60 modifiers appear in the \fIkey\fR string.
61 .sp
62 .LP
63 The \fB\(miI\fR \fIinclude-file\fR, \fB\(miC\fR \fIdirectory file\fR, and
64 \fIfile\fR arguments specify which files or directories are to be archived or
65 extracted. In all cases, appearance of a directory name refers to the files and
66 (recursively) subdirectories of that directory. Arguments appearing within
67 braces (\fB{ }\fR) indicate that one of the arguments must be specified.
68 .SH OPERANDS
69 .sp
70 .LP
71 The following operands are supported:
72 .sp
73 .ne 2
74 .na
75 \fB\fB\(miC\fR \fIdirectory file\fR\fR
76 .ad
77 .sp .6
78 .RS 4n
79 Performs a \fBchdir\fR (see \fBcd\fR(1)) operation on \fIdirectory\fR and
80 performs the \fBc\fR (create) or \fBr\fR (replace) operation on \fIfile\fR. Use
81 short relative path names for \fIfile\fR. If \fIfile\fR is "\fB\&.\fR", archive
82 all files in \fIdirectory\fR. This operand enables archiving files from
83 multiple directories not related by a close common parent.
84 .sp
85 This option may also be passed once to \fBx\fR (extract). In this case the
86 program will \fBchdir\fR to \fIdirectory\fR after opening the archive, but
87 before extracting its contents.
88 .RE
89
90 .sp
91 .ne 2
92 .na
93 \fB\fB\(miI\fR \fIinclude-file\fR\fR
94 .ad
95 .sp .6
96 .RS 4n
97 Opens \fIinclude-file\fR containing a list of files, one per line, and treats
98 it as if each file appeared separately on the command line. Be careful of
99 trailing white spaces. Also beware of leading white spaces, since, for each
100 line in the included file, the entire line (apart from the newline) is used to
101 match against the initial string of files to include. In the case where
102 excluded files (see \fBX\fR function modifier) are also specified, they take
103 precedence over all included files. If a file is specified in both the
104 \fIexclude-file\fR and the \fIinclude-file\fR (or on the command line), it is
105 excluded.
106 .RE
107
108 .sp
109 .ne 2
110 .na
111 \fB\fIfile\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 A path name of a regular file or directory to be archived (when the \fBc\fR,
116 \fBr\fR or \fBu\fR functions are specified), extracted (\fBx\fR) or listed
117 (\fBt\fR). When \fIfile\fR is the path name of a directory, the action applies
118 to all of the files and (recursively) subdirectories of that directory.
119 .sp
120 When a file is archived, and the \fBE\fR flag (see \fBFunction Modifiers\fR) is
121 not specified, the filename cannot exceed 256 characters. In addition, it must
122 be possible to split the name between parent directory names so that the prefix
123 is no longer than 155 characters and the name is no longer than 100 characters.
124 If \fBE\fR is specified, a name of up to \fIPATH_MAX\fR characters can be
125 specified.
126 .sp
127 For example, a file whose basename is longer than 100 characters could not be
128 archived without using the \fBE\fR flag. A file whose directory portion is 200
129 characters and whose basename is 50 characters could be archived (without using
130 \fBE\fR) if a slash appears in the directory name somewhere in character
131 positions 151-156.
132 .RE
133
134 .SS "Function Letters"
135 .sp
136 .LP
137 The function portion of the key is specified by one of the following letters:
138 .sp
139 .ne 2
140 .na
141 \fB\fBc\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 Create. Writing begins at the beginning of the tarfile, instead of at the end.
146 .RE
147
148 .sp
149 .ne 2
150 .na
151 \fB\fBr\fR\fR
152 .ad
153 .sp .6
154 .RS 4n
155 Replace. The named \fIfile\fRs are written at the end of the tarfile. A file
156 created with extended headers must be updated with extended headers (see
157 \fBE\fR flag under \fBFunction Modifiers\fR). A file created without extended
158 headers cannot be modified with extended headers.
159 .RE
160
161 .sp
162 .ne 2
163 .na
164 \fB\fBt\fR\fR
165 .ad
166 .sp .6
167 .RS 4n
168 Table of Contents. The names of the specified files are listed each time they
169 occur in the tarfile. If no \fIfile\fR argument is specified, the names of all
170 files and any associated extended attributes in the tarfile are listed. With
171 the \fBv\fR function modifier, additional information for the specified files
172 is displayed.
173 .RE
174
175 .sp
176 .ne 2
177 .na
178 \fB\fBu\fR\fR
179 .ad
180 .sp .6
181 .RS 4n
182 Update. The named \fIfile\fRs are written at the end of the tarfile if they are
183 not already in the tarfile, or if they have been modified since last written to
184 that tarfile. An update can be rather slow. A tarfile created on a 5.x system
185 cannot be updated on a 4.x system. A file created with extended headers must be
186 updated with extended headers (see \fBE\fR flag under \fBFunction
187 Modifiers\fR). A file created without extended headers cannot be modified with
188 extended headers.
189 .RE
190
191 .sp
192 .ne 2
193 .na
194 \fB\fBx\fR\fR
195 .ad
196 .sp .6
197 .RS 4n
198 Extract or restore. The named \fIfile\fRs are extracted from the tarfile and
199 written to the directory specified in the tarfile, relative to the current
200 directory. Use the relative path names of files and directories to be
201 extracted.
202 .sp
203 Absolute path names contained in the tar archive are unpacked using the
204 absolute path names, that is, the leading forward slash (\fB/\fR) is \fBnot\fR
205 stripped off.
206 .sp
207 If a named file matches a directory whose contents has been written to the
208 tarfile, this directory is recursively extracted. The owner, modification time,
209 and mode are restored (if possible); otherwise, to restore owner, you must be
210 the super-user. Character-special and block-special devices (created by
211 \fBmknod\fR(1M)) can only be extracted by the super-user. If no \fIfile\fR
212 argument is specified, the entire content of the tarfile is extracted. If the
213 tarfile contains several files with the same name, each file is written to the
214 appropriate directory, overwriting the previous one. Filename substitution
215 wildcards cannot be used for extracting files from the archive. Rather, use a
216 command of the form:
217 .sp
218 .in +2
219 .nf
220 \fBtar xvf ... /dev/rmt/0 \(gatar tf ... /dev/rmt/0 | \e
221 grep '\fIpattern\fR' \(ga\fR
222 .fi
223 .in -2
224 .sp
225
226 .RE
227
228 .sp
229 .LP
230 When extracting tapes created with the \fBr\fR or \fBu\fR functions, directory
231 modification times can not be set correctly. These same functions cannot be
232 used with many tape drives due to tape drive limitations such as the absence of
233 backspace or append capabilities.
234 .sp
235 .LP
236 When using the \fBr\fR, \fBu\fR, or \fBx\fR functions or the \fBX\fR function
237 modifier, the named files must match exactly the corresponding files in the
238 \fItarfile\fR. For example, to extract \fB\&./\fR\fIthisfile\fR, you must
239 specify \fB\&./\fR\fIthisfile,\fR and not \fIthisfile\fR. The \fBt\fR function
240 displays how each file was archived.
241 .SS "Function Modifiers"
242 .sp
243 .LP
244 The characters below can be used in conjunction with the letter that selects
245 the desired function.
246 .sp
247 .ne 2
248 .na
249 \fB\fBa\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
253 During a \fBcreate\fR operation autodetect compression based on the archive
254 suffix.
255 .RE
256
257 .sp
258 .ne 2
259 .na
260 \fB\fBb\fR \fIblocksize\fR\fR
261 .ad
262 .sp .6
263 .RS 4n
264 Blocking Factor. Use when reading or writing to raw magnetic archives (see
265 \fBf\fR below). The \fIblocksize\fR argument specifies the number of 512-byte
266 tape blocks to be included in each read or write operation performed on the
267 tarfile. The minimum is \fB1\fR, the default is \fB20\fR. The maximum value is
268 a function of the amount of memory available and the blocking requirements of
269 the specific tape device involved (see \fBmtio\fR(7I) for details.) The maximum
270 cannot exceed \fBINT_MAX\fR/512 (\fB4194303\fR).
271 .sp
272 When a tape archive is being read, its actual blocking factor is automatically
273 detected, provided that it is less than or equal to the nominal blocking factor
274 (the value of the \fIblocksize\fR argument, or the default value if the \fBb\fR
275 modifier is not specified). If the actual blocking factor is greater than the
276 nominal blocking factor, a read error results. See Example 5 in EXAMPLES.
277 .RE
278
279 .sp
280 .ne 2
281 .na
282 \fB\fBB\fR\fR
283 .ad
284 .sp .6
285 .RS 4n
286 Block. Force \fBtar\fR to perform multiple reads (if necessary) to read exactly
287 enough bytes to fill a block. This function modifier enables \fBtar\fR to work
288 across the Ethernet, since pipes and sockets return partial blocks even when
289 more data is coming. When reading from standard input, "\fB\(mi\fR", this
290 function modifier is selected by default to ensure that \fBtar\fR can recover
291 from short reads.
292 .RE
293
294 .sp
295 .ne 2
296 .na
297 \fB\fBD\fR\fR
298 .ad
299 .sp .6
300 .RS 4n
301 Data change warnings. Used with \fBc\fR, \fBr\fR, or \fBu\fR function letters.
302 Ignored with \fBt\fR or \fBx\fR function letters. If the size of a file changes
303 while the file is being archived, treat this condition as a warning instead of
304 as an error. A warning message is still written, but the exit status is not
305 affected.
306 .RE
307
308 .sp
309 .ne 2
310 .na
311 \fB\fBe\fR\fR
312 .ad
313 .sp .6
314 .RS 4n
315 Error. Exit immediately with a positive exit status if any unexpected errors
316 occur. The \fBSYSV3\fR environment variable overrides the default behavior.
317 (See ENVIRONMENT VARIABLES section below.)
318 .RE
319
320 .sp
321 .ne 2
322 .na
323 \fB\fBE\fR\fR
324 .ad
325 .sp .6
326 .RS 4n
327 Write a tarfile with extended headers. (Used with \fBc\fR, \fBr\fR, or \fBu\fR
328 function letters. Ignored with \fBt\fR or \fBx\fR function letters.) When a
329 tarfile is written with extended headers, the modification time is maintained
330 with a granularity of microseconds rather than seconds. In addition, filenames
331 no longer than \fBPATH_MAX\fR characters that could not be archived without
332 \fBE\fR, and file sizes greater than \fB8GB\fR, are supported. The \fBE\fR flag
333 is required whenever the larger files and/or files with longer names, or whose
334 \fBUID/GID\fR exceed \fB2097151\fR, are to be archived, or if time granularity
335 of microseconds is desired.
336 .RE
337
338 .sp
339 .ne 2
340 .na
341 \fB\fBf\fR\fR
342 .ad
343 .sp .6
344 .RS 4n
345 File. Use the \fItarfile\fR argument as the name of the tarfile. If \fBf\fR is
346 specified, \fB/etc/default/tar\fR is not searched. If \fBf\fR is omitted,
347 \fBtar\fR uses the device indicated by the \fBTAPE\fR environment variable, if
348 set. Otherwise, \fBtar\fR uses the default values defined in
349 \fB/etc/default/tar\fR. The number matching the \fBarchive\fR\fIN\fR string is
350 used as the output device with the blocking and size specifications from the
351 file. For example,
352 .sp
353 .in +2
354 .nf
355 \fBtar -c 2/tmp/*\fR
356 .fi
357 .in -2
358 .sp
359
360 writes the output to the device specified as \fBarchive2\fR in
361 \fB/etc/default/tar\fR.
362 .sp
363 If the name of the tarfile is "\fB\(mi\fR", \fBtar\fR writes to the standard
364 output or reads from the standard input, whichever is appropriate. \fBtar\fR
365 can be used as the head or tail of a pipeline. \fBtar\fR can also be used to
366 move hierarchies with the command:
367 .sp
368 .in +2
369 .nf
370 example% \fBcd fromdir; tar cf \(mi .| (cd todir; tar xfBp \(mi)\fR
371 .fi
372 .in -2
373 .sp
374
375 .RE
376
377 .sp
378 .ne 2
379 .na
380 \fB\fBF\fR\fR
381 .ad
382 .sp .6
383 .RS 4n
384 With one \fBF\fR argument, \fBtar\fR excludes all directories named \fBSCCS\fR
385 and \fBRCS\fR from the tarfile. With two arguments, \fBFF\fR, \fBtar\fR
386 excludes all directories named SCCS and RCS, all files with \fB\&.o\fR as their
387 suffix, and all files named \fBerrs\fR, \fBcore\fR, and \fBa.out\fR. The
388 \fBSYSV3\fR environment variable overrides the default behavior. (See
389 ENVIRONMENT VARIABLES section below.)
390 .RE
391
392 .sp
393 .ne 2
394 .na
395 \fB\fBh\fR\fR
396 .ad
397 .sp .6
398 .RS 4n
399 Follow symbolic links as if they were normal files or directories. Normally,
400 \fBtar\fR does not follow symbolic links.
401 .RE
402
403 .sp
404 .ne 2
405 .na
406 \fB\fBi\fR\fR
407 .ad
408 .sp .6
409 .RS 4n
410 Ignore directory checksum errors.
411 .RE
412
413 .sp
414 .ne 2
415 .na
416 \fB\fBj\fR\fR
417 .ad
418 .sp .6
419 .RS 4n
420 Use \fBbzip2\fR for compressing or decompressing the archives.
421 .RE
422
423 .sp
424 .ne 2
425 .na
426 \fB\fBJ\fR\fR
427 .ad
428 .sp .6
429 .RS 4n
430 Use \fBxz\fR for compressing or decompressing the archives.
431 .RE
432
433 .sp
434 .ne 2
435 .na
436 \fB\fBk\fR \fIsize\fR\fR
437 .ad
438 .sp .6
439 .RS 4n
440 Requires \fBtar\fR to use the size argument as the size of an archive in
441 kilobytes. This is useful when the archive is intended for a fixed size device
442 such as floppy disks. Large files are then split across volumes if they do not
443 fit in the specified size.
444 .RE
445
446 .sp
447 .ne 2
448 .na
449 \fB\fBl\fR\fR
450 .ad
451 .sp .6
452 .RS 4n
453 Link. Output error message if unable to resolve all links to the files being
454 archived. If \fBl\fR is not specified, no error messages are printed.
455 .RE
456
457 .sp
458 .ne 2
459 .na
460 \fB\fBm\fR\fR
461 .ad
462 .sp .6
463 .RS 4n
464 Modify. The modification time of the file is the time of extraction. This
465 function modifier is valid only with the \fBx\fR function.
466 .RE
467
468 .sp
469 .ne 2
470 .na
471 \fB\fBn\fR\fR
472 .ad
473 .sp .6
474 .RS 4n
475 The file being read is a non-tape device. Reading of the archive is faster
476 since \fBtar\fR can randomly seek around the archive.
477 .RE
478
479 .sp
480 .ne 2
481 .na
482 \fB\fBo\fR\fR
483 .ad
484 .sp .6
485 .RS 4n
486 Ownership. Assign to extracted files the user and group identifiers of the user
487 running the program, rather than those on tarfile. This is the default behavior
488 for users other than root. If the \fBo\fR function modifier is not set and the
489 user is root, the extracted files takes on the group and user identifiers of
490 the files on tarfile (see \fBchown\fR(1) for more information). The \fBo\fR
491 function modifier is only valid with the \fBx\fR function.
492 .RE
493
494 .sp
495 .ne 2
496 .na
497 \fB\fBp\fR\fR
498 .ad
499 .sp .6
500 .RS 4n
501 Restore the named files to their original modes, and \fBACL\fRs if applicable,
502 ignoring the present \fBumask\fR(1). This is the default behavior if invoked as
503 super-user with the \fBx\fR function letter specified. If super-user,
504 \fBSETUID\fR, and sticky information are also extracted, and files are restored
505 with their original owners and permissions, rather than owned by root. When
506 this function modifier is used with the \fBc\fR function, \fBACL\fRs are
507 created in the tarfile along with other information. Errors occur when a
508 tarfile with \fBACL\fRs is extracted by previous versions of \fBtar\fR.
509 .RE
510
511 .sp
512 .ne 2
513 .na
514 \fB\fBP\fR\fR
515 .ad
516 .sp .6
517 .RS 4n
518 Suppress the addition of a trailing "\fB/\fR" on directory entries in the
519 archive.
520 .RE
521
522 .sp
523 .ne 2
524 .na
525 \fB\fBq\fR\fR
526 .ad
527 .sp .6
528 .RS 4n
529 Stop after extracting the first occurrence of the named file. \fBtar\fR
530 normally continues reading the archive after finding an occurrence of a file.
531 .RE
532
533 .sp
534 .ne 2
535 .na
536 \fB\fBT\fR\fR
537 .ad
538 .sp .6
539 .RS 4n
540 This modifier is only available if the system is configured with Trusted
541 Extensions.
542 .sp
543 When this modifier is used with the function letter \fBc\fR, \fBr,\fR or
544 \fBu\fR for creating, replacing or updating a tarfile, the sensitivity label
545 associated with each archived file and directory is stored in the tarfile.
546 .sp
547 Specifying \fBT\fR implies the function modifier \fBp\fR.
548 .sp
549 When used with the function letter \fBx\fR for extracting a tarfile, the tar
550 program verifies that the file's sensitivity label specified in the archive
551 equals the sensitivity label of the destination directory. If not, the file is
552 not restored. This operation must be invoked from the global zone. If the
553 archived file has a relative pathname, it is restored to the corresponding
554 directory with the same label, if available. This is done by prepending to the
555 current destination directory the root pathname of the zone whose label equals
556 the file. If no such zone exists, the file is not restored.
557 .sp
558 Limited support is provided for extracting labeled archives from Trusted
559 Solaris 8. Only sensitivity labels, and multi-level directory specifications
560 are interpreted. Privilege specifications and audit attribute flags are
561 silently ignored. Multilevel directory specifications including symbolic links
562 to single level directories are are mapped into zone-relative pathnames if a
563 zone with the same label is available. This support is intended to facilitate
564 migration of home directories. Architectural differences preclude the
565 extraction of arbitrarily labeled files from Trusted Solaris 8 into identical
566 pathnames in Trusted Extensions. Files cannot be extracted unless their
567 archived label matches the destination label.
568 .RE
569
570 .sp
571 .ne 2
572 .na
573 \fB\fBv\fR\fR
574 .ad
575 .sp .6
576 .RS 4n
577 Verbose. Output the name of each file preceded by the function letter. With the
578 \fBt\fR function, \fBv\fR provides additional information about the tarfile
579 entries. The listing is similar to the format produced by the \fB-l\fR option
580 of the \fBls\fR(1) command.
581 .RE
582
583 .sp
584 .ne 2
585 .na
586 \fB\fBw\fR\fR
587 .ad
588 .sp .6
589 .RS 4n
590 What. Output the action to be taken and the name of the file, then await the
591 user's confirmation. If the response is affirmative, the action is performed;
592 otherwise, the action is not performed. This function modifier cannot be used
593 with the \fBt\fR function.
594 .RE
595
596 .sp
597 .ne 2
598 .na
599 \fB\fBX\fR\fR
600 .ad
601 .sp .6
602 .RS 4n
603 Exclude. Use the \fIexclude-file\fR argument as a file containing a list of
604 relative path names for files (or directories) to be excluded from the tarfile
605 when using the functions \fBc\fR, \fBx\fR, or \fBt\fR. Be careful of trailing
606 white spaces. Also beware of leading white spaces, since, for each line in the
607 excluded file, the entire line (apart from the newline) is used to match
608 against the initial string of files to exclude. Lines in the exclude file are
609 matched exactly, so an entry like "\fB/var\fR" does \fBnot\fR exclude the
610 \fB/var\fR directory if \fBtar\fR is backing up relative pathnames. The entry
611 should read "\fB\&./var\fR" under these circumstances. The \fBtar\fR command
612 does not expand shell metacharacters in the exclude file, so specifying entries
613 like "\fB*.o\fR" does not have the effect of excluding all files with names
614 suffixed with "\fB\&.o\fR". If a complex list of files is to be excluded, the
615 exclude file should be generated by some means such as the \fBfind\fR(1)
616 command with appropriate conditions.
617 .sp
618 Multiple \fBX\fR arguments can be used, with one \fIexclude-file\fR per
619 argument. In the case where included files (see \fB\(miI\fR \fIinclude-file\fR
620 operand) are also specified, the excluded files take precedence over all
621 included files. If a file is specified in both the \fIexclude-file\fR and the
622 \fIinclude-file\fR (or on the command line), it is excluded.
623 .RE
624
625 .sp
626 .ne 2
627 .na
628 \fB\fBz\fR\fR
629 .ad
630 .sp .6
631 .RS 4n
632 Use \fBgzip\fR for compressing or decompressing the archives.
633 .RE
634
635 .sp
636 .ne 2
637 .na
638 \fB\fBZ\fR\fR
639 .ad
640 .sp .6
641 .RS 4n
642 Use \fBcompress\fR for compressing or decompressing the archives.
643 .RE
644
645 .sp
646 .ne 2
647 .na
648 \fB\fB@\fR\fR
649 .ad
650 .sp .6
651 .RS 4n
652 Include extended attributes in archive. By default, \fBtar\fR does not place
653 extended attributes in the archive. With this flag, \fBtar\fR looks for
654 extended attributes on the files to be placed in the archive and add them to
655 the archive. Extended attributes go in the archive as special files with a
656 special type label. When this modifier is used with the \fBx\fR function,
657 extended attributes are extracted from the tape along with the normal file
658 data. Extended attribute files can only be extracted from an archive as part of
659 a normal file extract. Attempts to explicitly extract attribute records are
660 ignored.
661 .RE
662
663 .sp
664 .ne 2
665 .na
666 \fB\fB/\fR\fR
667 .ad
668 .sp .6
669 .RS 4n
670 Include extended system attributes in archive. By default, \fBtar\fR does not
671 place extended system attributes in the archive. With this flag, \fBtar\fR
672 looks for extended system attributes on the files to be placed in the archive
673 and adds them to the archive. Extended system attributes go in the archive as
674 special files with a special type label. When this modifier is used with the
675 \fBx\fR function, extended system attributes are extracted from the tape along
676 with the normal file data. Extended system attribute files can only be
677 extracted from an archive as part of a normal file extract. Attempts to
678 explicitly extract attribute records are ignored.
679 .RE
680
681 .sp
682 .ne 2
683 .na
684 \fB\fB[0-7]\fR\fR
685 .ad
686 .sp .6
687 .RS 4n
688 Select an alternative drive on which the tape is mounted. The default entries
689 are specified in \fB/etc/default/tar\fR. If no digit or \fBf\fR function
690 modifier is specified, the entry in \fB/etc/default/tar\fR with digit "\fB0\fR"
691 is the default.
692 .RE
693
694 .SH USAGE
695 .sp
696 .LP
697 See \fBlargefile\fR(5) for the description of the behavior of \fBtar\fR when
698 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
699 .sp
700 .LP
701 The automatic determination of the actual blocking factor can be fooled when
702 reading from a pipe or a socket (see the \fBB\fR function modifier below).
703 .sp
704 .LP
705 1/4" streaming tape has an inherent blocking factor of one 512-byte block. It
706 can be read or written using any blocking factor.
707 .sp
708 .LP
709 This function modifier works for archives on disk files and block special
710 devices, among others, but is intended principally for tape devices.
711 .sp
712 .LP
713 For information on \fBtar\fR header format, see \fBarchives.h\fR(3HEAD).
714 .SH EXAMPLES
715 .LP
716 \fBExample 1 \fRCreating an archive of your home directory
717 .sp
718 .LP
719 The following is an example using \fBtar\fR to create an archive of your home
720 directory on a tape mounted on drive \fB/dev/rmt/0\fR:
721
722 .sp
723 .in +2
724 .nf
725 example% \fBcd\fR
726 example% \fBtar cvf /dev/rmt/0\fR .
727 \fImessages from\fR tar
728 .fi
729 .in -2
730 .sp
731
732 .sp
733 .LP
734 The \fBc\fR function letter means create the archive. The \fBv\fR function
735 modifier outputs messages explaining what \fBtar\fR is doing. The \fBf\fR
736 function modifier indicates that the tarfile is being specified
737 (\fB/dev/rmt/0\fR in this example). The dot (\fB\&.\fR) at the end of the
738 command line indicates the current directory and is the argument of the \fBf\fR
739 function modifier.
740
741 .sp
742 .LP
743 Display the table of contents of the tarfile with the following command:
744
745 .sp
746 .in +2
747 .nf
748 example% \fBtar tvf /dev/rmt/0\fR
749 .fi
750 .in -2
751 .sp
752
753 .sp
754 .LP
755 The output is similar to the following for the POSIX locale:
756
757 .sp
758 .in +2
759 .nf
760 rw\(mir\(mi\(mir\(mi\(mi 1677/40 2123 Nov 7 18:15 1985 ./test.c
761 \&...
762 example%
763 .fi
764 .in -2
765 .sp
766
767 .sp
768 .LP
769 The columns have the following meanings:
770
771 .RS +4
772 .TP
773 .ie t \(bu
774 .el o
775 column 1 is the access permissions to \fB\&./test.c\fR
776 .RE
777 .RS +4
778 .TP
779 .ie t \(bu
780 .el o
781 column 2 is the \fIuser-id\fR/\fIgroup-id\fR of \fB\&./test.c\fR
782 .RE
783 .RS +4
784 .TP
785 .ie t \(bu
786 .el o
787 column 3 is the size of \fB\&./test.c\fR in bytes
788 .RE
789 .RS +4
790 .TP
791 .ie t \(bu
792 .el o
793 column 4 is the modification date of \fB\&./test.c\fR. When the \fBLC_TIME\fR
794 category is not set to the POSIX locale, a different format and date order
795 field can be used.
796 .RE
797 .RS +4
798 .TP
799 .ie t \(bu
800 .el o
801 column 5 is the name of \fB\&./test.c\fR
802 .RE
803 .sp
804 .LP
805 To extract files from the archive:
806
807 .sp
808 .in +2
809 .nf
810 example% \fBtar xvf /dev/rmt/0\fR
811 \fImessages from\fR tar
812 example%
813 .fi
814 .in -2
815 .sp
816
817 .sp
818 .LP
819 If there are multiple archive files on a tape, each is separated from the
820 following one by an EOF marker. To have \fBtar\fR read the first and second
821 archives from a tape with multiple archives on it, the \fInon-rewinding\fR
822 version of the tape device name must be used with the \fBf\fR function
823 modifier, as follows:
824
825 .sp
826 .in +2
827 .nf
828 example% \fBtar xvfp /dev/rmt/0n \fIread first archive from tape\fR\fR
829 \fImessages from\fR tar
830 example% \fBtar xvfp /dev/rmt/0n \fIread second archive from tape\fR\fR
831 \fImessages from\fR tar
832 example%
833 .fi
834 .in -2
835 .sp
836
837 .sp
838 .LP
839 Notice that in some earlier releases, the above scenario did not work
840 correctly, and intervention with \fBmt\fR(1) between \fBtar\fR invocations was
841 necessary. To emulate the old behavior, use the non-rewind device name
842 containing the letter \fBb\fR for BSD behavior. See the \fBClose Operations\fR
843 section of the \fBmtio\fR(7I) manual page.
844
845 .LP
846 \fBExample 2 \fRArchiving files from /usr/include and from /etc to default tape
847 drive 0
848 .sp
849 .LP
850 To archive files from \fB/usr/include\fR and from \fB/etc\fR to default tape
851 drive \fB0\fR:
852
853 .sp
854 .in +2
855 .nf
856 example% \fBtar c -C /usr include -C /etc .\fR
857 .fi
858 .in -2
859 .sp
860
861 .sp
862 .LP
863 The table of contents from the resulting tarfile would produce output like the
864 following:
865
866 .sp
867 .in +2
868 .nf
869 include/
870 include/a.out.h
871 \fIand all the other files in\fR \fB/usr/include ...\fR
872 \&./chown \fIand all the other files in\fR /etc
873 .fi
874 .in -2
875 .sp
876
877 .sp
878 .LP
879 To extract all files in the \fBinclude\fR directory:
880
881 .sp
882 .in +2
883 .nf
884 example% \fBtar xv include
885 x include/, 0 bytes, 0 tape blocks \e
886 \fIand all files under\fR include ...\fR
887 .fi
888 .in -2
889 .sp
890
891 .LP
892 \fBExample 3 \fRTransferring files across the network
893 .sp
894 .LP
895 The following is an example using \fBtar\fR to transfer files across the
896 network. First, here is how to archive files from the local machine
897 (\fBexample\fR) to a tape on a remote system (\fBhost\fR):
898
899 .sp
900 .in +2
901 .nf
902 example% \fBtar cvfb \(mi 20 \fIfiles\fR| \e
903 rsh \fIhost\fR dd of=/dev/rmt/0 obs=20b\fR
904 \fImessages from\fR tar
905 example%
906 .fi
907 .in -2
908 .sp
909
910 .sp
911 .LP
912 In the example above, we are \fIcreating\fR a \fItarfile\fR with the \fBc\fR
913 key letter, asking for \fIverbose\fR output from \fBtar\fR with the \fBv\fR
914 function modifier, specifying the name of the output \fItarfile\fR using the
915 \fBf\fR function modifier (the standard output is where the \fItarfile\fR
916 appears, as indicated by the `\fB\(mi\fR\&' sign), and specifying the blocksize
917 (\fB20\fR) with the \fBb\fR function modifier. If you want to change the
918 blocksize, you must change the blocksize arguments both on the \fBtar\fR
919 command \fIand\fR on the \fBdd\fR command.
920
921 .LP
922 \fBExample 4 \fRRetrieving files from a tape on the remote system back to the
923 local system
924 .sp
925 .LP
926 The following is an example that uses \fBtar\fR to retrieve files from a tape
927 on the remote system back to the local system:
928
929 .sp
930 .in +2
931 .nf
932 example% \fBrsh -n host dd if=/dev/rmt/0 bs=20b | \e
933 tar xvBfb \(mi 20 \fIfiles\fR\fR
934 \fImessages from\fR tar
935 example%
936 .fi
937 .in -2
938 .sp
939
940 .sp
941 .LP
942 In the example above, we are \fIextracting\fR from the \fItarfile\fR with the
943 \fBx\fR key letter, asking for \fIverbose\fR \fIoutput\fR \fIfrom\fR \fBtar\fR
944 with the \fBv\fR function modifier, telling \fBtar\fR it is reading from a pipe
945 with the \fBB\fR function modifier, specifying the name of the input
946 \fItarfile\fR using the \fBf\fR function modifier (the standard input is where
947 the \fItarfile\fR appears, as indicated by the "\fB\(mi\fR" sign), and
948 specifying the blocksize (\fB20\fR) with the \fBb\fR function modifier.
949
950 .LP
951 \fBExample 5 \fRCreating an archive of the home directory
952 .sp
953 .LP
954 The following example creates an archive of the home directory on
955 \fB/dev/rmt/0\fR with an actual blocking factor of \fB19\fR:
956
957 .sp
958 .in +2
959 .nf
960 example% \fBtar cvfb /dev/rmt/0 19 $HOME\fR
961 .fi
962 .in -2
963 .sp
964
965 .sp
966 .LP
967 To recognize this archive's actual blocking factor without using the \fBb\fR
968 function modifier:
969
970 .sp
971 .in +2
972 .nf
973 example% \fBtar tvf /dev/rmt/0\fR
974 tar: blocksize = 19
975 \&...
976 .fi
977 .in -2
978 .sp
979
980 .sp
981 .LP
982 To recognize this archive's actual blocking factor using a larger nominal
983 blocking factor:
984
985 .sp
986 .in +2
987 .nf
988 example% \fBtar tvf /dev/rmt/0 30\fR
989 tar: blocksize = 19
990 \&...
991 .fi
992 .in -2
993 .sp
994
995 .sp
996 .LP
997 Attempt to recognize this archive's actual blocking factor using a nominal
998 blocking factor that is too small:
999
1000 .sp
1001 .in +2
1002 .nf
1003 example% \fBtar tvf /dev/rmt/0 10\fR
1004 tar: tape read error
1005 .fi
1006 .in -2
1007 .sp
1008
1009 .SH ENVIRONMENT VARIABLES
1010 .sp
1011 .LP
1012 See \fBenviron\fR(5) for descriptions of the following environment variables
1013 that affect the execution of \fBtar\fR: \fBLC_COLLATE\fR, \fBLC_CTYPE\fR,
1014 \fBLC_MESSAGES\fR, \fBLC_TIME\fR, \fBTZ\fR, and \fBNLSPATH\fR.
1015 .sp
1016 .LP
1017 Affirmative responses are processed using the extended regular expression
1018 defined for the \fByesexpr\fR keyword in the \fBLC_MESSAGES\fR category of the
1019 user's locale. The locale specified in the \fBLC_COLLATE\fR category defines
1020 the behavior of ranges, equivalence classes, and multi-character collating
1021 elements used in the expression defined for \fByesexpr\fR. The locale specified
1022 in \fBLC_CTYPE\fR determines the locale for interpretation of sequences of
1023 bytes of text data a characters, the behavior of character classes used in the
1024 expression defined for the \fByesexpr\fR. See \fBlocale\fR(5).
1025 .SH EXIT STATUS
1026 .sp
1027 .LP
1028 The following exit values are returned:
1029 .sp
1030 .ne 2
1031 .na
1032 \fB\fB0\fR\fR
1033 .ad
1034 .sp .6
1035 .RS 4n
1036 Successful completion.
1037 .RE
1038
1039 .sp
1040 .ne 2
1041 .na
1042 \fB\fB>0\fR\fR
1043 .ad
1044 .sp .6
1045 .RS 4n
1046 An error occurred.
1047 .RE
1048
1049 .SH FILES
1050 .sp
1051 .ne 2
1052 .na
1053 \fB\fB/dev/rmt/[0-7][b][n]\fR\fR
1054 .ad
1055 .sp .6
1056 .RS 4n
1057
1058 .RE
1059
1060 .sp
1061 .ne 2
1062 .na
1063 \fB\fB/dev/rmt/[0-7]l[b][n]\fR\fR
1064 .ad
1065 .sp .6
1066 .RS 4n
1067
1068 .RE
1069
1070 .sp
1071 .ne 2
1072 .na
1073 \fB\fB/dev/rmt/[0-7]m[b][n]\fR\fR
1074 .ad
1075 .sp .6
1076 .RS 4n
1077
1078 .RE
1079
1080 .sp
1081 .ne 2
1082 .na
1083 \fB\fB/dev/rmt/[0-7]h[b][n]\fR\fR
1084 .ad
1085 .sp .6
1086 .RS 4n
1087
1088 .RE
1089
1090 .sp
1091 .ne 2
1092 .na
1093 \fB\fB/dev/rmt/[0-7]u[b][n]\fR\fR
1094 .ad
1095 .sp .6
1096 .RS 4n
1097
1098 .RE
1099
1100 .sp
1101 .ne 2
1102 .na
1103 \fB\fB/dev/rmt/[0-7]c[b][n]\fR\fR
1104 .ad
1105 .sp .6
1106 .RS 4n
1107
1108 .RE
1109
1110 .sp
1111 .ne 2
1112 .na
1113 \fB\fB/etc/default/tar\fR\fR
1114 .ad
1115 .sp .6
1116 .RS 4n
1117 Settings might look like this:
1118 .br
1119 .in +2
1120 \fBarchive0=/dev/rmt/0\fR
1121 .in -2
1122 .br
1123 .in +2
1124 \fBarchive1=/dev/rmt/0n\fR
1125 .in -2
1126 .br
1127 .in +2
1128 \fBarchive2=/dev/rmt/1\fR
1129 .in -2
1130 .br
1131 .in +2
1132 \fBarchive3=/dev/rmt/1n\fR
1133 .in -2
1134 .br
1135 .in +2
1136 \fBarchive4=/dev/rmt/0\fR
1137 .in -2
1138 .br
1139 .in +2
1140 \fBarchive5=/dev/rmt/0n\fR
1141 .in -2
1142 .br
1143 .in +2
1144 \fBarchive6=/dev/rmt/1\fR
1145 .in -2
1146 .br
1147 .in +2
1148 \fBarchive7=/dev/rmt/1n\fR
1149 .in -2
1150 .RE
1151
1152 .sp
1153 .ne 2
1154 .na
1155 \fB\fB/tmp/tar*\fR\fR
1156 .ad
1157 .sp .6
1158 .RS 4n
1159
1160 .RE
1161
1162 .SH ATTRIBUTES
1163 .sp
1164 .LP
1165 See \fBattributes\fR(5) for descriptions of the following attributes:
1166 .sp
1167
1168 .sp
1169 .TS
1170 box;
1171 c | c
1172 l | l .
1173 ATTRIBUTE TYPE ATTRIBUTE VALUE
1174 _
1175 CSI Enabled
1176 _
1177 Interface Stability Committed
1178 .TE
1179
1180 .SH SEE ALSO
1181 .sp
1182 .LP
1183 \fBar\fR(1), \fBbasename\fR(1), \fBbzip2\fR(1), \fBcd\fR(1), \fBchown\fR(1),
1184 \fBcompress\fR)(1), \fBcpio\fR(1), \fBcsh\fR(1), \fBdirname\fR(1),
1185 \fBfind\fR(1), \fBgzip\fR(1), \fBls\fR(1), \fBmt\fR(1), \fBpax\fR(1),
1186 \fBsetfacl\fR(1), \fBumask\fR(1), \fBxz\fR(1), \fBmknod\fR(1M),
1187 \fBarchives.h\fR(3HEAD), \fBattributes\fR(5), \fBenviron\fR(5),
1188 \fBfsattr\fR(5), \fBlargefile\fR(5), \fBmtio\fR(7I)
1189 .SH DIAGNOSTICS
1190 .sp
1191 .LP
1192 Diagnostic messages are output for bad key characters and tape read/write
1193 errors, and for insufficient memory to hold the link tables.
1194 .SH NOTES
1195 .sp
1196 .LP
1197 There is no way to access the \fIn\fR-th occurrence of a file.
1198 .sp
1199 .LP
1200 Tape errors are handled ungracefully.
1201 .sp
1202 .LP
1203 The \fBtar\fR archive format allows \fBUID\fRs and \fBGID\fRs up to
1204 \fB2097151\fR to be stored in the archive header. Files with \fBUID\fRs and
1205 \fBGID\fRs greater than this value is archived with the \fBUID\fR and \fBGID\fR
1206 of \fB60001\fR.
1207 .sp
1208 .LP
1209 If an archive is created that contains files whose names were created by
1210 processes running in multiple locales, a single locale that uses a full 8-bit
1211 codeset (for example, the \fBen_US\fR locale) should be used both to create the
1212 archive and to extract files from the archive.
1213 .sp
1214 .LP
1215 Neither the \fBr\fR function letter nor the \fBu\fR function letter can be used
1216 with quarter-inch archive tapes, since these tape drives cannot backspace.
1217 .sp
1218 .LP
1219 Since \fBtar\fR has no options, the standard "\fB\(mi\(mi\fR" argument that is
1220 normally used in other utilities to terminate recognition of options is not
1221 needed. If used, it is recognized only as the first argument and is ignored.
1222 .sp
1223 .LP
1224 Since \fB\(miC\fR \fIdirectory\fR \fIfile\fR and \fB\(miI\fR \fIinclude-file\fR
1225 are multi-argument operands, any of the following methods can be used to
1226 archive or extract a file named \fB\(miC\fR or \fB\(miI\fR:
1227 .RS +4
1228 .TP
1229 1.
1230 Specify them using file operands containing a \fB/\fR character on the
1231 command line (such as \fB/home/joe/\(miC\fR or \fB\&./\(miI\fR).
1232 .RE
1233 .RS +4
1234 .TP
1235 2.
1236 Include them in an include file with \fB\(miI\fR \fIinclude-file\fR.
1237 .RE
1238 .RS +4
1239 .TP
1240 3.
1241 Specify the directory in which the file resides:
1242 .sp
1243 .in +2
1244 .nf
1245 \fB-C \fIdirectory\fR -C\fR
1246 .fi
1247 .in -2
1248 .sp
1249
1250 or
1251 .sp
1252 .in +2
1253 .nf
1254 \fB-C \fIdirectory\fR -I\fR
1255 .fi
1256 .in -2
1257 .sp
1258
1259 .RE
1260 .RS +4
1261 .TP
1262 4.
1263 Specify the entire directory in which the file resides:
1264 .sp
1265 .in +2
1266 .nf
1267 \fB-C \fIdirectory\fR .\fR
1268 .fi
1269 .in -2
1270 .sp
1271
1272 .RE