bin/pax/tar.1

   1 .\"-
   2 .\" Copyright (c) 1996 SigmaSoft, Th. Lockert
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"      This product includes software developed by SigmaSoft, Th. Lockert.
  16 .\" 4. The name of the author may not be used to endorse or promote products
  17 .\"    derived from this software without specific prior written permission
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\"     $OpenBSD: tar.1,v 1.33 2001/05/01 17:58:01 aaron Exp $
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd February 7, 2001
  34 .Dt TAR 1
  35 .Os
  36 .Sh NAME
  37 .Nm tar
  38 .Nd tape archiver
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Sm off
  42 .Op Fl
  43 .Brq Cm crtux
  44 .Op Cm befhjmopqsvwyzHLOPXZ014578
  45 .Sm on
  46 .Op Ar blocksize
  47 .Op Ar archive
  48 .Op Ar replstr
  49 .\" XXX how to do this right?
  50 .Op Fl C Ar directory
  51 .Op Fl I Ar file
  52 .Op Ar
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 command creates, adds files to, or extracts files from an
  57 archive file in
  58 .Nm
  59 format.
  60 A
  61 .Nm
  62 archive is often stored on a magnetic tape, but can be
  63 stored equally well on a floppy, CD-ROM, or in a regular disk file.
  64 .Pp
  65 One of the following flags must be present:
  66 .Bl -tag -width indent
  67 .It Fl c
  68 Create new archive, or overwrite an existing archive,
  69 adding the specified files to it.
  70 .It Fl r
  71 Append the named new files to existing archive.
  72 Note that this will only work on media on which an end-of-file mark
  73 can be overwritten.
  74 .It Fl t
  75 List contents of archive.
  76 If any files are named on the
  77 command line, only those files will be listed.
  78 .It Fl u
  79 Alias for
  80 .Fl r .
  81 .It Fl x
  82 Extract files from archive.
  83 If any files are named on the
  84 command line, only those files will be extracted from the
  85 archive.
  86 If more than one copy of a file exists in the
  87 archive, later copies will overwrite earlier copies during
  88 extraction.
  89 The file mode and modification time are preserved
  90 if possible.
  91 The file mode is subject to modification by the
  92 .Xr umask 2 .
  93 .El
  94 .Pp
  95 In addition to the flags mentioned above, any of the following
  96 flags may be used:
  97 .Bl -tag -width indent
  98 .It Fl b Ar "blocking factor"
  99 Set blocking factor to use for the archive, with 512 byte blocks.
 100 The default is 20, the maximum is 126.
 101 Archives with a blocking factor larger 63 violate the
 102 .Tn POSIX
 103 standard and will not be portable to all systems.
 104 .It Fl e
 105 Stop after first error.
 106 .It Fl f Ar archive
 107 Filename where the archive is stored.
 108 Defaults to
 109 .Pa /dev/sa0 .
 110 .It Fl h
 111 Follow symbolic links as if they were normal files
 112 or directories.
 113 .It Fl j
 114 Compress archives using
 115 .Xr bzip2 1 .
 116 .It Fl m
 117 Do not preserve modification time.
 118 .It Fl O
 119 Write old-style
 120 .Pq non- Ns Tn POSIX
 121 archives.
 122 .It Fl o
 123 Do not write directory information that the older (V7) style
 124 .Nm
 125 is unable to decode.
 126 This implies the
 127 .Fl O
 128 flag.
 129 .It Fl p
 130 Preserve user and group ID as well as file mode regardless of
 131 the current
 132 .Xr umask 2 .
 133 The setuid and setgid bits are only preserved if the user is
 134 the superuser.
 135 Only meaningful in conjunction with the
 136 .Fl x
 137 flag.
 138 .It Fl q
 139 Select the first archive member that matches each
 140 .Ar pattern
 141 operand.
 142 No more than one archive member is matched for each
 143 .Ar pattern .
 144 When members of type directory are matched, the file hierarchy rooted at that
 145 directory is also matched.
 146 .It Fl s Ar replstr
 147 Modify the file or archive member names specified by the
 148 .Ar pattern
 149 or
 150 .Ar file
 151 operands according to the substitution expression
 152 .Ar replstr ,
 153 using the syntax of the
 154 .Xr ed 1
 155 utility regular expressions.
 156 The format of these regular expressions are:
 157 .Dl /old/new/[gp]
 158 As in
 159 .Xr ed 1 ,
 160 .Cm old
 161 is a basic regular expression and
 162 .Cm new
 163 can contain an ampersand
 164 .Pq Ql & ,
 165 .Li \e Ns Ar n
 166 (where
 167 .Ar n
 168 is a digit) back-references,
 169 or subexpression matching.
 170 The
 171 .Cm old
 172 string may also contain newline characters.
 173 Any non-null character can be used as a delimiter
 174 .Ql ( /
 175 is shown here).
 176 Multiple
 177 .Fl s
 178 expressions can be specified.
 179 The expressions are applied in the order they are specified on the
 180 command line, terminating with the first successful substitution.
 181 The optional trailing
 182 .Cm g
 183 continues to apply the substitution expression to the pathname substring
 184 which starts with the first character following the end of the last successful
 185 substitution.
 186 The first unsuccessful substitution stops the operation of the
 187 .Cm g
 188 option.
 189 The optional trailing
 190 .Cm p
 191 will cause the final result of a successful substitution to be written to
 192 standard error
 193 in the following format:
 194 .Pp
 195 .Dl <original pathname> >> <new pathname>
 196 .Pp
 197 File or archive member names that substitute to the empty string
 198 are not selected and will be skipped.
 199 .It Fl v
 200 Verbose operation mode.
 201 .It Fl w
 202 Interactively rename files.
 203 This option causes
 204 .Nm
 205 to prompt the user for the filename to use when storing or
 206 extracting files in an archive.
 207 .It Fl y
 208 Compress archives using
 209 .Xr bzip2 1 .
 210 .It Fl z
 211 Compress archive using
 212 .Xr gzip 1 .
 213 .It Fl C Ar directory
 214 This is a positional argument which sets the working directory for the
 215 following files.
 216 When extracting, files will be extracted into
 217 the specified directory; when creating, the specified files will be matched
 218 from the directory.
 219 .It Fl H
 220 Follow symlinks given on command line only.
 221 .It Fl L
 222 Follow all symlinks.
 223 .It Fl P
 224 Do not strip leading slashes
 225 .Pq Ql /
 226 from pathnames.
 227 The default is to strip leading slashes.
 228 .It Fl I Ar file
 229 This is a positional argument which reads the names of files to
 230 archive or extract from the given file, one per line.
 231 .It Fl X
 232 Do not cross mount points in the file system.
 233 .It Fl Z
 234 Compress archive using
 235 .Xr compress 1 .
 236 .El
 237 .Pp
 238 The options
 239 .Op Fl 014578
 240 can be used to select one of the compiled-in backup devices,
 241 .Pa /dev/rst Ns Ar N .
 242 .Sh ENVIRONMENT
 243 .Bl -tag -width TMPDIR
 244 .It Ev TMPDIR
 245 Path in which to store temporary files.
 246 .It Ev TAPE
 247 Default tape device to use instead of
 248 .Pa /dev/sa0 .
 249 .El
 250 .Sh FILES
 251 .Bl -tag -width "/dev/sa0"
 252 .It Pa /dev/sa0
 253 default archive name
 254 .El
 255 .Sh EXIT STATUS
 256 The
 257 .Nm
 258 utility will exit with one of the following values:
 259 .Bl -tag -width 2n
 260 .It 0
 261 All files were processed successfully.
 262 .It 1
 263 An error occurred.
 264 .El
 265 .Pp
 266 Whenever
 267 .Nm
 268 cannot create a file or a link when extracting an archive or cannot
 269 find a file while writing an archive, or cannot preserve the user
 270 ID, group ID, file mode, or access and modification times when the
 271 .Fl p
 272 option is specified, a diagnostic message is written to standard
 273 error and a non-zero exit value will be returned, but processing
 274 will continue.
 275 In the case where
 276 .Nm
 277 cannot create a link to a file,
 278 .Nm
 279 will not create a second copy of the file.
 280 .Pp
 281 If the extraction of a file from an archive is prematurely terminated
 282 by a signal or error,
 283 .Nm
 284 may have only partially extracted the file the user wanted.
 285 Additionally, the file modes of extracted files and directories may
 286 have incorrect file bits, and the modification and access times may
 287 be wrong.
 288 .Pp
 289 If the creation of an archive is prematurely terminated by a signal
 290 or error,
 291 .Nm
 292 may have only partially created the archive which may violate the
 293 specific archive format specification.
 294 .Sh COMPATIBILITY
 295 The
 296 .Fl L
 297 flag is not portable to other versions of
 298 .Nm
 299 where it may have a different meaning.
 300 .Sh SEE ALSO
 301 .Xr cpio 1 ,
 302 .Xr pax 1
 303 .Sh HISTORY
 304 A
 305 .Nm
 306 command first appeared in
 307 .At v7 .
 308 .Sh AUTHORS
 309 .An Keith Muller
 310 at the University of California, San Diego.