git.gag.com Git - debian/pax/blob - tar.1

   1 .\"     $OpenBSD: tar.1,v 1.50 2008/06/11 00:49:08 pvalchev 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 .\"     $OpenBSD: tar.1,v 1.50 2008/06/11 00:49:08 pvalchev Exp $
  27 .\"
  28 .Dd $Mdocdate: June 11 2008 $
  29 .Dt TAR 1
  30 .Os
  31 .Sh NAME
  32 .Nm tar
  33 .Nd tape archiver
  34 .Sh SYNOPSIS
  35 .Nm tar
  36 .Sm off
  37 .No { Cm crtux No } Op Cm 014578befHhjLmOoPpqsvwXZz
  38 .Sm on
  39 .Bk -words
  40 .Op Ar blocking-factor | archive | replstr
  41 .Op Fl C Ar directory
  42 .Op Fl I Ar file
  43 .Op Ar file ...
  44 .Ek
  45 .Nm tar
  46 .No { Ns Fl crtux Ns }
  47 .Op Fl 014578eHhjLmOoPpqvwXZz
  48 .Op Fl b Ar blocking-factor
  49 .Op Fl C Ar directory
  50 .Op Fl f Ar archive
  51 .Op Fl I Ar file
  52 .Op Fl s Ar replstr
  53 .Op Ar file ...
  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 violate the
 135 .Tn POSIX
 136 standard and will not be portable to all systems.
 137 .It Fl C Ar directory
 138 This is a positional argument which sets the working directory for the
 139 following files.
 140 When extracting, files will be extracted into
 141 the specified directory; when creating, the specified files will be matched
 142 from the directory.
 143 .It Fl e
 144 Stop after the first error.
 145 .It Fl f Ar archive
 146 Filename where the archive is stored.
 147 Defaults to
 148 .Pa /dev/rst0 .
 149 .It Fl H
 150 Follow symlinks given on the command line only.
 151 .It Fl h
 152 Follow symbolic links as if they were normal files
 153 or directories.
 154 In extract mode this means that a directory entry in the archive
 155 will not overwrite an existing symbolic link, but rather what the
 156 link ultimately points to.
 157 .It Fl I Ar file
 158 This is a positional argument which reads the names of files to
 159 archive or extract from the given file, one per line.
 160 .It Fl j
 161 Compress archive using bzip2.
 162 The bzip2 utility must be installed separately.
 163 .It Fl L
 164 Synonym for the
 165 .Fl h
 166 option.
 167 .It Fl m
 168 Do not preserve modification time.
 169 .It Fl O
 170 Write old-style (non-POSIX) archives.
 171 .It Fl o
 172 Don't write directory information that the older (V7) style
 173 .Nm
 174 is unable to decode.
 175 This implies the
 176 .Fl O
 177 flag.
 178 .It Fl P
 179 Do not strip leading slashes
 180 .Pq Sq /
 181 from pathnames.
 182 The default is to strip leading slashes.
 183 .It Fl p
 184 Preserve user and group ID as well as file mode regardless of
 185 the current
 186 .Xr umask 2 .
 187 The setuid and setgid bits are only preserved if the user is
 188 the superuser.
 189 Only meaningful in conjunction with the
 190 .Fl x
 191 flag.
 192 .It Fl q
 193 Select the first archive member that matches each
 194 .Ar file
 195 operand.
 196 No more than one archive member is matched for each
 197 .Ar file .
 198 When members of type directory are matched, the file hierarchy rooted at that
 199 directory is also matched.
 200 .It Fl s Ar replstr
 201 Modify the archive member names according to the substitution expression
 202 .Ar replstr ,
 203 using the syntax of the
 204 .Xr ed 1
 205 utility regular expressions.
 206 .Ar file
 207 arguments may be given to restrict the list of archive members to those
 208 specified.
 209 .Pp
 210 The format of these regular expressions is
 211 .Pp
 212 .Dl /old/new/[gp]
 213 .Pp
 214 As in
 215 .Xr ed 1 ,
 216 .Va old
 217 is a basic regular expression (see
 218 .Xr re_format 7 )
 219 and
 220 .Va new
 221 can contain an ampersand
 222 .Pq Ql & ,
 223 .Ql \e Ns Em n
 224 (where
 225 .Em n
 226 is a digit) back-references,
 227 or subexpression matching.
 228 The
 229 .Va old
 230 string may also contain newline characters.
 231 Any non-null character can be used as a delimiter
 232 .Po
 233 .Ql /
 234 is shown here
 235 .Pc .
 236 Multiple
 237 .Fl s
 238 expressions can be specified.
 239 The expressions are applied in the order they are specified on the
 240 command line, terminating with the first successful substitution.
 241 .Pp
 242 The optional trailing
 243 .Cm g
 244 continues to apply the substitution expression to the pathname substring,
 245 which starts with the first character following the end of the last successful
 246 substitution.
 247 The first unsuccessful substitution stops the operation of the
 248 .Cm g
 249 option.
 250 The optional trailing
 251 .Cm p
 252 will cause the final result of a successful substitution to be written to
 253 standard error in the following format:
 254 .Pp
 255 .D1 Em original-pathname No >> Em new-pathname
 256 .Pp
 257 File or archive member names that substitute to the empty string
 258 are not selected and will be skipped.
 259 .It Fl v
 260 Verbose operation mode.
 261 .It Fl w
 262 Interactively rename files.
 263 This option causes
 264 .Nm
 265 to prompt the user for the filename to use when storing or
 266 extracting files in an archive.
 267 .It Fl X
 268 Do not cross mount points in the file system.
 269 .It Fl Z
 270 Compress archive using
 271 .Xr compress 1 .
 272 .It Fl z
 273 Compress archive using
 274 .Xr gzip 1 .
 275 .El
 276 .Pp
 277 The options
 278 .Op Fl 014578
 279 can be used to select one of the compiled-in backup devices,
 280 .Pa /dev/rstN .
 281 .Sh ENVIRONMENT
 282 .Bl -tag -width Fl
 283 .It Ev TMPDIR
 284 Path in which to store temporary files.
 285 .It Ev TAPE
 286 Default tape device to use instead of
 287 .Pa /dev/rst0 .
 288 .El
 289 .Sh FILES
 290 .Bl -tag -width "/dev/rst0"
 291 .It Pa /dev/rst0
 292 default archive name
 293 .El
 294 .Sh EXAMPLES
 295 Create an archive on the default tape drive, containing the files named
 296 .Pa bonvole
 297 and
 298 .Pa sekve :
 299 .Pp
 300 .Dl $ tar c bonvole sekve
 301 .Pp
 302 Output a
 303 .Xr gzip 1
 304 compressed archive containing the files
 305 .Pa bonvole
 306 and
 307 .Pa sekve
 308 to a file called
 309 .Pa foriru.tar.gz :
 310 .Pp
 311 .Dl $ tar zcf foriru.tar.gz bonvole sekve
 312 .Pp
 313 Verbosely create an archive, called
 314 .Pa backup.tar.gz ,
 315 of all files matching the shell
 316 .Xr glob 3
 317 function
 318 .Pa *.c :
 319 .Pp
 320 .Dl $ tar zcvf backup.tar.gz *.c
 321 .Pp
 322 Verbosely list, but do not extract, all files ending in
 323 .Pa .jpeg
 324 from a compressed archive named
 325 .Pa backup.tar.gz .
 326 Note that the glob pattern has been quoted to avoid expansion by the shell:
 327 .Pp
 328 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
 329 .Pp
 330 For more detailed examples, see
 331 .Xr pax 1 .
 332 .Sh DIAGNOSTICS
 333 .Nm
 334 will exit with one of the following values:
 335 .Bl -tag -width 2n -offset indent
 336 .It 0
 337 All files were processed successfully.
 338 .It 1
 339 An error occurred.
 340 .El
 341 .Pp
 342 Whenever
 343 .Nm
 344 cannot create a file or a link when extracting an archive or cannot
 345 find a file while writing an archive, or cannot preserve the user
 346 ID, group ID, file mode, or access and modification times when the
 347 .Fl p
 348 option is specified, a diagnostic message is written to standard
 349 error and a non-zero exit value will be returned, but processing
 350 will continue.
 351 In the case where
 352 .Nm
 353 cannot create a link to a file,
 354 .Nm
 355 will not create a second copy of the file.
 356 .Pp
 357 If the extraction of a file from an archive is prematurely terminated
 358 by a signal or error,
 359 .Nm
 360 may have only partially extracted the file the user wanted.
 361 Additionally, the file modes of extracted files and directories may
 362 have incorrect file bits, and the modification and access times may
 363 be wrong.
 364 .Pp
 365 If the creation of an archive is prematurely terminated by a signal
 366 or error,
 367 .Nm
 368 may have only partially created the archive, which may violate the
 369 specific archive format specification.
 370 .Sh SEE ALSO
 371 .Xr cpio 1 ,
 372 .Xr pax 1
 373 .Sh HISTORY
 374 A
 375 .Nm
 376 command first appeared in
 377 .At v7 .
 378 .Sh AUTHORS
 379 Keith Muller at the University of California, San Diego.
 380 .Sh CAVEATS
 381 The
 382 .Fl j
 383 and
 384 .Fl L
 385 flags are not portable to other versions of
 386 .Nm
 387 where they may have a different meaning.