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