1.\" $NetBSD: tar.1,v 1.35 2015/04/11 16:22:07 wiz 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.28 2000/11/09 23:58:56 aaron Exp 27.\" 28.Dd April 11, 2015 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.Oo \&- Oc {crtux} Op Fl 014578befHhJjklmOoPpqSvwXZz 38.Sm on 39.Op Ar archive 40.Op Ar blocksize 41.\" XXX how to do this right? 42.Op Fl C Ar directory 43.Op Fl s Ar replstr 44.Op Fl T Ar file 45.Op Ar file ... 46.Sh DESCRIPTION 47The 48.Nm 49command creates, adds files to, or extracts files from an 50archive file in 51.Dq tar 52format. 53A tar archive is often stored on a magnetic tape, but can be 54stored equally well on a floppy, CD-ROM, or in a regular disk file. 55.Pp 56One of the following flags must be present: 57.Bl -tag -width Ar 58.It Fl c , Fl Fl create 59Create new archive, or overwrite an existing archive, 60adding the specified files to it. 61.It Fl r , Fl Fl append 62Append the named new files to existing archive. 63Note that this will only work on media on which an end-of-file mark 64can be overwritten. 65.It Fl t , Fl Fl list 66List contents of archive. 67If any files are named on the 68command line, only those files will be listed. 69.It Fl u , Fl Fl update 70Alias for 71.Fl r . 72.It Fl x , Fl Fl extract , Fl Fl get 73Extract files from archive. 74If any files are named on the 75command line, only those files will be extracted from the 76archive. 77If more than one copy of a file exists in the 78archive, later copies will overwrite earlier copies during 79extraction. 80The file mode and modification time are preserved 81if possible. 82The file mode is subject to modification by the 83.Xr umask 2 . 84.El 85.Pp 86In addition to the flags mentioned above, any of the following 87flags may be used: 88.Bl -tag -width Ar 89.It Fl b Ar "blocking factor" , Fl Fl block-size Ar "blocking factor" 90Set blocking factor to use for the archive. 91.Nm 92uses 512 byte blocks. 93The default is 20, the maximum is 126. 94Archives with a blocking factor larger 63 violate the 95.Tn POSIX 96standard and will not be portable to all systems. 97.It Fl e 98Stop after first error. 99.It Fl f Ar archive , Fl Fl file Ar archive 100Filename where the archive is stored. 101Defaults to 102.Pa /dev/rst0 . 103If the archive is of the form: 104.Ar [[user@]host:]file 105then the archive will be processed using 106.Xr rmt 8 . 107.It Fl h , Fl Fl dereference 108Follow symbolic links as if they were normal files 109or directories. 110.It Fl J, Fl Fl xz 111Compress/decompress archive using 112.Xr xz 1 . 113.It Fl j, Fl Fl bzip2, Fl Fl bunzip2 114Use 115.Xr bzip2 1 116for compression of the archive. 117This option is a GNU extension. 118.It Fl k , Fl Fl keep-old-files 119Keep existing files; don't overwrite them from archive. 120.It Fl l , Fl Fl one-file-system 121Do not descend across mount points. 122.\" should be '-X' 123.It Fl m , Fl Fl modification-time 124Do not preserve modification time. 125.It Fl O 126When creating and appending to an archive, write old-style (non-POSIX) archives. 127When extracting from an archive, extract to standard output. 128.It Fl o , Fl Fl portability , Fl Fl old-archive 129Don't write directory information that the older (V7) style 130.Nm 131is unable to decode. 132This implies the 133.Fl O 134flag. 135.It Fl p , Fl Fl preserve-permissions , Fl Fl preserve 136Preserve user and group ID as well as file mode regardless of 137the current 138.Xr umask 2 . 139The setuid and setgid bits are only preserved if the user is 140the superuser. 141Only meaningful in conjunction with the 142.Fl x 143flag. 144.It Fl q , Fl Fl fast-read 145Select the first archive member that matches each 146.Ar pattern 147operand. 148No more than one archive member is matched for each 149.Ar pattern . 150When members of type directory are matched, the file hierarchy rooted at that 151directory is also matched. 152.It Fl S , Fl Fl sparse 153This flag has no effect as 154.Nm 155always generates sparse files. 156.It Fl s Ar replstr 157Modify the file or archive member names specified by the 158.Ar pattern 159or 160.Ar file 161operands according to the substitution expression 162.Ar replstr , 163using the syntax of the 164.Xr ed 1 165utility regular expressions. 166The format of these regular expressions are: 167.Dl /old/new/[gps] 168As in 169.Xr ed 1 , 170.Cm old 171is a basic regular expression and 172.Cm new 173can contain an ampersand (\*[Am]), \en (where n is a digit) back-references, 174or subexpression matching. 175The 176.Cm old 177string may also contain 178.Aq Dv newline 179characters. 180Any non-null character can be used as a delimiter (/ is shown here). 181Multiple 182.Fl s 183expressions can be specified. 184The expressions are applied in the order they are specified on the 185command line, terminating with the first successful substitution. 186The optional trailing 187.Cm g 188continues to apply the substitution expression to the pathname substring 189which starts with the first character following the end of the last successful 190substitution. 191The first unsuccessful substitution stops the operation of the 192.Cm g 193option. 194The optional trailing 195.Cm p 196will cause the final result of a successful substitution to be written to 197.Dv standard error 198in the following format: 199.Dl \*[Lt]original pathname\*[Gt] \*[Gt]\*[Gt] \*[Lt]new pathname\*[Gt] 200File or archive member names that substitute to the empty string 201are not selected and will be skipped. 202The substitutions are applied by default to the destination hard and symbolic 203links. 204The optional trailing 205.Cm s 206prevents the substitutions from being performed on symbolic link destinations. 207.It Fl v 208Verbose operation mode. 209.It Fl w , Fl Fl interactive , Fl Fl confirmation 210Interactively rename files. 211This option causes 212.Nm 213to prompt the user for the filename to use when storing or 214extracting files in an archive. 215.It Fl z , Fl Fl gzip , Fl Fl gunzip 216Compress/decompress archive using 217.Xr gzip 1 . 218.It Fl B , Fl Fl read-full-blocks 219Reassemble small reads into full blocks (For reading from 4.2BSD pipes). 220.It Fl C Ar directory , Fl Fl directory Ar directory 221This is a positional argument which sets the working directory for the 222following files. 223When extracting, files will be extracted into 224the specified directory; when creating, the specified files will be matched 225from the directory. 226This argument and its parameter may also appear in a file list specified by 227.Fl T . 228.It Fl H 229Only follow symlinks given on command line. 230.Pp 231Note SysVr3/i386 picked up ISC/SCO UNIX compatibility which implemented 232.Dq Fl F Ar file 233which was defined as obtaining a list of command line switches and files 234on which to operate from the specified file, 235but SunOS-5 uses 236.Dq Fl I Ar file 237because they use 238.Sq Fl F 239to mean something else. 240We might someday provide SunOS-5 compatibility 241but it makes little sense to confuse things with ISC/SCO compatibility. 242.\".It Fl L 243.\"Do not follow any symlinks (do the opposite of 244.\".Fl h ). 245.It Fl P , Fl Fl absolute-paths 246Do not strip leading slashes 247.Pq Sq / 248from pathnames. 249The default is to strip leading slashes. 250.It Fl T Ar file , Fl Fl files-from Ar file 251Read the names of files to archive or extract from the given file, one 252per line. 253A line may also specify the positional argument 254.Dq Fl C Ar directory . 255.It Fl X Ar file , Fl Fl exclude-from Ar file 256Exclude files matching the shell glob patterns listed in the given file. 257.\" exclude should be '-E' and '-X' should be one-file-system 258.Pp 259Note that it would be more standard to use this option to mean ``do not 260cross filesystem mount points.'' 261.It Fl Z , Fl Fl compress , Fl Fl uncompress 262Compress archive using compress. 263.It Fl Fl strict 264Do not enable GNU tar extensions such as long filenames and long link names. 265.It Fl Fl atime-preserve 266Preserve file access times. 267.It Fl Fl chroot 268.Fn chroot 269to the current directory before extracting files. 270Use with 271.Fl x 272and 273.Fl h 274to make absolute symlinks relative to the current directory. 275.It Fl Fl unlink 276Ignored, only accepted for compatibility with other 277.Nm 278implementations. 279.Nm 280always unlinks files before creating them. 281.It Fl Fl use-compress-program Ar program 282Use the named program as the program to decompress the input. 283.It Fl Fl force-local 284Do not interpret filenames that contain a 285.Sq \&: 286as remote files. 287.It Fl Fl insecure 288Normally 289.Nm 290ignores filenames that contain 291.Dq .. 292as a path component. 293With this option, files that contain 294.Dq .. 295can be processed. 296.It Fl Fl no-recursion 297Cause files of type directory being copied or archived, or archive members of 298type directory being extracted, to match only the directory file or archive 299member and not the file hierarchy rooted at the directory. 300.El 301.Pp 302The options 303.Op Fl 014578 304can be used to select one of the compiled-in backup devices, 305.Pa /dev/rstN . 306.Sh FILES 307.Bl -tag -width "/dev/rst0" 308.It Pa /dev/rst0 309default archive name 310.El 311.Sh DIAGNOSTICS 312.Nm 313will exit with one of the following values: 314.Bl -tag -width 2n 315.It 0 316All files were processed successfully. 317.It 1 318An error occurred. 319.El 320.Pp 321Whenever 322.Nm 323cannot create a file or a link when extracting an archive or cannot 324find a file while writing an archive, or cannot preserve the user 325ID, group ID, file mode, or access and modification times when the 326.Fl p 327option is specified, a diagnostic message is written to standard 328error and a non-zero exit value will be returned, but processing 329will continue. 330In the case where 331.Nm 332cannot create a link to a file, 333.Nm 334will not create a second copy of the file. 335.Pp 336If the extraction of a file from an archive is prematurely terminated 337by a signal or error, 338.Nm 339may have only partially extracted the file the user wanted. 340Additionally, the file modes of extracted files and directories may 341have incorrect file bits, and the modification and access times may 342be wrong. 343.Pp 344If the creation of an archive is prematurely terminated by a signal 345or error, 346.Nm 347may have only partially created the archive which may violate the 348specific archive format specification. 349.Sh SEE ALSO 350.Xr cpio 1 , 351.Xr pax 1 352.Sh HISTORY 353A 354.Nm 355command first appeared in 356.At v7 . 357.Sh AUTHORS 358.An Keith Muller 359at the University of California, San Diego. 360