Tar darwin, gnutar

Tape Archive

Sun version

tar create, update, or extract files in a single tarfile.
Used to package a group of related files.
Output can be directed to a disk file.
Table of contents can be listed from an existing tar file, individual files can be xtracted.

Eample: create, verbose, tarfile.tar compressing files in the home directory(~), excluding ISO images ( at lower priority with errors written to a logfile

       nice tar -czvf tarfile.taz --exclude *iso ~ > tar.`date +log.%y%m%d%H%M.stderr`
      head -10 tar.`date +log.%y%m%d%H*.stderr`
Eample: extract files, verbosely from previously created tarfile creating subdirectory from which the files came originally:
        tar -xvf package.tar .
Define operation
create/update tarfile
-c
--create
-A Append
--append
--catenate
--concatenate
-u
--update
-d
--diff
--compare

-r replace
display contents of tarfile.tar
-t Table of contents
--list
(tarfile is not updated nor are files extracted
extract individual files from tarfile.tar -x
-extract
--get
options which affect file selection
-G, --incremental  
-g, --listed-incremental fname 
-N, --after-date DATE, --newer  DATE    

    --files-from=flist+
    --exclude  FILE     
    --exclude-from  FILE 

-C, --directory DIR 
    --checkpoint       
-T, --force-local      
-F, --info-script  fname
    --new-volume-script  fname  
 
-h, --dereference   

-k, --keep-old-files  
-K, --starting-file  fname
-l, --one-file-system     

--remove-files  

options which affect attributes of files
--atime-preserve -m, --modification-time -p, --same-permissions, --preserve-permissions --null
options which affect output
-f,  --file  HOSTNAME: fname  
-O, --to-stdout  
-P, --absolute-paths  
    --preserve       

-s, --same-order, --preserveorder  
    --same-owner  
-S, --sparse   
-w, --interactive, --confirmation  

--version   
 
-j, -I, --bzip 
-X, -Z, --compress, --uncompress  
-z, --gzip, --ungzip        
--use-compress-program PROG 

Less frequently used
-i, --ignore-zeros -M, --multi-volume -b, --block-size N -B, --read-full-blocks --block-compress -[0-7 lmh ] -L, --tape-length n --ignore-failed-read -V, --label NAME -W, --verify -R, --record-number -o, --old-archive, --portability
affect STDOUT display
--totals -v, --verbose
fname1 fname2, ... fnameN ]

or

dir1 dir2, ...dirN ]

GNU version of tar , an archiving program designed to store and extract files from an archive file known as a tarfile. A tarfile may be made on a tape drive, it is more common to write a tarfile to a normal file.
The first argument to tar must be one of the options: A c d r t u x
The final arguments to tar are the names of the files or directories which to be archived / eXtracted.
The use of a directory name always implies that the subdirectories below should be included in the archive.

Function

 One of the following must be used: 
 -A, --catenate, --concatenate   Append tar files to an archive
 -c, --create              a new archive
 -d, --diff, --compare   find differences between archive and file system

        > tar -df htmlroot.tar|egrep -v 'Mode|Uid|Gid'

       v.tar.files
       v.tar.files: Uid differs  may be bad. most likely not if transfered from another system
       v.tar.files: Gid differs
       v.tar.files: Mod time differs  Most likely BAD
       v.tar.files: Size differs      Most likely BAD
           
       

 -r, --append           files to the end of an archive
 -t, --list              list the table of contents of an archive
 -u, --update            only append files that are newer than copy in archive
 -x, --extract, --get    from an archive
 --delete               delete from the archive (not for use on tapes!)

OTHER OPTIONS
 --atime-preserve           don't change access times on dumped files
 -b, --block-size N         block size of Nx512 bytes (default N=20) 
 -B, --read-full-blocks     reblock as we read (for reading 4.2BSD pipes) 
 -C, --directory DIR        change to directory DIR 
 --checkpoint               print directory names while reading the archive 
 -f, --file [HOSTNAME:]F    use archive file or device F (default /dev/rmt0) 
 --force-local              archive file is local even if has a colon 
 -F, --info-script F --new-volume-script F
    run script at end of each tape (implies -M) 
 -G, --incremental          create/list/extract old GNU-format incremental backup
 -g, --listed-incremental F create/list/extract new GNU-format incremental backup 
 -h, --dereference          don't dump symlinks; dump the files they point to 
 --ignore-failed-read       don't exit with non-zero status on unreadable files 
 -i, --ignore-zeros         ignore blocks of zeros in archive (normally mean EOF) 
 -j, -I, --bzip             filter the archive through bzip2. 
			Note: -I is deprecated and may get a different meaning in the future. 
 -k, --keep-old-files       keep existing files; don't overwrite them from archive 
 -K, --starting-file F      begin at file F in the archive 
 -l, --one-file-system      stay in local file system when creating an archive 
 -L, --tape-length N        change tapes after writing N*1024 bytes 
 -m, --modification-time    don't extract file modified time 
 -M, --multi-volume         create/list/extract multi-volume archive good for floppies 
 --null              -T reads null-terminated names, disable -C 
 -N, --after-date DATE, --newer DATE      only store files newer than DATE 
 -o, --ld-archive, --portability  write a V7 format archive, rather than ANSI format
 -O, --to-stdout             extract files to standard output 
 -p, --same-permissions, 
     --preserve-permissions  extract all protection information
     --same-owner            create extracted files with the same ownership 
 --preserve              like -p -s
 -P, --absolute-paths        don't strip leading `/'s from file names 
 -R, --record-number        show record number within archive with each message 
 --remove-files             after adding them to the archive
	  Use if tight on space and tarfile is on same volume as files being archived) 
 -s, --same-order, --preserve-order
    			list of names to extract is sorted to match archive 
 -S, --sparse               handle sparse files efficiently 
 -T, --files-from=F         get names to extract or create from file F 
     --totals               print total bytes written with --create 
 -v, --verbose              verbosely list files processed 
 -V, --label NAME           create archive with volume name NAME 
     --version              print tar program version number 
 -w, --interactive, --confirmation    ask for confirmation for every action 
 -W, --verify               verify the archive after writing it 
     --exclude FILE
 -X, --exclude-from FILE       exclude files listed in FILE 
 -Z, --compress, --uncompress  filter the archive through compress
 -z, --gzip, --ungzip          gzip
 --use-compress-program PROG   filter the archive through PROG (which must accept -d)

 tar - The GNU version of the tar archiving utility
                      30 October 2000                         TAR(1)

Errors
tar --remove -cf bigball.tar *
File size limit exceeded
> echo $?
153
Files are not removed.
tar: email2.db: Wrote only 2048 of 10240 bytes
tar: Error is not recoverable: exiting now
echo $?

tar: email.db: Cannot write: No space left on device




NAME

     tar - create tape archives, and add or extract files

SYNOPSIS

     /usr/sbin/tar c [ bBefFhilvwX [ 0-7 ]] [ device ] [ block ]
[ exclude-filename ... ] [ -I include-filename ]
filename ...  [ -C directory filename ]

 /usr/sbin/tar r [ bBefFhilvw [ 0-7 ]] [ device ] [ block ]
[ -I include-filename ] filename ...
[ -C directory filename ]

 /usr/sbin/tar t [ BefFhilvX [ 0-7 ]] [ device ]
[ exclude-filename ... ] [ -I include-filename ]
[ filename ... ]

 /usr/sbin/tar u [ bBefFhilvw [ 0-7 ]] [ device ] [ block ]
filename ...

 /usr/sbin/tar x [ BefFhilmopvwX [ 0-7 ]] [ device ]
[ exclude-filename ... ] [ filename ... ]

DESCRIPTION

tar archives and extracts files to and from a single file called a tarfile . A tarfile is usually a magnetic tape, but it can be any file. tar's actions are controlled by the key argument. The key is a string of characters containing exactly one function letter (c, r, t , u, or x) and one or more function modifiers, depending on the function letter used. Other arguments to the command are filenames (or directory names) specifying which files are to be archived or extracted. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory.
Function Letters
The function portion of the key is specified by one of the following letters:

c Create. Writing begins at the beginning of the tarfile, instead of at the end. This key implies the r key.

r Replace. The named filenames are written on the end of the tape. The c and u functions imply this function. See NOTES for more information.

t Table of Contents. The names of the specified files are listed each time they occur on the tarfile. If no filenames arguments are given, all the names on the tarfile are listed. With the v function modifier, additional information for the specified files is displayed. The listing is similar to the format produced by the ls -l command.

u Update. The named filenames are added to the tarfile if they are not already there, or have been modified since last written on that tarfile. This key implies the r key. See NOTES for more information.

x Extract, or restore. The named filenames are extracted from the tarfile and written to the current directory. If a named file matches a directory whose contents had been written onto the tarfile, this directory is (recursively) extracted. Use the file or directory's relative path when appropriate, or tar will not find a match. The owner, modification time, and mode are restored (if possible); otherwise, to restore owner, you must be the superuser. If no filenames argument is given, the entire content of the tarfile is extracted. Note: If several files with the same name are on the tarfile, the last one overwrites all earlier ones. See NOTES for more information.

Function Modifiers
The characters below may be used in addition to the letter that selects the desired function. Use them in the order shown in the SYNOPSIS.

b Blocking Factor. This causes tar to use the block argument as the blocking factor for tape records. The default is 1, the maximum is 20. This function should not be supplied when operating on regular archives or block special devices. It is mandatory however, when reading archives on raw magnetic tape archives (see f below). The block size is deter- mined automatically when reading tapes created on block special devices (key letters x and t). This determination of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). The maximum blocking factor is determined only by the amount of memory available to tar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utilization.

B Block. Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. When reading from standard input, '-', this option is automatically selected to make sure that tar can recover from short reads.

e Error. If any unexpected errors occur tar will exit immediately with a positive exit status.

f File. This causes tar to use the device argument as the name of the tarfile. If f is given, /etc/default/tar is not searched. If f is omitted, tar will use the device indicated by the TAPE environment variable, if set; otherwise, it will use the default values defined in /etc/default/tar. If the name of the tarfile is '-', tar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, tar can be used as the head or tail of a pipeline. tar can also be used to move hierarchies with the command: example% cd fromdir; tar cf - . | (cd todir; tar xfBp -)

F With one F argument, tar will exclude all directories named SCCS from the tarfile. With two arguments, FF , tar will exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out.

h Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links.

i Ignore. With this option tar will ignore directory checksum errors.

l Link. This tells tar to complain if it cannot resolve all of the links to the files being archived. If l is not specified, no error messages are printed.

m Modify. This tells tar to not extract the modification times from the tarfile. The modification time of the file will be the time of extraction. This option is only valid with the x key.

o Ownership. This causes extracted files to take on the user and group identifier of the user running the program, rather than those on tape. This happens by default for users other than root. If the 'o' option is not set and the user is root, the extracted files will take on the group and user identifiers of the files on tape (see chown(1) for more information). The 'o' option is only valid with the x key.

p Restore the named files to their original modes, ignoring the present umask(2). SETUID and sticky information are also extracted if your are the super-user. This option is only useful with the x key letter.

v Verbose. Normally, tar does its work silently. This option causes tar to type the name of each file it treats, preceded by the function letter. With the t function, v gives more information about the tape entries than just the name.

w What. This option causes tar to print the action to be taken, followed by the name of the file, and then wait for the user's confirmation. If a word beginning with y is given, the action is performed. Any other input means no. This is not valid with the t key.

X Exclude. Use the exclude-filename argument as a file containing a list of named files (or directories) to be excluded from the tarfile when using the key letters c, x, or t. Multiple X arguments may be used, with one exclude-filename per argument. See NOTES for more information.

[0-7] Select an alternative drive on which the tape is mounted. The default entries are specified in /etc/default/tar.

If a file name is preceded by - I then the filename is opened. A list filenames, one per line, is treated as if each appeared separately on the command line. Be careful of trailing white space in both include and exclude file lists.

In the case where excluded files (see X option) also exist, excluded files take precedence over all included files. So, if a file is specified in both the include and exclude files (or on the command line), it will be excluded.

If a file name is preceded by - C in a c (create) or r (replace) operation, tar will perform a chdir (see csh(1)) to that file name. This allows multiple directories not related by a close common parent to be archived using short relative path names.

Note: the -C option only applies to one following directory name and one following file name.

If no digit or 'f' is given, the entry in /etc/default/tar with digit "0" will be the default.

EXAMPLES

To archive files from /usr/include and from /etc, onto default tape drive 0 one might use:
example% tar c -C /usr  include -C /etc .
If you get a table of contents from the resulting tarfile, you might see something like:
include/
include/a.out.h
and all the other files in /usr/include ...
/chown
and all the other files in /etc
To extract all files under include:
example% tar xv include
x include/, 0 bytes, 0 tape blocks
and all files under include... Here is a simple example using tar to create an archive of your home directory on a tape mounted on drive
/dev/rmt/0:

example% cd
example% tar cvf /dev/rmt/0 .
messages from tar The c option means create the archive; the v option makes tar tell you what it is doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmt/0 in this example).

Now you can read the table of contents from the archive like this: example% tar tvf /dev/rmt/0 rw-r--r-- 1677/40 2123 Nov 7 18:15 1985 ./test.c ... example%

The columns have the following meanings:


+ column 1 is the access permissions to ./test.c
+ column 2 is the user-id/group-id of ./test.c
+ column 3 is the size of ./test.c in bytes
+ column 4 is the modification date of ./test.c
+ column 5 is the name of ./test.c
 You can extract files from the archive like this:

example% tar xvf /dev/rmt/0
messages from tar example%

If there are multiple archive files on a tape, each is separated from the following one by an EOF marker. tar does not read the EOF mark on the tape after it finishes reading an archive file because tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use tar to read the next archive file from the tape, tar does not know enough to skip over the EOF mark and tries to read the EOF mark as an archive instead. The result of this is an error message from tar to the effect:

tar: blocksize=0

This means that to read another archive from the tape, you must skip over the EOF marker before starting another tar command. You can accomplish this using the mt(1) command, as shown in the example below. Assume that you are reading from /dev/rmt/0n.

example% tar xvfp /dev/rmt/0n read first archive from tape messages from tar example% mt fsf 1 skip over the end-of-file marker example% tar xvfp /dev/rmt/0n read second archive from tape messages from tar example%

Finally, here is an example using tar to transfer files across the Ethernet. First, here is how to archive files from the local machine (example) to a tape on a remote sys- tem (host):

example% tar cvfb  -  20 filenames |
      rsh host dd of=/dev/rmt/0  obs=20b
messages from tar  
example%

In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with the v option, specifying the name of the output tarfile using the f option (the standard output is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option. If you want to change the blocksize, you must change the blocksize arguments both on the tar command and on the dd command.

Now, here is how to use tar to get files from a tape on the remote system back to the local system:

 example% rsh -n host dd if=/dev/rmt/0 bs=20b | tar xvBfb - 20 filenames
messages from tar example%

In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the input tarfile using the f option (the standard input is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option.

ENVIRONMENT

If any of the LC_* variables ( LC_CTYPE, LC_MESSAGES, LC_TIME, LC_COLLATE, LC_NUMERIC, and LC_MONETARY ) (see environ(5)) are not set in the environment, the operational behavior of tar for each corresponding locale category is determined by the value of the LANG environment variable. If LC_ALL is set, its contents are used to override both the LANG and the other LC_* variables. If none of the above variables is set in the environment, the "C" (U.S. style) locale determines how tar behaves.

LC_CTYPE
Determines how tar handles characters. When LC_CTYPE is set to a valid value, tar can display and handle text and filenames containing valid characters for that locale. tar can display and handle Extended Unix code (EUC) characters where any individual character can be 1, 2, or 3 bytes wide. tar can also handle EUC characters of 1, 2, or more column widths. In the "C" locale, only characters from ISO 8859-1 are valid.
LC_MESSAGES
Determines how diagnostic and informative messages are presented. This includes the language and style of the messages, and the correct form of affirmative and negative responses. In the "C" locale, the messages are presented in the default form found in the program itself (in most cases, U.S. English).
LC_TIME
Determines how tar handles date and time formats. In the "C" locale, date and time handling follow the U.S. rules.

FILES

     /dev/rmt/[0-7][lmhuc][b][n]
 /etc/default/tar    Settings may look like this:
archive0=/dev/rmt/0
archive1=/dev/rmt/0n
archive2=/dev/rmt/1
archive3=/dev/rmt/1n
archive4=/dev/rmt/0
archive5=/dev/rmt/0n
archive6=/dev/rmt/1
archive7=/dev/rmt/1n
 /tmp/tar*

SEE ALSO

     ar(1), chown(1), cpio(1), csh(1),  ls(1),  mt(1),  umask(2), environ(5)

DIAGNOSTICS

Complains about bad key characters and tape read/write errors.
Complains if enough memory is not available to hold the link tables.

NOTES

There is no way to ask for the n-th occurrence of a file.

Tape errors are handled ungracefully.

The u option can be slow.

The b option should not be used with archives that are going to be updated. The current magnetic tape driver cannot backspace raw magnetic tape. If the archive is on a disk file, the b option should not be used at all, because updating an archive stored on disk can destroy it.

Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives cannot backspace.

When extracting tapes created with the r or u option, directory modification times may not be set correctly.

When using r,u,x, orX, the named files must match exactly to the corresponding files in the tarfile. For example, to extract ./filename, you must specify ./filename, and not filename. The t option displays how each file was archived.

The full pathname length cannot exceed 255 characters.
The file name (or leaf) length cannot exceed 100 characters.
The prefix of the pathname cannot exceed 155 characters.
tar does not copy empty directories or special files such as devices.
Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form:
tar xvf... /dev/rmt/0 `tar tf... /dev/rmt/0 | grep 'pattern'`

SunOS 5.4 Last Change: 17 Feb 1994