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