BAR(1)

NAME
bar - create tape archives, and add or extract files

SYNOPSIS
bar [ - ] crxtu [ 014578feovwbXlFmhpBisHSUZRTIN ]
[ bar-file ] [ blocksize ] [ exclude-file ] [ string ]
[ target_directory ] [ user_id ] [ include-file ]
filename1 ... [ -C dir filename ... ]...

DESCRIPTION

bar archives and extracts multiple files onto a single bar, file archive, called a bar-file. It is quite similar to tar(5), but it has additional function modifiers, can read and write multiple volumes, and writes and reads a format that is incompatible with tar (see bar(5)). A bar-file is usually a magnetic tape, but it can be any file. bar's actions are controlled by the first argument, the key, a string of characters containing exactly one function letter from the set rxtuc, and one or more of the optional function modifiers listed below. Other arguments to bar are file or directory names that specify which files to archive or extract. In all cases, the appearance of a directory name refers recursively to the files and subdirectories of that directory.

FUNCTION LETTERS

c   Create a new bar-file and write the named files onto it.

r   Write the named files on the end of the bar-file. Note: this option does not work with quarter-inch archive tapes.

x   Extract the named files from the bar-file. If a named file matches a directory with contents written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no filename arguments are given, all files in the archive are extracted. Note: if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions.

t   List the table of contents of the bar-file.

u   Add the named files to the bar-file if they are not there or if they have been modified since they were last archived. Note: this option does not work with quarter-inch archive tapes.

FUNCTION MODIFIERS

014578
    Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid drives. The default is /dev/rmt8.

f   Use the next argument as the name of the bar-file. If f is omitted, use the device indicated by the TAPE environment variable, if set. Otherwise, use /dev/rmt8 by default. If bar-file is given as `-', bar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, bar can be used as the head or tail of a filter chain. bar can also be used to copy hierarchies with the command:

    example% cd fromdir; bar cf - . | (cd todir; bar xfBp -)

e   If any unexpected errors occur bar exits immediately with a positive exit status.

o   Suppress information specifying owner and modes of directories which bar normally places in the archive. Such information makes former versions of bar generate an error message like:

        filename: cannot create

    when they encounter it.

v   Verbose. Normally bar does its work silently; the v option displays the name of each file bar treats, preceded by the function letter. When used with the t function, v displays the bar-file entries in a form similar to `ls -l '.

w   Wait for user confirmation before taking the specified action. If you use w, bar displays the action to be taken followed by the file name, and then waits for a y response to proceed. No action is taken on the named file if you type anything other than a line beginning with y.

b   Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. The block size is determined automatically when reading tapes (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 bar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utilization.

X   Use the next argument as a file containing a list of named files (or directories) to be excluded from the bar-file when using the key letters `c', `x', or `t'. Multiple X arguments may be used, with one exclude-file per argument.

l   Display error messages if all links to archived files cannot be resolved. If l is not used, no error messages are printed.

F   With one F argument specified, exclude all directories named SCCS from bar-file. With two arguments FF, exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out.

m   Do not extract modification times of extracted files. The modification time will be the time of extraction.

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

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

B   Force bar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that bar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming.

i   Ignore directory checksum errors.

s   Force the ownership of extracted files to match the bar process's effective user ID and group ID.

H   The string of up to 128 characters is to be used as a volume header ID. A volume header is written to each volume of the archive when the c function letter is specified. See bar(5) for the volume header's format.

    Use of the H function modifier when creating an archive allows bar to read volumes out of sequence. When extracting a file that spans volumes, bar will identify the tape(s) it needs to extract the entire file. If the wrong volume is inserted, bar issues a warning and prompts again for the correct volume.

S   Place files specified for extraction in this target directory when used with the x function letter.

U   Specify the user ID in the volume header when creating archive, when the H function modifier is used. If the c function letter is specified and a volume header exists, bar will verify that the user ids match before overwriting bar-file if the N modifier is specified.

Z   Specify compression. bar will compress files when used with the c function letter and will decompress files when used with the x function letter. bar will neither compress a compressed file, nor decompress a decompressed file.

R   Read the volume header and print the information to stdout.

N   See if the user owns the media (uid matches that in the bar header) before overwriting bar-file with the C key word.

T   When using the x or t function letters, terminate the search of the media after all the files specified are extracted (for x) or listed (for t).

I   Use the next argument as a file containing a list of named files, one per line, to be included in the bar archive. The include file expects filenames to be followed by a semicolon and newline character.

    In the case where excluded files (see X flag) 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.

OPTIONS

-C dir filename
    In a c (create) or r (replace) operation, bar performs a chdir (see csh(1)) to that directory before interpreting filename. This allows multiple directories not related by a close common parent to be archived using short relative path names. For example, to archive files from /usr/include and from /etc, one might use:

    example% bar c -C /usr include -C /etc .

    If you get a table of contents from the resulting bar-file, you will see something like:
    include/
    include/a.out.h
    and all the other files in /usr/include .../chown
    and all the other files in /etc

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

EXAMPLES

Here is a simple example using bar to create an archive of your home directory on a tape mounted on drive /dev/rmt0:

    example% cd
    example% bar cvf /dev/rmt0 .
    messages

The c option means create the archive; the v option makes bar tell you what it's doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmt0 in this example).

Here is another example: /dev/rmt0:

    example% cd
    example% bar cvfH /dev/rmt0 "THIS IS MY HEADER"  .
    messages

As in the first example, the c option means create the archive; the v option makes bar tell you what it's doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmt0 in this example). The H option says to use the string "THIS IS MY HEADER" as the ID field in the volume header.

Now you can read the table of contents from the archive like this:

    example% bar tvf /dev/rmt0
    (access  user-id/group-id	size	mod. date	filename)
    rw-r--r-- 1677/40 	2123	Nov 7 18:15:1985	./archive/test.c
    ...
    example%

You can extract files from the archive like this:
    example% bar xvf /dev/rmt0
    messages

If there are multiple archive files on a tape, each is separated from the following one by an EOF marker. bar does not read the EOF mark on the tape after it finishes reading an archive file because bar looks for a special header to decide when it has reached the end of the archive. Now if you try to use bar to read the next archive file from the tape, bar 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 bar to the effect:

    bar: blocksize=0

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

    example% bar xvfp /dev/nrmt0 read first archive from tape
    messages
    example% mt fsf 1 skip over the end-of-file marker
    example% bar xvfp /dev/nrmt0 read second archive from tape
    messages
    example%

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

    example% bar cvfb -  20 filenames | rsh host dd of=/dev/rmt0 obs=20b
    messages
    example%

In the example above, we are creating a bar-file with the c key letter, asking for verbose output from bar with the v option, specifying the name of the output bar-file using the f option (the standard output is where the bar-file 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 bar command and on the dd command.

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

    example% rsh -n host dd if=/dev/rmt0 bs=20b | bar xvBfb - 20 filenames
    messages
    example%

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

FILES
/dev/rmt?
    half-inch magnetic tape interface
/dev/rar?
    quarter-inch magnetic tape interface
/dev/rst?
    SCSI tape interface
/tmp/bar*

ENVIRONMENT

TAPE
    If specified, in the environment, the value of TAPE indicates the default tape device.

NOTES
bar will handle multiple volumes gracefully. If a tape error is encountered, bar issues a message on the standard error requesting a new volume. The presence of a new volume is confirmed when bar reads a line beginning with Y or y on the standard input; a line beginning with N or n aborts the archive; with any other character bar reissues the prompt.

SEE ALSO
cpio(1), mt(1), umask(2V), bar(5), tar(5), dump(8), restore(8)

BUGS

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

There is no way to ask for the nth occurrence of a file.

The u option can be slow.

There is no way selectively to follow symbolic links.

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

Files with names longer than 100 characters cannot be processed.

Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form:

    bar xvf... /dev/rst0 `bar tf... /dev/rst0 | grep 'pattern'`

If you specify `-' as the target file and the archive spans volumes, the request for a new volume may get lost.