bin/pax/tar.1

   1 .\"     $OpenBSD: tar.1,v 1.59 2015/09/13 15:42:11 guenther Exp $
   2 .\"
   3 .\" Copyright (c) 1996 SigmaSoft, Th. Lockert
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd $Mdocdate: September 13 2015 $
  27 .Dt TAR 1
  28 .Os
  29 .Sh NAME
  30 .Nm tar
  31 .Nd tape archiver
  32 .Sh SYNOPSIS
  33 .Nm tar
  34 .Sm off
  35 .No { Cm crtux No } Op Cm 014578befHhjLmNOoPpqsvwXZz
  36 .Sm on
  37 .Bk -words
  38 .Op Ar blocking-factor | archive | replstr
  39 .Op Fl C Ar directory
  40 .Op Fl I Ar file
  41 .Op Ar
  42 .Ek
  43 .Nm tar
  44 .No { Ns Fl crtux Ns }
  45 .Bk -words
  46 .Op Fl 014578eHhjLmNOoPpqvwXZz
  47 .Op Fl b Ar blocking-factor
  48 .Op Fl C Ar directory
  49 .Op Fl f Ar archive
  50 .Op Fl I Ar file
  51 .Op Fl s Ar replstr
  52 .Op Ar
  53 .Ek
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 command creates, adds files to, or extracts files from an
  58 archive file in
  59 .Dq tar
  60 format.
  61 A tar archive is often stored on a magnetic tape, but can be
  62 stored equally well on a floppy, CD-ROM, or in a regular disk file.
  63 .Pp
  64 In the first (legacy) form, all option flags except for
  65 .Fl C
  66 and
  67 .Fl I
  68 must be contained within the first argument to
  69 .Nm
  70 and must not be prefixed by a hyphen
  71 .Pq Sq - .
  72 Option arguments, if any, are processed as subsequent arguments to
  73 .Nm
  74 and are processed in the order in which their corresponding option
  75 flags have been presented on the command line.
  76 .Pp
  77 In the second and preferred form, option flags may be given in any order
  78 and are immediately followed by their corresponding option argument
  79 values.
  80 .Pp
  81 One of the following flags must be present:
  82 .Bl -tag -width Ds
  83 .It Fl c
  84 Create new archive, or overwrite an existing archive,
  85 adding the specified files to it.
  86 .It Fl r
  87 Append the named new files to existing archive.
  88 Note that this will only work on media on which an end-of-file mark
  89 can be overwritten.
  90 .It Fl t
  91 List contents of archive.
  92 If any files are named on the
  93 command line, only those files will be listed.
  94 The
  95 .Ar file
  96 arguments may be specified as glob patterns (see
  97 .Xr glob 3
  98 for more information), in which case
  99 .Nm
 100 will list all archive members that match each pattern.
 101 .It Fl u
 102 Alias for
 103 .Fl r .
 104 .It Fl x
 105 Extract files from archive.
 106 If any files are named on the
 107 command line, only those files will be extracted from the
 108 archive.
 109 The
 110 .Ar file
 111 arguments may be specified as glob patterns (see
 112 .Xr glob 3
 113 for more information), in which case
 114 .Nm
 115 will extract all archive members that match each pattern.
 116 .Pp
 117 If more than one copy of a file exists in the
 118 archive, later copies will overwrite earlier copies during
 119 extraction.
 120 The file mode and modification time are preserved
 121 if possible.
 122 The file mode is subject to modification by the
 123 .Xr umask 2 .
 124 .El
 125 .Pp
 126 In addition to the flags mentioned above, any of the following
 127 flags may be used:
 128 .Bl -tag -width Ds
 129 .It Fl b Ar blocking-factor
 130 Set blocking factor to use for the archive.
 131 .Nm
 132 uses 512-byte blocks.
 133 The default is 20, the maximum is 126.
 134 Archives with a blocking factor larger than 63
 135 violate the POSIX standard and will not be portable to all systems.
 136 .It Fl C Ar directory
 137 This is a positional argument which sets the working directory for the
 138 following files.
 139 When extracting, files will be extracted into
 140 the specified directory; when creating, the specified files will be matched
 141 from the directory.
 142 .It Fl e
 143 Stop after the first error.
 144 .It Fl f Ar archive
 145 Filename where the archive is stored.
 146 Defaults to
 147 .Pa /dev/rst0 .
 148 If set to hyphen
 149 .Pq Sq -
 150 standard output is used.
 151 See also the
 152 .Ev TAPE
 153 environment variable.
 154 .It Fl H
 155 Follow symlinks given on the command line only.
 156 .It Fl h
 157 Follow symbolic links as if they were normal files
 158 or directories.
 159 In extract mode this means that a directory entry in the archive
 160 will not overwrite an existing symbolic link, but rather what the
 161 link ultimately points to.
 162 .It Fl I Ar file
 163 This is a positional argument which reads the names of files to
 164 archive or extract from the given file, one per line.
 165 .It Fl j
 166 Compress archive using bzip2.
 167 The bzip2 utility must be installed separately.
 168 .It Fl L
 169 Synonym for the
 170 .Fl h
 171 option.
 172 .It Fl m
 173 Do not preserve modification time.
 174 .It Fl N
 175 Use only the numeric UID and GID values when creating or extracting an
 176 archive.
 177 .It Fl O
 178 Write old-style (non-POSIX) archives.
 179 .It Fl o
 180 Don't write directory information that the older (V7) style
 181 .Nm
 182 is unable to decode.
 183 This implies the
 184 .Fl O
 185 flag.
 186 .It Fl P
 187 Do not strip leading slashes
 188 .Pq Sq /
 189 from pathnames.
 190 The default is to strip leading slashes.
 191 .It Fl p
 192 Preserve user and group ID as well as file mode regardless of
 193 the current
 194 .Xr umask 2 .
 195 The setuid and setgid bits are only preserved if the user and group ID
 196 could be preserved.
 197 Only meaningful in conjunction with the
 198 .Fl x
 199 flag.
 200 .It Fl q
 201 Select the first archive member that matches each
 202 .Ar file
 203 operand.
 204 No more than one archive member is matched for each
 205 .Ar file .
 206 When members of type directory are matched, the file hierarchy rooted at that
 207 directory is also matched.
 208 .It Fl s Ar replstr
 209 Modify the archive member names according to the substitution expression
 210 .Ar replstr ,
 211 using the syntax of the
 212 .Xr ed 1
 213 utility regular expressions.
 214 .Ar file
 215 arguments may be given to restrict the list of archive members to those
 216 specified.
 217 .Pp
 218 The format of these regular expressions is
 219 .Pp
 220 .Dl /old/new/[gp]
 221 .Pp
 222 As in
 223 .Xr ed 1 ,
 224 .Va old
 225 is a basic regular expression (see
 226 .Xr re_format 7 )
 227 and
 228 .Va new
 229 can contain an ampersand
 230 .Pq Ql & ,
 231 .Ql \e Ns Em n
 232 (where
 233 .Em n
 234 is a digit) back-references,
 235 or subexpression matching.
 236 The
 237 .Va old
 238 string may also contain newline characters.
 239 Any non-null character can be used as a delimiter
 240 .Po
 241 .Ql /
 242 is shown here
 243 .Pc .
 244 Multiple
 245 .Fl s
 246 expressions can be specified.
 247 The expressions are applied in the order they are specified on the
 248 command line, terminating with the first successful substitution.
 249 .Pp
 250 The optional trailing
 251 .Cm g
 252 continues to apply the substitution expression to the pathname substring,
 253 which starts with the first character following the end of the last successful
 254 substitution.
 255 The first unsuccessful substitution stops the operation of the
 256 .Cm g
 257 option.
 258 The optional trailing
 259 .Cm p
 260 will cause the final result of a successful substitution to be written to
 261 standard error in the following format:
 262 .Pp
 263 .D1 Em original-pathname No >> Em new-pathname
 264 .Pp
 265 File or archive member names that substitute to the empty string
 266 are not selected and will be skipped.
 267 .It Fl v
 268 Verbose operation mode.
 269 .It Fl w
 270 Interactively rename files.
 271 This option causes
 272 .Nm
 273 to prompt the user for the filename to use when storing or
 274 extracting files in an archive.
 275 .It Fl X
 276 Do not cross mount points in the file system.
 277 .It Fl Z
 278 Compress archive using
 279 .Xr compress 1 .
 280 .It Fl z
 281 Compress archive using
 282 .Xr gzip 1 .
 283 .El
 284 .Pp
 285 The options
 286 .Op Fl 014578
 287 can be used to select one of the compiled-in backup devices,
 288 .Pa /dev/rstN .
 289 .Sh ENVIRONMENT
 290 .Bl -tag -width Fl
 291 .It Ev TMPDIR
 292 Path in which to store temporary files.
 293 .It Ev TAPE
 294 Default tape device to use instead of
 295 .Pa /dev/rst0 .
 296 If set to hyphen
 297 .Pq Sq -
 298 standard output is used.
 299 .El
 300 .Sh FILES
 301 .Bl -tag -width "/dev/rst0"
 302 .It Pa /dev/rst0
 303 default archive name
 304 .El
 305 .Sh EXIT STATUS
 306 The
 307 .Nm
 308 utility exits with one of the following values:
 309 .Pp
 310 .Bl -tag -width Ds -offset indent -compact
 311 .It 0
 312 All files were processed successfully.
 313 .It 1
 314 An error occurred.
 315 .El
 316 .Sh EXAMPLES
 317 Create an archive on the default tape drive, containing the files named
 318 .Pa bonvole
 319 and
 320 .Pa sekve :
 321 .Pp
 322 .Dl $ tar c bonvole sekve
 323 .Pp
 324 Output a
 325 .Xr gzip 1
 326 compressed archive containing the files
 327 .Pa bonvole
 328 and
 329 .Pa sekve
 330 to a file called
 331 .Pa foriru.tar.gz :
 332 .Pp
 333 .Dl $ tar zcf foriru.tar.gz bonvole sekve
 334 .Pp
 335 Verbosely create an archive, called
 336 .Pa backup.tar.gz ,
 337 of all files matching the shell
 338 .Xr glob 3
 339 function
 340 .Pa *.c :
 341 .Pp
 342 .Dl $ tar zcvf backup.tar.gz *.c
 343 .Pp
 344 Verbosely list, but do not extract, all files ending in
 345 .Pa .jpeg
 346 from a compressed archive named
 347 .Pa backup.tar.gz .
 348 Note that the glob pattern has been quoted to avoid expansion by the shell:
 349 .Pp
 350 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
 351 .Pp
 352 For more detailed examples, see
 353 .Xr pax 1 .
 354 .Sh DIAGNOSTICS
 355 Whenever
 356 .Nm
 357 cannot create a file or a link when extracting an archive or cannot
 358 find a file while writing an archive, or cannot preserve the user
 359 ID, group ID, file mode, or access and modification times when the
 360 .Fl p
 361 option is specified, a diagnostic message is written to standard
 362 error and a non-zero exit value will be returned, but processing
 363 will continue.
 364 In the case where
 365 .Nm
 366 cannot create a link to a file,
 367 .Nm
 368 will not create a second copy of the file.
 369 .Pp
 370 If the extraction of a file from an archive is prematurely terminated
 371 by a signal or error,
 372 .Nm
 373 may have only partially extracted the file the user wanted.
 374 Additionally, the file modes of extracted files and directories may
 375 have incorrect file bits, and the modification and access times may
 376 be wrong.
 377 .Pp
 378 If the creation of an archive is prematurely terminated by a signal
 379 or error,
 380 .Nm
 381 may have only partially created the archive, which may violate the
 382 specific archive format specification.
 383 .Sh SEE ALSO
 384 .Xr cpio 1 ,
 385 .Xr pax 1
 386 .Sh HISTORY
 387 A
 388 .Nm
 389 command first appeared in
 390 .At v7 .
 391 .Sh AUTHORS
 392 .An Keith Muller
 393 at the University of California, San Diego.
 394 .Sh CAVEATS
 395 The
 396 .Fl j
 397 and
 398 .Fl L
 399 flags are not portable to other versions of
 400 .Nm
 401 where they may have a different meaning.