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