1.\" $OpenBSD: tar.1,v 1.35 2001/10/25 16:59:03 niklas 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.35 2001/10/25 16:59:03 niklas Exp $ 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 tar 41.Sm off 42.Oo \&- Oc {crtux} Op befhmopqsvwzHLOPXZ014578 43.Sm on 44.Op Ar blocksize 45.Op Ar archive 46.Op Ar replstr 47.\" XXX how to do this right? 48.Op Fl C Ar directory 49.Op Fl I Ar file 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 64Create new archive, or overwrite an existing archive, 65adding the specified files to it. 66.It Fl r 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 71List contents of archive. 72If any files are named on the 73command line, only those files will be listed. 74.It Fl u 75Alias for 76.Fl r . 77.It Fl x 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" 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 105Filename where the archive is stored. 106Defaults to 107.Pa /dev/rst0 . 108.It Fl h 109Follow symbolic links as if they were normal files 110or directories. 111In extract mode this means that a directory entry in the archive 112will not overwrite an existing symbolic link, but rather what the 113link ultimately points to. 114.It Fl m 115Do not preserve modification time. 116.It Fl O 117Write old-style (non-POSIX) archives. 118.It Fl o 119Don't write directory information that the older (V7) style 120.Nm 121is unable to decode. 122This implies the 123.Fl O 124flag. 125.It Fl p 126Preserve user and group ID as well as file mode regardless of 127the current 128.Xr umask 2 . 129The setuid and setgid bits are only preserved if the user is 130the superuser. 131Only meaningful in conjunction with the 132.Fl x 133flag. 134.It Fl q 135Select the first archive member that matches each 136.Ar pattern 137operand. 138No more than one archive member is matched for each 139.Ar pattern . 140When members of type directory are matched, the file hierarchy rooted at that 141directory is also matched. 142.It Fl s Ar replstr 143Modify the file or archive member names specified by the 144.Ar pattern 145or 146.Ar file 147operands according to the substitution expression 148.Ar replstr , 149using the syntax of the 150.Xr ed 1 151utility regular expressions. 152The format of these regular expressions are: 153.Dl /old/new/[gp] 154As in 155.Xr ed 1 , 156.Cm old 157is a basic regular expression and 158.Cm new 159can contain an ampersand (&), \\n (where n is a digit) back-references, 160or subexpression matching. 161The 162.Cm old 163string may also contain 164.Dv <newline> 165characters. 166Any non-null character can be used as a delimiter (/ is shown here). 167Multiple 168.Fl s 169expressions can be specified. 170The expressions are applied in the order they are specified on the 171command line, terminating with the first successful substitution. 172The optional trailing 173.Cm g 174continues to apply the substitution expression to the pathname substring 175which starts with the first character following the end of the last successful 176substitution. 177The first unsuccessful substitution stops the operation of the 178.Cm g 179option. 180The optional trailing 181.Cm p 182will cause the final result of a successful substitution to be written to 183.Dv standard error 184in the following format: 185.Dl <original pathname> >> <new pathname> 186File or archive member names that substitute to the empty string 187are not selected and will be skipped. 188.It Fl v 189Verbose operation mode. 190.It Fl w 191Interactively rename files. 192This option causes 193.Nm 194to prompt the user for the filename to use when storing or 195extracting files in an archive. 196.It Fl z 197Compress archive using gzip. 198.It Fl C Ar directory 199This is a positional argument which sets the working directory for the 200following files. 201When extracting, files will be extracted into 202the specified directory; when creating, the specified files will be matched 203from the directory. 204.It Fl H 205Follow symlinks given on command line only. 206.It Fl L 207Follow all symlinks. 208In extract mode this means that a directory entry in the archive 209will not overwrite an existing symbolic link, but rather what the 210link ultimately points to. 211.It Fl P 212Do not strip leading slashes 213.Pq Sq / 214from pathnames. 215The default is to strip leading slashes. 216.It Fl I Ar file 217This is a positional argument which reads the names of files to 218archive or extract from the given file, one per line. 219.It Fl X 220Do not cross mount points in the file system. 221.It Fl Z 222Compress archive using compress. 223.El 224.Pp 225The options 226.Op Fl 014578 227can be used to select one of the compiled-in backup devices, 228.Pa /dev/rstN . 229.Sh DIAGNOSTICS 230.Nm 231will exit with one of the following values: 232.Bl -tag -width 2n 233.It 0 234All files were processed successfully. 235.It 1 236An error occurred. 237.El 238.Pp 239Whenever 240.Nm 241cannot create a file or a link when extracting an archive or cannot 242find a file while writing an archive, or cannot preserve the user 243ID, group ID, file mode, or access and modification times when the 244.Fl p 245option is specified, a diagnostic message is written to standard 246error and a non-zero exit value will be returned, but processing 247will continue. 248In the case where 249.Nm 250cannot create a link to a file, 251.Nm 252will not create a second copy of the file. 253.Pp 254If the extraction of a file from an archive is prematurely terminated 255by a signal or error, 256.Nm 257may have only partially extracted the file the user wanted. 258Additionally, the file modes of extracted files and directories may 259have incorrect file bits, and the modification and access times may 260be wrong. 261.Pp 262If the creation of an archive is prematurely terminated by a signal 263or error, 264.Nm 265may have only partially created the archive which may violate the 266specific archive format specification. 267.Sh FILES 268.Bl -tag -width "/dev/rst0" 269.It Pa /dev/rst0 270default archive name 271.El 272.Sh ENVIRONMENT 273.Bl -tag -width Fl 274.It Ev TMPDIR 275Path in which to store temporary files. 276.It Ev TAPE 277Default tape device to use instead of 278.Pa /dev/rst0 . 279.El 280.Sh SEE ALSO 281.Xr cpio 1 , 282.Xr pax 1 283.Sh AUTHORS 284Keith Muller at the University of California, San Diego. 285.Sh HISTORY 286A 287.Nm 288command first appeared in 289.At v7 . 290.Sh CAVEATS 291The 292.Fl L 293flag is not portable to other versions of 294.Nm 295where it may have a different meaning. 296