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