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