.\" @(#)tar.1 1.43 96/02/20 SMI;
.\" Copyright 1989 AT&T
.\" Copyright (c) 1996, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Portions Copyright (c) 1992, X/Open Company Limited
.\" All Rights Reserved
.TH tar 1 "20 Feb 1996"
.SH NAME
tar \- create tape archives and add or extract files
.SH SYNOPSIS
.BR "tar c "[ "bBefFhiloPvwX" " [ " 0-7 " ]]"
[
.I block
] [
.I tarfile
]
.if n .ti +5n
[
.I exclude-file 
]
.if t .ti +5n
{
.BI \-I " include-file"
|
.if n .ti +5n
.BI "\-C " "directory file"
|
.I file
} \|.\|.\|. 
.LP
.BR "tar r "[ " bBefFhilvw"
.RB [ " 0-7 " ]]
[
.I block
]
.if t .ti +5n
.if n .ti +5n
{
.BI \-I " include-file"
|
.BI "\-C " "directory file"
|
.I file
} \|.\|.\|. 
.LP
.BR "tar t "[ " BefFhilvX"
.RB [ " 0-7 " ]]
[
.I tarfile
]
.if n .ti +5n
[
.I exclude-file 
]
{
.BI \-I " include-file"
|
.I file 
} .\|.\|. 
.LP
.BR "tar u "[ " bBefFhilvw"
.RB [ " 0-7 " ]]
[
.I block
] [
.I tarfile
]
.IR file " .\|.\|."
.LP
.BR "tar x "[ " BefFhilmopvwX"
.RB [ " 0-7 " ]]
[
.I tarfile
]
.if n .ti +5n
[
.I exclude-file
] [
.IR file " .\|.\|. ]"
.SH AVAILABILITY
SUNWcsu
.SH DESCRIPTION
.IX "tar command" "" "\fLtar\fP \(em create tape archives, and add or extract files"
.IX "archives" "create tape archives, and add or extract files" "" "create tape archives, and add or extract files \(em \fLtar\fP"
.IX "tape archives" "create" "" "create \(em \fLtar\fP"
The
.B tar
command archives and extracts files to and from a single file called a
.IR tarfile .
A tarfile is usually a magnetic tape, but it can be any file.
.BR tar 's
actions are controlled by the
.I key
argument.
The
.I key
is a string of characters containing
exactly one function letter
.RB ( c ", " r ", " t
.RB ", " u ", or " x )
and zero or more function modifiers
(letters or digits),
depending on the function letter used.
The
.I key
string contains
no
.SM SPACE
characters. 
Function modifier arguments are listed on the command line
in the same order as their corresponding function modifiers
appear in the
.I key
string.
.LP
The
.BI \-I " include-file"\f1,
.BI "\-C " "directory file"\f1,
and
.I file
arguments
specify which files or directories are to be archived or extracted.
In all cases, appearance of a directory name refers to
the files and (recursively) subdirectories of that directory.
Arguments appearing within braces
.RB ( { \| } )
indicate that one of the arguments must be specified.
.SH OPTIONS
The following options are supported:
.TP 
.BI \-I " include-file"
Open
.I include-file
containing a list of files, one per line, and treat
as if each file appeared separately on the command line.
Be careful of trailing white spaces.
In the case where excluded files (see
.B X
function modifier)
are also specified, they take
precedence over all included files.
If a file is specified in both the
.I exclude-file
and the
.I include-file
(or on the command line),
it will be excluded.
.TP 
.BI \-C " directory file"
Perform a
.B chdir
(see
.BR cd (1))
operation on
.I directory
and perform the
.B c
(create) or
.B r
(replace) operation on
.IR file .
Use short relative path names for
.IR file .
If
.I file
is
.RB ` . ',
archive all files in
.IR directory .
This option enables archiving files from multiple directories not
related by a close common parent.
.SH OPERANDS
The following operands are supported:
.TP
.I file
A path name of a regular file or directory to be archived
(when the
.BR c ,
.B r
or
.B u
functions are specified),
extracted
.RB ( x )
or listed
.RB ( t ).
When
.I file
is the path name of a directory, the action applies to
all of the files and (recursively) subdirectories of that directory.
The directory portion of
.I file
(see
.BR dirname (1))
cannot exceed 155 characters.
The file name portion
(see
.BR basename (1))
cannot exceed 100 characters.
.SS "Function Letters"
.LP
The function portion of the key is specified by one of the
following letters:
.TP
.B c
Create. Writing begins at the beginning of the tarfile,
instead of at the end.
.TP
.B r
Replace.  The named
.IR file s
are written
at the end of the tarfile.
.TP
.B t
Table of Contents.
The names of the specified files
are listed each time they occur in the tarfile.  If no
.I file
argument is given, the names of all files in the tarfile
are listed.  With the
.B v
function modifier, additional information for the specified
files is displayed.
.TP
.B u
Update.  The named
.IR file s
are written at the end of the tarfile if they
are not already in the tarfile, or if they have
been modified since last written to that tarfile.
An update can be rather slow.
A tarfile created on a 5.x system cannot be updated
on a 4.x system.
.TP
.B x
Extract or restore.  The named
.IR file s
are extracted from the tarfile and written to the 
directory specified in the tarfile, relative to the
current directory.
Use the relative path names of files and directories to be extracted.
If a named file matches a directory whose contents
has been written to the tarfile, this directory is recursively extracted.
The owner, modification time, and mode are restored (if possible); otherwise,
to restore owner, you must be the super-user. 
Character-special and block-special devices (created by 
.BR mknod (1M))
can only be extracted by the super-user.
If no
.I file 
argument is given, the entire content of the
tarfile is extracted.
If the tarfile contains several files with the same name,
each file is written to the appropriate directory, overwriting
the previous one.  
Filename substitution wildcards cannot be used for extracting files
from the archive; rather, use a command of the form:
.LP
.RS 13
.ft 3
tar xvf... /dev/rmt/0 \(gatar tf... /dev/rmt/0 | grep '\f2pattern\f1\f3'\|\(ga\f1
.ft 1
.RE
.LP
When extracting tapes created with the
.BR r " or " u
functions, directory modification times may not be set correctly.
These same functions cannot be used with many tape drives due to 
tape drive limitations such as the absence of backspace or append capabilities.
.LP
When using the
.BR r ", "  u ,
or
.B x
functions or the
.B X
function modifier,
the named files must match exactly the corresponding
files in the
.IR tarfile .
For example, to extract
.BI ./ thisfile\f1,
you must specify
.BI ./ thisfile\f1,
and not
.IR thisfile .
The \f3t\f1 function displays how each file was archived.
.SS "Function Modifiers"
.LP
The characters below may be used in conjunction with the letter
that selects the desired function.
.TP 
.B b
Blocking Factor.
Use when reading or writing to raw magnetic archives (see
.B f
below).
The \f2block\f1 argument specifies the number of 512-byte
tape blocks to be included in each read or write operation performed
on the tarfile.
The minimum is
.BR 1 ,
the default is
.BR 20 .
The maximum value is a function of the amount of memory available and
the blocking requirements of the specific tape device involved
(see
.BR mtio (7I)
for details.)
.sp 1n
When a tape archive is being read, its actual blocking factor
will be automatically detected, provided that it is less than or
equal to the nominal blocking factor (the value of the
.I block 
argument, or the default value if the
.B b
modifier is not specified).  If the actual blocking factor is greater
than the nominal blocking factor, a read error will result.
See Example 5 in
.B EXAMPLES
below.
.sp 1n
The automatic determination of the actual blocking factor may be fooled
when reading from a pipe or a socket (see the
.B B
function modifier below).
.sp 1n
1/4" streaming tape has an inherent blocking factor of one
512-byte block.  It can be read or written using any blocking factor.
.sp 1n
This function modifier works for archives on disk files and block
special devices, among others, but is intended principally for
tape devices.
.TP
.B B
Block.  Force
.B tar
to perform multiple reads (if necessary) to
read exactly enough bytes to fill a block.
This function modifier enables
.B tar
to work across the Ethernet, since pipes and sockets return
partial blocks even when more data is coming.
When reading from standard input, '\-',
this function modifier is selected by default to ensure that
.BR tar
can recover from short reads.
.TP
.B e
Error.  
Exit immediately with a positive exit status if any unexpected errors occur.
.TP
.B f
File.  
Use the
.I tarfile
argument as the name of the tarfile.
If
.B f
is specified, \f3/etc/default/tar\fP is not searched.
If
.B f
is omitted,
.B tar
will use the device indicated by the
.SB TAPE
environment variable, if set; otherwise, it will use
the default values defined in
.BR /etc/default/tar .
If the name of the tarfile is
.RB ' \- ',
.B tar
writes to the standard output or reads from the standard input,
whichever is appropriate.
.B tar
can be used as the head or tail of a pipeline.
.B tar
can also be used to move hierarchies with the command:
.sp 1n
.ti +5n
.B "example% cd fromdir; tar cf \- ."
.if n .ti +15n
.B "| (cd todir; tar xfBp \-)"
.TP
.B F
With one
.B F
argument,
.B tar
excludes all directories named
.SM SCCS
and
.SM RCS
from the tarfile.
With two arguments,
.BR FF ,
.B tar
excludes all directories named \s-1SCCS\s0 and \s-1RCS\s0, all files with
.B .o
as their suffix, and all files named
.BR errs ,
.BR core ,
and
.BR a.out .
.TP
.\" This option used to be L
.B h
Follow symbolic links as if they were normal files or directories.
Normally,
.B tar
does not follow symbolic links.
.TP
.B i
Ignore directory checksum errors.
.TP
.B l
Link.
Output error message if unable to resolve all links
to the files being archived.
If
.B l
is not specified, no
error messages are printed.
.TP
.B m
Modify.
The modification time
of the file is the time of extraction.
This function modifier is valid only with the
.B x
function.
.TP
.B o
Ownership.  Assign to extracted files the
user and group identifiers of the user running the program, rather
than those on tarfile.  This is the default behavior for users other
than root.  If the
.B o
function modifier is not set and the user is
root, the extracted files will take on the group and user
identifiers of the files on tarfile (see
.BR chown (1)
for more information).  The 
.B o
function modifier is only valid with the
.B x
function.
.TP
.B p
Restore the named files to their original modes, and ACLs if applicable,
ignoring the present
.BR umask (1).
.SM SETUID
and sticky information are also extracted for the super-user.
When this function modifier is used with the
.B c
function, ACLs are created in the tarfile along with other information.
Errors will occur when a tarfile with ACLs is extracted by
previous versions of
.BR tar .
.TP 
.B P
Suppress the addition of a trailing "/" on directory entries in 
the archive.
.TP
.B v
Verbose.
Output the name of each file 
preceded by the function letter.
With the
.B t
function,
.B v
provides additional information about the
tarfile entries.
The listing is similar to the format produced by the
.B \-l
option of the
.BR ls (1) 
command.
.TP
.B w
What.
Output the action to be taken and the name of the file, then
await the user's confirmation.
If the first keystroke is
.BR y ,
the action is performed; otherwise, the action is not performed.
This function modifier cannot be used with the
.B t
function.
.TP
.B X
Exclude.
Use the
.I exclude-file
argument as a file containing a list of relative path names for files
(or directories) to be excluded from the tarfile when using the functions
.BR c ,
.BR x ,
or
.BR t .
Be careful of trailing white spaces.
Multiple
.B X
arguments may be used, with one
.I "exclude-file"
per argument. 
In the case where included files (see
.BI \-I " include-file"
option)
are also specified, the excluded files take
precedence over all included files.
If a file is specified in both the
.I exclude-file
and the
.I include-file
(or on the command line),
it will be excluded.
.TP
.B [0-7]
Select an alternative drive on which the tape is mounted.
The default entries are specified in
.BR /etc/default/tar .
If no digit or \f3f\fP function modifier is specified,
the entry in \f3/etc/default/tar\fP with
digit "\f30\fP" is the default.
.SH EXAMPLES
.TP 3
.B 1.
The following is an example using
.B tar
to create an archive of your
home directory on a tape mounted on drive
.BR /dev/rmt/0 :
.RS 8
.sp 1n
.nf
.B example% cd	
.B "example% tar cvf /dev/rmt/0 ."
.IB "messages from " tar
.sp 1n
.fi
.RE
.RS 3
The
.B c
function letter means create the archive; the
.B v
function modifier outputs messages explaining what
.B tar
is doing; the
.B f
function modifier indicates that the tarfile is being specified (
.B /dev/rmt/0
in this example). The dot (\f3.\fP) at the end of the command
line indicates the current directory and is the argument of the
.B f
function modifier.
.LP
Display the table of contents of the tarfile with the following
command:
.RS 5
.sp 1n
.ft 3
.nf
example% tar tvf /dev/rmt/0
.if t .ta 10n +10n +8n +22n
.if n .ta 10n +8n +6n +22n
.RE
.LP
.ft 1
.fi
The output will be similar to the following:
.RS 5
.sp 1n
.ft 3
.nf
rw-r--r--	1677/40	2123	Nov  7 18:15 1985	./test.c
\&.\|.\|.
example%
.RE
.LP
.ft 1
.fi
The columns have the following meanings:
.LP
.RS 5
\(bu column 1 is the access permissions to \f3./test.c\f1
.br
\(bu column 2 is the \f2user-id\f1/\f2group-id\f1 of \f3./test.c\f1
.br
\(bu column 3 is the size of \f3./test.c\f1 in bytes
.br
\(bu column 4 is the modification date of \f3./test.c\f1
.br
\(bu column 5 is the name of \f3./test.c\f1
.RE
.LP
To extract files from the archive:
.RS 5
.sp 1n
.nf
.B example% tar xvf /dev/rmt/0
.IB "messages from " tar
.B example%
.fi
.RE
.LP
If there are multiple archive files on a tape, each is separated
from the following one by an
.SM EOF
marker.  To have 
.B tar
read the first and second archives from a tape with multiple archives on
it, the
.I non-rewinding
version of the tape device name must be used with the \f3f\f1 function modifier,
as follows:
.RS 5
.sp 1n
.nf
.if t .ta 32n
.if n .ta 32n
.BI "example% tar xvfp /dev/rmt/0n" "	read first archive from tape"
.IB "messages from " tar
.BI "example% tar xvfp /dev/rmt/0n" "	read second archive from tape"
.IB "messages from " tar
.B example%
.fi
.RE
.br
.ne 7
.LP
Note that in some earlier releases, the above scenario did not work
correctly, and intervention with
.BR mt (1)
between
.B tar
invocations was necessary.
To emulate the old behavior, use
the non-rewind device name containing the letter
.B b
for BSD behavior.  See the
.B "Close Operations" 
section of the
.BR mtio (7I)
manual page.
.RE
.TP 3
.B 2.
To archive files from
.B /usr/include
and from
.B /etc 
to default tape drive \f30\f1:
.sp 1n
.RS 8
.B "example% tar c \-C /usr  include \-C /etc ."
.RE
.RS 3
.sp 1n
The table of contents from the resulting
tarfile would produce output like the following:
.RS 5
.sp 1n
.nf
.B include/
.B include/a.out.h
.IB "and all the other files in " "/usr/include \f1.\|.\|."
.B ./chown
.IB "and all the other files in " /etc
.fi
.sp 1n
.RE
To extract all files in the
.BR include " directory:"
.RS 5
.sp 1n
.nf
.ft 3
example% tar xv include
x include/, 0 bytes, 0 tape blocks
.ft 2
and all files under \f3include\f1.\|.\|.
.fi
.RE
.RE
.br
.ne 6
.TP 3
.B 3.
The following is an example using
.B tar
to transfer files across the Ethernet.
First, here is how to archive files
from the local machine (\c
.BR example )
to a tape on a remote system (\c
.BR host ):
.RS 8
.sp 1n
.BI "example% tar cvfb  \-  20" " files " |
.if n .ti +5n
.BI " rsh " host " dd of=/dev/rmt/0  obs=20b"
.nf
.IB "messages from " tar
.B example%
.fi
.RE
.RS 3
.LP
In the example above, we are
.I creating
a
.I tarfile
with the
.B c
key letter, asking for
.I verbose
output from
.B tar
with the
.B v
function modifier, specifying the name of the output
.I tarfile
using the
.B f
function modifier (the standard output is where the
.I tarfile
appears, as indicated
by the
.RB ` \- '
sign), and specifying the blocksize (\f320\f1) with the
.B b
function modifier.
If you want to change the blocksize, you must change the blocksize
arguments both on the
.B tar
command
.I and
on the
.B dd
command.
.RE
.TP 3
.B 4.
The following is an example that uses
.B tar
to retrieve files from a tape on the remote system back to the
local system:
.LP
.RS 8
.B example% rsh  \-n host  dd
.B if=/dev/rmt/0  bs=20b |
.if n .ti +5n
.B tar xvBfb  \- 20
.I files
.br
.IB "messages from " tar
.br
.B example%
.RE
.RS 3
.LP
In the example above, we are
.I extracting
from the
.I tarfile
with the
.B x
key letter, asking for
.I verbose output from
.B tar
with the
.B v
function modifier, telling
.B tar
it is reading from a pipe with the
.B B
function modifier, specifying the name of the input
.I tarfile
using the
.B f
function modifier (the standard input is where the
.I tarfile
appears, as indicated
by the
.RB ` \- '
sign), and specifying the blocksize (\f320\f1) with the
.B b
function modifier.
.RE
.TP 3
.B 5.
The following example creates an archive of the home directory on
.B /dev/rmt/0
with an actual blocking factor of 19.
.sp 1n
.RS 8
.ft 3
example% tar cvfb /dev/rmt/0 19 $HOME
.ft 1
.sp 1n
.RE
.RS 3
To recognize this archive's actual blocking factor without using the
.B b
function modifier:
.sp 1n
.RS 5
.ft 3
.nf
example% tar tvf /dev/rmt/0 
tar: blocksize = 19
\&.\|.\|.
.fi
.ft 1
.sp 1n
.RE
To recognize this archive's actual blocking factor using a
larger nominal blocking factor:
.sp 1n
.RS 5
.ft 3
.nf
example% tar tvf /dev/rmt/0 30
tar: blocksize = 19
\&.\|.\|.
.fi
.ft 1
.RE
.sp 1n
Attempt to recognize this archive's actual blocking factor using a
nominal blocking factor that is too small:
.sp 1n
.RS 5
.ft 3
.nf
example% tar tvf /dev/rmt/0 10
tar: tape read error
.fi
.ft 1
.RE
.RE
.SH ENVIRONMENT
See
.BR environ (5)
for descriptions of the following environment variables that affect the
execution of
.BR tar :
.BR \s-1LC_COLLATE\s0\f1 ,
.BR \s-1LC_CTYPE\s0\f1 ,
.BR \s-1LC_MESSAGES\s0\f1 ,
.BR \s-1LC_TIME\s0\f1 ,
.BR \s-1TZ\s0\f1 ,
and
.BR \s-1NLSPATH\s0\f1 .
.SH "EXIT STATUS"
The following exit values are returned:
.PD 0
.TP 10
.B 0
Successful completion.
.TP
.B >0
An error occurred.
.PD
.SH FILES
.PD 0
.TP
.B /dev/rmt/[0-7][b][n]
.TP
.B /dev/rmt/[0-7]l[b][n]
.TP
.B /dev/rmt/[0-7]m[b][n]
.TP
.B /dev/rmt/[0-7]h[b][n]
.TP
.B /dev/rmt/[0-7]u[b][n]
.TP
.B /dev/rmt/[0-7]c[b][n]
.br
.TP 20
.B /etc/default/tar
Settings may look like this:
.RS
.B archive0=/dev/rmt/0
.br
.B archive1=/dev/rmt/0n
.br
.B archive2=/dev/rmt/1
.br
.B archive3=/dev/rmt/1n
.br
.B archive4=/dev/rmt/0
.br
.B archive5=/dev/rmt/0n
.br
.B archive6=/dev/rmt/1
.br
.B archive7=/dev/rmt/1n
.LP
.RE
.LP
.B /tmp/tar\(**
.PD
.SH SEE ALSO
.BR ar (1),
.BR basename (1),
.BR cd (1),
.BR chown (1),
.BR cpio (1),
.BR csh (1),
.BR dirname (1),
.BR ls (1),
.BR mt (1),
.BR pax (1),
.BR setfacl (1),
.BR umask (1),
.BR mknod (1M),
.BR vold (1M),
.BR environ (5),
.BR mtio (7I)
.SH DIAGNOSTICS
Diagnostic messages are output for bad key characters and tape read/write errors,
and for insufficient memory to hold the link tables.
.SH NOTES
There is no way to access for the
.IR n -th
occurrence of a file.
.LP
Tape errors are handled ungracefully.
.LP
When the Volume Management daemon is running, accesses to floppy devices
through the conventional device names (for example,
.BR /dev/rdiskette )
may not succeed.  See 
.BR vold (1M)
for further details.
.LP
The
.B tar
archive format allows 
\s-1UID\s0s and \s-1GID\s0s up to 2097151 to be stored in the archive header.
Files with \s-1UID\s0s and \s-1GID\s0s greater than this value 
will be archived with the
.SM UID
and 
.SM GID 
of
.BR 60001 .
