1234 lines
30 KiB
Plaintext
1234 lines
30 KiB
Plaintext
.\" @(#)install.n 5.3 12/21/87
|
|
.\"
|
|
.\" BRU (Backup and Restore Utility)
|
|
.\" Installation Guide
|
|
.\" Nroff/Troff source
|
|
.\"
|
|
.\" tbl install.n | nroff -mm >install.doc
|
|
.\" tbl install.n | troff -mm | ...
|
|
.\"
|
|
.\"
|
|
.\" === Hyphenation control (1 = on)
|
|
.\".nr Hy 1
|
|
.\" === Page offset register
|
|
.\".nr O 10
|
|
.\" === Some kind of black magic, but I forget ...
|
|
.tr ~
|
|
.\" === All headings unnumbered.
|
|
.\" .nr Hu 1
|
|
.\" === Set for space after headings for levels 1-3
|
|
.nr Hs 3
|
|
.\" === Set for breaks after headings for levels 1-3
|
|
.nr Hb 3
|
|
.\" === Force all level 1 headings to start on new page
|
|
.nr Ej 1
|
|
.\" === Set page header format
|
|
.PH "/\*(DT/(preliminary)/Bru Installation Guide/"
|
|
.\" === Set page footer format
|
|
.PF "// - % - //"
|
|
.\" === Set quoting for nroff/troff
|
|
.if n .ds lq ""
|
|
.if n .ds rq ""
|
|
.if t .ds lq ``
|
|
.if t .ds rq ''
|
|
.\"
|
|
.\" The "\!.br" embedded in the title macro is some kind of black magic.
|
|
.\"
|
|
.TL
|
|
Backup and Restore Utility
|
|
.br
|
|
\!.br
|
|
(BRU)
|
|
.br
|
|
\!.br
|
|
Installation Guide
|
|
.AF "Engineering Software Tools"
|
|
.AU "Fred Fish"
|
|
.AF "Georgia Tech, School of I.C.S."
|
|
.AU "Arnold Robbins"
|
|
.SA 1
|
|
.\" === All paragraphs indented from now on
|
|
.nr Pt 1
|
|
.AS 1
|
|
This document describes the
|
|
.I bru
|
|
installation procedure for
|
|
new software/hardware environments.
|
|
For best performance,
|
|
.I bru
|
|
requires proper initialization of a device table file,
|
|
usually located in
|
|
.IR /etc/brutab .
|
|
The purpose of this document is to describe function of the device table
|
|
and ways to determine the appropriate entries.
|
|
It also describes, in fair detail, the changes
|
|
that were necessary to bring
|
|
.I bru
|
|
up under 4.2\ BSD.
|
|
This should serve to highlight points to examine when porting
|
|
to some other version of
|
|
.BR UNIX .
|
|
.AE
|
|
.MT 4 1
|
|
.SK
|
|
.H 1 "INTRODUCTION"
|
|
.P
|
|
For best performance,
|
|
.I bru
|
|
requires proper initialization of a device table file,
|
|
usually located in
|
|
.IR /etc/brutab .
|
|
The purpose of this document is to describe function of the device table
|
|
and ways to determine the appropriate entries.
|
|
.P
|
|
One of the most powerful concepts of the
|
|
.B UNIX\*F
|
|
.FS
|
|
UNIX is a trademark of AT&T Bell Laboratories.
|
|
.FE
|
|
operating system
|
|
is that everything is a file.
|
|
Using this concept, and the technique of information hiding (of the
|
|
implementation details), application programming is greatly simplified
|
|
and portability is enhanced.
|
|
Unfortunately there are certain types of applications, which by their
|
|
very nature, need more information about I/O irregularities than
|
|
most standard
|
|
.B UNIX
|
|
systems provide.
|
|
.I Bru
|
|
is an example of one such application.
|
|
.P
|
|
To compensate for the lack of well defined, deterministic information
|
|
about such conditions as attempts to read or write unformatted media,
|
|
the size of removable media, etc,
|
|
.I bru
|
|
contains
|
|
an internal table which describes certain conditions under which
|
|
the cause of I/O irregularities can be intuited.
|
|
.P
|
|
In previous versions of
|
|
.IR bru ,
|
|
the device table was initialized by
|
|
making appropriate changes to the source code.
|
|
The current version supports initialization from an external data file,
|
|
usually
|
|
.IR /etc/brutab .
|
|
This is much more flexible and allows system administrators to add or
|
|
alter system devices without having access to the
|
|
.I bru
|
|
source code.
|
|
An examination of the data file template will underscore the fact that
|
|
there are wide variations in implementation details of various
|
|
hardware/software environments.
|
|
.H 1 "DISTRIBUTION OVERVIEW"
|
|
.P
|
|
The
|
|
.I bru
|
|
distribution tape consists of four major directories.
|
|
.P
|
|
The
|
|
.I bru
|
|
source distribution directory contains several subdirectories
|
|
as follows:
|
|
.VL 18 4
|
|
.B
|
|
.LI bru/config
|
|
.R
|
|
Contains configuration script and data base information for
|
|
systems on which installations have been completed by the author,
|
|
as well as for installations completed at Georgia Tech.
|
|
Also contains a template
|
|
.I brutab
|
|
file for customization for a specific hardware/software environment.
|
|
The configuration script builds the
|
|
.B config.mk
|
|
file, which is an include file for
|
|
.IR make .
|
|
.B
|
|
.LI bru/doc
|
|
.R
|
|
Contains machine readable form of all available documentation,
|
|
including the nroff/troff source for this document.
|
|
.B
|
|
.LI bru/notes
|
|
.R
|
|
Contains various commentary type notes of a random nature about
|
|
details of the implementation and other things of interest.
|
|
.B
|
|
.LI bru/src
|
|
.R
|
|
Contains all source required to make
|
|
.IR bru .
|
|
.B
|
|
.LI bru/test
|
|
.R
|
|
Contains some miscellaneous tests which may be of use when
|
|
porting
|
|
.IR bru .
|
|
.ig \" unused was not on our tape
|
|
.B
|
|
.LI bru/unused
|
|
.R
|
|
Contains modules which are no longer used but are kept around
|
|
for reference or possible future use.
|
|
..
|
|
.LE
|
|
.P
|
|
The other three directories are on the Release Tape are as follows:
|
|
.VL 12 4
|
|
.B
|
|
.LI dbug
|
|
.R
|
|
The source and documentation for the internal debugger
|
|
which
|
|
.I bru
|
|
uses.
|
|
.B
|
|
.LI ndir
|
|
.R
|
|
This is a public domain implementation of the BSD style directory
|
|
access library for
|
|
.B UNIX
|
|
systems with fixed format directories (V7 and System V).
|
|
System V users should install these routines in the standard
|
|
C library,
|
|
.IR /lib/libc ,
|
|
before trying to compile
|
|
.I bru
|
|
(see below).
|
|
.B
|
|
.LI rmt
|
|
.R
|
|
This is the remote magnetic tape access library for BSD systems, and
|
|
System V systems which support Berekely style networking (a remote
|
|
shell and the
|
|
.IR rmt (8)
|
|
remote magnetic tape protocol).
|
|
.LE
|
|
.H 1 "PRELIMINARY INSTALLATION INSTRUCTIONS"
|
|
.P
|
|
Before proceeding to compile and install
|
|
.I bru
|
|
itself, the following steps should be followed.
|
|
Once they have been done, follow the instructions below for determining
|
|
the particular device characteristics of your installation.
|
|
.H 2 "Installation of the Debugger"
|
|
.P
|
|
.I Bru
|
|
uses an internal debugger, whose output can be controlled at run-time.
|
|
While this debugger does increase the space and time needed to run
|
|
.IR bru ,
|
|
it's output can be so informative that
|
|
.I bru
|
|
should be compiled with the debugger included, at least initially.
|
|
If it runs without problems for a satisfactory length of time, then
|
|
it can be re-compiled without the debugger.
|
|
.P
|
|
To install the debugger, cd to the
|
|
.B dbug
|
|
directory, and run
|
|
\*(lqmake install.\*(rq
|
|
It should work correctly under both System V
|
|
and 4.2\ BSD.
|
|
.H 2 "The Remote Magnetic Tape Library"
|
|
.P
|
|
If you have a 4.2\ BSD system,
|
|
or a System V system with Berkeley style networking
|
|
(a remote shell and the
|
|
.IR rmt (8)
|
|
program),
|
|
then you should install this library if you wish to
|
|
use remote tape drives for backups.
|
|
You may have to change the call to
|
|
.I exec
|
|
in
|
|
.B rmtops.c
|
|
to use the proper remote shell.
|
|
.P
|
|
Experience seems to indicate that remote tape drives should
|
|
.I not
|
|
be put into the
|
|
.B /etc/brutab
|
|
file.
|
|
Instead, use them via the
|
|
.B \-f
|
|
command line option and let
|
|
.I bru
|
|
just treat them as unknown devices.
|
|
.H 2 "System V Specific Instructions"
|
|
.P
|
|
For portability to BSD systems which have a different directory structure,
|
|
.I bru
|
|
uses the portable directory access library.
|
|
A public domain version of this library has been supplied in the
|
|
.B ndir
|
|
directory.
|
|
System V (and System III or V7) users must compile and install these routines,
|
|
before attempting to compile and load
|
|
.IR bru .
|
|
.P
|
|
On systems with the source code, copy these routines to the source
|
|
directory for
|
|
.I /lib/libc.a
|
|
and rebuild the library.
|
|
.P
|
|
If your system does not have source code,
|
|
you can still install them.
|
|
First, make a backup copy of the library
|
|
(e.g.,
|
|
.IR /lib/liboc.a ).
|
|
Next, compile the routines,
|
|
and use
|
|
.IR ar (1)
|
|
to install the new routines at the front of the C library.
|
|
(\*(lqar cr /lib/libc.a *.o\*(rq).
|
|
If your version of System V has the
|
|
.IR ranlib (1)
|
|
command, then run it on the library, to ensure that all the
|
|
routines will be in the proper order for loading.
|
|
.P
|
|
Finally, install the
|
|
.B dir.h
|
|
file in the
|
|
.B /usr/include
|
|
directory, and be sure that it is readable.
|
|
.P
|
|
.B
|
|
If you do not install these routines then
|
|
.I bru
|
|
will not compile, and it will not load!
|
|
.R
|
|
.H 2 "4.2\ BSD Specific Instructions"
|
|
.P
|
|
4.2\ BSD systems vary in respect to these instructions. They may or may
|
|
not be necessary.
|
|
.P
|
|
Look in the
|
|
.B /usr/include
|
|
directory.
|
|
If you have files named
|
|
.B dir.h
|
|
and
|
|
.BR time.h ,
|
|
then nothing further needs to be done.
|
|
If you do not, create these files, and have them do a
|
|
.B #include
|
|
.B <sys/dir.h>
|
|
and
|
|
.B <sys/time.h>
|
|
respectively.
|
|
Alternatively, you may create them
|
|
as symbolic links to the respective files in
|
|
.BR /usr/include/sys .
|
|
.P
|
|
Rumor has it that for 4.3\ BSD,
|
|
.BR /usr/include/time.h ,
|
|
at least, will be back where it belongs.
|
|
.P
|
|
.B
|
|
Again, if you do not do this,
|
|
.I bru
|
|
will not compile!
|
|
.R
|
|
.H 1 "IMPORTANT FILES"
|
|
.P
|
|
There are several files which are of interest in configuring
|
|
.IR bru :
|
|
.VL 16 4
|
|
.B
|
|
.LI config.mk
|
|
.R
|
|
This is a
|
|
.I make
|
|
include file which is found in the root directory of the
|
|
.I bru
|
|
distribution.
|
|
This file is used by
|
|
.I make
|
|
in the various subdirectories to determine installation dependent
|
|
parameters, such as the directory for installing the executable.
|
|
It is normally built by a script in the
|
|
.B bru/config
|
|
directory.
|
|
.B
|
|
.LI config.h
|
|
.R
|
|
Contains many fundamental constants, such as the size of an archive
|
|
block, which should not be changed.
|
|
Also contains a few \*(lqtunable\*(rq constants, such as the current version
|
|
and release numbers, the default archive file name, etc.
|
|
.B
|
|
.LI devices.h
|
|
.R
|
|
Has declaration for a structure which contains information about
|
|
known system devices.
|
|
This structure is described in detail in another section.
|
|
.B
|
|
.LI brutab
|
|
.R
|
|
Contains a template for the loadable device table file.
|
|
This is the file which generally requires the most customization.
|
|
Note that the first entry is the default system backup device.
|
|
.B
|
|
.LI typedefs.h
|
|
.R
|
|
Contains
|
|
.B typedefs
|
|
(type definitions) for some of the less commonly supported
|
|
fundamental types and
|
|
for the derived types used in the source code.
|
|
.LE
|
|
.P
|
|
Be aware that the
|
|
.B UNIX
|
|
System V header files in the
|
|
.B /usr/include
|
|
and
|
|
.B /usr/include/sys
|
|
directories
|
|
are sometimes customized slightly by the various vendors
|
|
to accommodate their particular hardware.
|
|
These changes can sometimes cause problems with missing or
|
|
multiply referenced
|
|
.B #define 's.
|
|
.H 1 "THE DEVICE STRUCTURE"
|
|
.P
|
|
The file
|
|
.B devices.h
|
|
contains the definition of a structure which
|
|
contains information about known devices.
|
|
The elements of this structure and their descriptions are:
|
|
.VL 16 4
|
|
.B
|
|
.LI dv_dev
|
|
.R
|
|
Character pointer to a named system device name.
|
|
For example,
|
|
.BR /dev/rmt0 .
|
|
One of these is usually the default archive device,
|
|
which is given by the first entry in
|
|
.IR /etc/brutab .
|
|
.B
|
|
.LI dv_flags
|
|
.R
|
|
Flags for various capabilities.
|
|
Current flags include
|
|
.B D_REOPEN
|
|
for close and reopen archive device
|
|
after switching media,
|
|
.B D_ISTAPE
|
|
for device is a 9-track tape drive,
|
|
.B D_RAWTAPE
|
|
for device is a raw 9-track tape drive, and
|
|
.B D_NOREWIND
|
|
for device does not automatically rewind if device file is closed.
|
|
Some implementations require
|
|
.B D_REOPEN
|
|
to clear any error conditions set
|
|
by attempting to read past end of device, or set by switching media.
|
|
.B
|
|
.LI dv_msize
|
|
.R
|
|
Media size if known, zero if unknown.
|
|
Note that the size is in bytes, commonly given in the form
|
|
\*(lq640L * 1024L\*(rq.
|
|
.B
|
|
.LI dv_seek
|
|
.R
|
|
Minimum seek resolution, zero if no seeks allowed.
|
|
All seeks must be to integral multiples of this value.
|
|
Some implementations of raw device files do not allow seeks to
|
|
any location other than the start of a device physical sector.
|
|
In this case, the minimum resolution is the sector size.
|
|
.B
|
|
.LI dv_prerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after a partial read
|
|
at end of device.
|
|
A partial read is a read which attempts to read past end
|
|
of device and returns a number greater than zero but less
|
|
than the number of bytes requested.
|
|
.B
|
|
.LI dv_pwerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after a partial write
|
|
at end of device.
|
|
A partial write is a write which attempts to write past end
|
|
of device and returns a number greater than zero but less
|
|
than the number of bytes requested to be written.
|
|
.B
|
|
.LI dv_zrerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after a zero read
|
|
at end of device.
|
|
A zero read is a read which occurs right at the end of
|
|
device, or past end of device, and returns zero or end of file.
|
|
.B
|
|
.LI dv_zwerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after a zero write
|
|
at end of device.
|
|
A zero write is a write which occurs right at the end of
|
|
device, or past end of device, and returns zero or end of file.
|
|
.B
|
|
.LI dv_frerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after an unsuccessful attempt to
|
|
read from unformatted media.
|
|
.B
|
|
.LI dv_fwerr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after an unsuccessful attempt to
|
|
write to unformatted media.
|
|
.B
|
|
.LI dv_wperr
|
|
.R
|
|
Expected value to be found in
|
|
.B errno
|
|
after an unsuccessful attempt to
|
|
write to write-protected media.
|
|
.LE
|
|
.H 1 "DETERMINING DEVICE CHARACTERISTICS"
|
|
.P
|
|
Perhaps the simpliest method for determining some of the required table
|
|
values is to use an
|
|
.I /etc/brutab
|
|
file with only the stdin/stdout entry,
|
|
and examine the behavior of
|
|
.I bru
|
|
when used with the device in question.
|
|
See the routine
|
|
.B recover()
|
|
in the file
|
|
.BR blocks.c .
|
|
.P
|
|
Note that a reasonably functional version of
|
|
.I bru
|
|
can be built without
|
|
defining any entries in the
|
|
.I /etc/brutab
|
|
file.
|
|
However, it may exhibit rather peculiar behavior when I/O errors
|
|
occur while communicating with an unknown device.
|
|
.H 1 "MAKEFILE DEFINES"
|
|
.P
|
|
There are a number of defines which may be specified on the command
|
|
line to the
|
|
.B make
|
|
utility to control which particular flavor of
|
|
.I bru
|
|
is desired.
|
|
To make a particular version of
|
|
.IR bru ,
|
|
all that is typically needed
|
|
is a command sequence of the form:
|
|
.DS I N
|
|
cd /usr/src/cmd/bru\ \ \ # /usr/src/bin/bru on 4.2\ BSD
|
|
make -f bru.mk setup
|
|
make -f bru.mk
|
|
.DE
|
|
All of the defines are documented in the makefile
|
|
.B bru.mk
|
|
in the
|
|
.I bru
|
|
root directory, and additionally in
|
|
.B Makefile
|
|
in the
|
|
.I bru
|
|
source directory (bru/src).
|
|
Some of the more important defines are:
|
|
.VL 20 4
|
|
.B
|
|
.LI TARGET
|
|
.R
|
|
Defined for the particular target machine.
|
|
For example; CDS_U200, FPS_S2000, USI_VAX750, etc.
|
|
This define was primarily used to conditionally compile the
|
|
table entries in the known device table.
|
|
However, now that
|
|
.I bru
|
|
uses an external file, none of the code depends on its value.
|
|
.B
|
|
.LI BIN
|
|
.R
|
|
Directory where the executable version of
|
|
.I bru
|
|
is to be installed.
|
|
Default is
|
|
.BR /bin .
|
|
.B
|
|
.LI COPYRIGHT
|
|
.R
|
|
Defined if a copyright message is to be included in the output
|
|
of the internal documentation printed when
|
|
.I bru
|
|
is invoked with
|
|
the
|
|
.B \-h
|
|
argument.
|
|
.B
|
|
.LI DBUG
|
|
.R
|
|
Defined to be
|
|
.B \-DNO_DBUG
|
|
if the debugging package
|
|
.B dbug
|
|
is not available, left undefined if it is available.
|
|
.B
|
|
.LI DBUGLIB
|
|
.R
|
|
Defined to be
|
|
.B \-ldbug
|
|
if the debugging package
|
|
.B dbug
|
|
is available, left undefined if it is unavailable.
|
|
.B
|
|
.LI OS
|
|
.R
|
|
Set to some meaningful string which describes the operating system
|
|
in use, typically
|
|
.B SYSIII ,
|
|
.B SYSV ,
|
|
.B BSD4_2 ,
|
|
etc.
|
|
Default is
|
|
.BR SYSV .
|
|
.B
|
|
.LI OWN
|
|
.R
|
|
Set to the owner of the
|
|
.I bru
|
|
executable file.
|
|
Default is
|
|
.BR root .
|
|
.B
|
|
.LI GRP
|
|
.R
|
|
Set to the group of the
|
|
.I bru
|
|
executable file.
|
|
Default is
|
|
.BR bin .
|
|
.B
|
|
.LI MODE
|
|
.R
|
|
Set to the access mode of the
|
|
.I bru
|
|
executable file.
|
|
Default is
|
|
.BR 4711 .
|
|
.B
|
|
.LI NFLAG
|
|
.R
|
|
Set to
|
|
.B \-n
|
|
if the
|
|
.I bru
|
|
executable is to be linked \*(lqtext shared\*(rq.
|
|
.B
|
|
.LI IFLAG
|
|
.R
|
|
Set to
|
|
.B \-i
|
|
if the
|
|
.I bru
|
|
executable is to be linked with \*(lqsplit I&D\*(rq for PDP-11/70's or
|
|
similar type machines.
|
|
.B
|
|
.LI NET
|
|
.R
|
|
Defined to be
|
|
.B \-DNET
|
|
if the system supports the remote magnetic tape library,
|
|
left undefined if it is not available.
|
|
.B
|
|
.LI NETLIB
|
|
.R
|
|
Defined to be
|
|
.B \-lrmt
|
|
if the remote magnetic tape libary is available,
|
|
left undefined if it is not available.
|
|
.LE
|
|
.P
|
|
This may not be an exhaustive list, so consult the documentation in
|
|
the makefiles for more information.
|
|
.H 1 "NON-UNIX PORTS"
|
|
.P
|
|
There are currently no known versions of this software running under
|
|
any operating system other than
|
|
.BR UNIX .
|
|
Although it might be possible to build a subset version which could
|
|
read or write archives compatible with the
|
|
.B UNIX
|
|
version, such an
|
|
implementation would probably require extensive changes in the source.
|
|
There are no explicit hardware dependencies built into the code,
|
|
other than the previously documented device table; there are many
|
|
implicit assumptions that the software environment is
|
|
.B UNIX .
|
|
.P
|
|
Note that
|
|
.I all
|
|
system or library calls are isolated to the file
|
|
.BR sys.c ,
|
|
making
|
|
modification or substitution of runtime support functions
|
|
relatively easy.
|
|
Typically, if
|
|
.B foo()
|
|
is a library function then all
|
|
.I bru
|
|
routines
|
|
call
|
|
.BR s_foo() ,
|
|
where the function
|
|
.B s_foo()
|
|
in
|
|
.B sys.c
|
|
calls the
|
|
actual library function
|
|
.BR foo() .
|
|
.P
|
|
.I Bru
|
|
has been installed on a
|
|
.B BSD4.1
|
|
system, but only under a special system V emulation environment.
|
|
Porting directly to a
|
|
.B 4.2\ BSD
|
|
system has been done; it required moderately extensive changes in several
|
|
areas (see below).
|
|
.H 1 "COMPILER DEPENDENCIES"
|
|
.P
|
|
Not all C compilers are created equal.
|
|
If your particular compiler is a derivative of the
|
|
.B pcc
|
|
(portable C compiler)
|
|
you should have no problems.
|
|
At the current time,
|
|
.I bru
|
|
has been installed on a PDP-11/70 running standard
|
|
.B UNIX
|
|
System V,
|
|
a Convergent Technologies Miniframe (vender port of
|
|
.BR UNIX ),
|
|
a Callan Data Systems Unistar 200 (Unisoft port),
|
|
and a Four Phase Systems Series 2000 (vender port).
|
|
So far, no port has taken more than a half-day to accomplish.
|
|
.P
|
|
At Georgia Tech, ports to an AT&T 3B20S and 3B2/300 were
|
|
accomplished quickly.
|
|
Both these machines run System V Release 2.
|
|
Porting to 4.2\ BSD took quite a while (see below); this was due to
|
|
the nature of 4.2\ BSD, not to the quality of
|
|
.IR bru 's
|
|
code.
|
|
.P
|
|
The
|
|
.I bru
|
|
source code conforms to standards of Kernighan and Ritchie's
|
|
.I
|
|
The C Programming Language
|
|
.R
|
|
and, with the exception of the type
|
|
.BR void ,
|
|
does not use any extensions to the language such
|
|
as structure assignments or enumerations.
|
|
Note the file
|
|
.B typedefs.h
|
|
which contains type definitions for some of the less commonly
|
|
supported types, such as unsigned character.
|
|
Compiler problems can sometimes be circumvented with an
|
|
appropriate
|
|
.BR typedef .
|
|
.H 1 "PORTING TO 4.2 BSD"
|
|
.P
|
|
A port to 4.2\ BSD, for the DEC Vax, has just been completed.
|
|
It required numerous changes, most of which were straightforward,
|
|
but some of which were quite tricky and hard to deal with.
|
|
This section will describe the changes made and difficulties
|
|
encountered when porting to 4.2\ BSD.
|
|
This description may be useful when porting
|
|
.I bru
|
|
to other
|
|
.B UNIX
|
|
environments.
|
|
.P
|
|
The first thing that had to be fixed was the
|
|
.B Makefile
|
|
in the source directory.
|
|
The Berkeley
|
|
.I make
|
|
is the original version; it does not know how to include other makefiles.
|
|
To get around this, a shell script called
|
|
.BR MAKE ,
|
|
was created.
|
|
This script builds the
|
|
.B Makefile
|
|
using here documents, and either puts the
|
|
.B ../config.mk
|
|
file directly into the
|
|
.BR Makefile ,
|
|
or does the original's include of
|
|
.BR config.mk .
|
|
The new
|
|
.B Makefile
|
|
has
|
|
.I bru
|
|
being dependent on the
|
|
.BR Makefile ,
|
|
with the
|
|
.B Makefile
|
|
itself dependent upon
|
|
.BR MAKE .
|
|
Some new files were created, so their
|
|
associated dependencies were added to
|
|
.BR MAKE .
|
|
Finally the
|
|
.B Makefile
|
|
in the parent directory had to be changed to issue a
|
|
.B MAKE
|
|
command first.
|
|
.P
|
|
We now present a general discussion of what had to be changed for
|
|
4.2\ BSD, and then a list of the individual source files, along with
|
|
a brief description of the actual changes made.
|
|
Most changes were minor, several files were not changed at all.
|
|
.P
|
|
The one feature of 4.2\ BSD that caused the most work was getting
|
|
.I bru
|
|
to properly handle symbolic links.
|
|
A file named \*(lqsymlinks\*(rq in the
|
|
.B notes
|
|
directory describes what symbolic links are
|
|
and what the general strategy was.
|
|
Basically, the symbolic link is treated as a special file, with
|
|
only the header block written to the archive. Then a lot
|
|
of special casing code does its best to extract them, depending
|
|
on whether or not
|
|
.I bru
|
|
is running on a BSD system.
|
|
.P
|
|
4.2\ BSD does not support System V's fifos
|
|
(named pipes).
|
|
.I Bru
|
|
will extract these files as plain files, mode 0666 as
|
|
modified by the
|
|
.IR umask ,
|
|
and print a warning message.
|
|
.P
|
|
4.2\ BSD reimplemented the
|
|
.B UNIX
|
|
file system to increase file access speed.
|
|
As a result, the directory structure changed radically.
|
|
However, they defined a (fairly) clean set of library routines for
|
|
dealing with directories.
|
|
.I Bru
|
|
had to be changed to use them.
|
|
A public domain implementation of this libary for
|
|
systems with old-style directories exists, so
|
|
.I bru
|
|
can still use this library, even under System V.
|
|
.P
|
|
On BSD systems, the
|
|
.IR chown (2)
|
|
system call is restricted to the Super-user.
|
|
Since
|
|
.I bru
|
|
runs setuid to root, this isn't a problem.
|
|
However, the default behavior had been for
|
|
.I bru
|
|
to
|
|
\*(lqgive away\*(rq
|
|
the files it extracted, which could be inconvenient for an
|
|
archive moved from one machine where the
|
|
.IR uid
|
|
of the current user
|
|
was not the same on the other machine.
|
|
The user would then have to get the Super-user to
|
|
.IR chown (1)
|
|
the files back to him.
|
|
(The System V
|
|
.I tar
|
|
and
|
|
.I cpio
|
|
programs have this problem.)
|
|
To avoid this dilemma, a new
|
|
.B \-C
|
|
option was added.
|
|
By default,
|
|
.I bru
|
|
now extracts files and
|
|
.IR chown 's
|
|
them to the current user.
|
|
If
|
|
.B \-C
|
|
is given, then
|
|
.I bru
|
|
will
|
|
.I chown
|
|
the new file to the user
|
|
.I uid
|
|
and group
|
|
.I gid
|
|
given in the archive.
|
|
With or without the
|
|
.BR \-C ,
|
|
.I bru
|
|
will not restore the setuid and setgid bits if the file does not
|
|
belong to the current user, or if the user is not root.
|
|
.P
|
|
Some minor changes had to be made to fake the
|
|
.IR uname (2)
|
|
system call.
|
|
Also, instead of using
|
|
.I mknod "(2) and " link (2)
|
|
to create a new directory,
|
|
.I bru
|
|
uses the new
|
|
.IR mkdir (2)
|
|
system call.
|
|
.P
|
|
Finally, since 4.2\ BSD has networking facilities and a (primitive)
|
|
remote magnetic tape protocol for its own
|
|
.IR dump " and " restore
|
|
programs,
|
|
a remote magnetic tape library was written that allowed access
|
|
to tape drives on a remote system over the ethernet.
|
|
The library
|
|
\*(lqreplaces\*(rq
|
|
the standard
|
|
.B UNIX
|
|
system calls in a transparent fashion.
|
|
.I Bru
|
|
does not know that it is dealing with a remote device.
|
|
The
|
|
.B \-DNET
|
|
define controls the use of this facility;
|
|
a copy of this library
|
|
should also be on the Release Tape.
|
|
.P
|
|
We now go through the source code file by file.
|
|
.VL 16 4
|
|
.LI blocks.h
|
|
Changed the include of <sys/utsname.h> to just "ustname.h".
|
|
.LI config.h
|
|
Changed the ID to indicate that this was the 4.2\ BSD version,
|
|
and incremented the variant.
|
|
.LI errors.h
|
|
Added about a half dozen new error codes that have to do
|
|
with making directories, dealing with symbolic links,
|
|
and with fifos.
|
|
.LI flags.h
|
|
Added a variable for the new
|
|
.B \-C
|
|
flag.
|
|
Also added a flag for
|
|
.BR \-ul ,
|
|
unconditional extraction of symbolic links.
|
|
.LI macros.h
|
|
Added the IS_FLNK macro, which tests if a file is a symbolic link.
|
|
.LI manifest.h
|
|
Added conditional definitions of S_IFIFO and S_IFLNK, so that BSD and
|
|
System V systems can each understand the file types unique to the other.
|
|
.LI access.c
|
|
The system call
|
|
.IR access (2)
|
|
will go through symbolic links.
|
|
This behavior is wrong; we want information about the link itself,
|
|
not what it points to, and is very bad if the link points to a file
|
|
that does not happen to exist.
|
|
To get around this,
|
|
.B file_access()
|
|
now attempts a
|
|
.IR readlink (2)
|
|
first, and if it succeeds, decides whether or not to return TRUE or FALSE.
|
|
If it fails, the file is not a symbolic link, and it is safe to call
|
|
.IR access .
|
|
.LI blocks.c
|
|
Changed to include <sys/file.h> instead of <fcntl.h>; even though
|
|
BSD has an <fcntl.h> file, it is woefully incomplete.
|
|
Rumor has it that this will be fixed in 4.3\ BSD.
|
|
.LI create.c
|
|
In the
|
|
.B do_write()
|
|
routine, only set
|
|
.B "fip\ \->\ lname"
|
|
to NULL if the file being dealt with is not a symbolic link.
|
|
This is because only a file header block is written.
|
|
The name field contains the real file name, and the
|
|
link field the name of the file pointed to by the symbolic link.
|
|
.LI date.c
|
|
BSD's date, time, and time zone handling is different from System V's.
|
|
The major things to do here were to conditionalize the calling of
|
|
.BR tzset() ,
|
|
and to compute the
|
|
.B timezone
|
|
variable by hand.
|
|
.LI devices.c
|
|
Conditionalized the System V specific errors, and added in all the
|
|
BSD errors.
|
|
.LI diff.c
|
|
Added code to check for differences in the contents of symbolic links.
|
|
.LI errors.c
|
|
Added error messages for the 4.2 specific things.
|
|
.LI estimate.c
|
|
In the
|
|
.B do_estimate()
|
|
routine, only set
|
|
.B "fip\ \->\ lname"
|
|
to NULL if the file being dealt with is not a symbolic link.
|
|
See the comments above for create.c.
|
|
.LI extract.c
|
|
Changed the declaration and use of
|
|
.B mkdir()
|
|
to be
|
|
.BR newdir(),
|
|
since there is a
|
|
.B mkdir()
|
|
system call.
|
|
The layout of the
|
|
.IR stat (2)
|
|
buffer has changed; this required building a structure by hand for
|
|
passing on to
|
|
.B s_utimes()
|
|
instead of assuming that
|
|
.BR st_atime " and " st_mtime
|
|
are contiguous. Some of the checking
|
|
for hard links had to be redone to take symbolic links into account.
|
|
Next,
|
|
.B makespecial()
|
|
and
|
|
.B attributes()
|
|
had to be changed.
|
|
.B Makespecial()
|
|
has to extract fifos as regular files under 4.2\ BSD, and call a new
|
|
routine,
|
|
.BR mksymlink() ,
|
|
to extract symbolic links.
|
|
Pyramid style conditional symbolic links are handled by that routine,
|
|
as is the problem of what to do with symbolic links on an AT&T system.
|
|
.B Attributes()
|
|
had to be changed to not
|
|
.I chmod
|
|
or
|
|
.I utime
|
|
a symbolic link, since 4.2\ BSD does not allow it!
|
|
(This, of course, is very bad for a backup program, but there is nothing
|
|
to be done; those system calls would go through the link and affect the
|
|
pointed to file, which would be even worse.)
|
|
The
|
|
.I chown
|
|
system call does work.
|
|
Also, the
|
|
.I chown
|
|
had to be done before the
|
|
.I chmod
|
|
and
|
|
.IR utime ,
|
|
in order for extraction of setuid/setgid files to work correctly.
|
|
.LI fmode.c
|
|
Added S_IFLNK and 'l' to the mode printing code.
|
|
.LI globals.c
|
|
Changed
|
|
.BR "char\ *copyright" " to " "char\ copyright[]" .
|
|
Changed the <sys/utsname.h> to "utsname.h".
|
|
.LI hex.c
|
|
Conditionalized the include of <memory.h> to System V.
|
|
.LI init.c
|
|
Added the declaration and use of
|
|
.BR gp_init() .
|
|
This routine does for the group file what
|
|
.B ur_init()
|
|
does for the password file.
|
|
Also added parsing of the
|
|
.BR \-C " and " \-ul
|
|
arguments.
|
|
.LI mkdir.c
|
|
Changed the name of the
|
|
.B mkdir()
|
|
routine to be
|
|
.BR newdir() ,
|
|
and added code to use the built-in
|
|
.I mkdir
|
|
system call.
|
|
.LI readinfo.h
|
|
Added the declaration and use of
|
|
.BR gp_gname() ,
|
|
which prints out the name of a group.
|
|
.LI sys.c
|
|
As is to be expected, most of the changes were made here.
|
|
Mainly, it consisted of adding implementations for System V routines
|
|
that BSD does not have, e.g.
|
|
.B getopt
|
|
and
|
|
.BR uname .
|
|
One major thing was for
|
|
.B s_stat()
|
|
to go through
|
|
.IR lstat (2),
|
|
and not
|
|
.IR stat (2).
|
|
Added s_* interfaces for the BSD specific system calls, e.g.
|
|
.BR s_mkdir() .
|
|
This was actually the most straightforward part of the changes
|
|
for 4.2; it was done first.
|
|
.LI table.c
|
|
Changed to use
|
|
.B gp_gname()
|
|
to print the group name instead of the group
|
|
.IR gid ,
|
|
for verbose table of contents.
|
|
Added code to check for symbolic links, and to print out the appropriate
|
|
info on the link.
|
|
.LI trees.c
|
|
Changed to use the portable directory access routines (in the
|
|
.B do_dir()
|
|
routine).
|
|
.B NOTE:
|
|
The s_* names for the directory routines could conceivably conflict
|
|
with other names on C compilers which do not keep long variable names
|
|
distinct. For that reason, in this file
|
|
.BR only ,
|
|
the s_* names are
|
|
.BR #defines 's.
|
|
If your C compiler does not support
|
|
\*(lqflexnames\*(rq, remove the
|
|
.BR #defines 's,
|
|
and use the real names, without the leading
|
|
\*(lqs_.\*(rq
|
|
.LI tty.c
|
|
Conditionalized the include of <termio.h> to System V, added an
|
|
include of <sgtty.h> for BSD, and added code in
|
|
.BR tty_inflush() .
|
|
.LI usage.c
|
|
Added
|
|
.BR \-C " and " \-ul
|
|
in the appropriate places, and changed \*(lqvarient\*(rq to
|
|
\*(lqvariant.\*(rq
|
|
.LI utils.c
|
|
Made the changes described above for the
|
|
.B \-C
|
|
option.
|
|
Created a new routine,
|
|
.BR mksymlink() ,
|
|
which worries about extracting regular and Pyramid conditional
|
|
symbolic links. The decisions and testing are isolated there.
|
|
This routine went through several iterations.
|
|
.B File_stat
|
|
was changed to do a
|
|
.I readlink
|
|
on a symbolic link, and fill in the
|
|
.B lname
|
|
field of the file description structure.
|
|
.B Verbosity()
|
|
had to be changed a little to handle symbolic links,
|
|
as did the
|
|
.B unconditional()
|
|
routine.
|
|
.LE
|
|
.P
|
|
The following files did not have to be changed at all.
|
|
.DS I
|
|
.TS
|
|
l l l l
|
|
l l l l
|
|
l l l l
|
|
l.
|
|
dbug.h bru.c headers.c passwd.c
|
|
devices.h chksum.c inspect.c scan.c
|
|
exeinfo.h done.c links.c signals.c
|
|
finfo.h
|
|
.TE
|
|
.DE
|
|
.P
|
|
The following files were added for the 4.2\ BSD version.
|
|
.VL 16 4
|
|
.LI rmt.h
|
|
This file does the appropriate
|
|
.BR #define 's
|
|
for the remote magnetic tape library.
|
|
.LI utsname.h
|
|
This file declares the
|
|
.B utsname
|
|
structure, independent of operating system.
|
|
Under 4.2\ BSD, it defines the structure explicitly,
|
|
based on the System V man page.
|
|
Otherwise, it just includes <sys/utsname.h>.
|
|
.LI groups.c
|
|
This file is an edited version of passwd.c, which sets up the
|
|
same kind of interface for the
|
|
.I /etc/group
|
|
file.
|
|
This allows printing out alphabetic names for group
|
|
.IR gid 's,
|
|
instead of just numbers.
|
|
This is most useful for printing a verbose tables of contents of
|
|
an archive.
|
|
It is surprising that this was not done earlier.
|
|
.LI symlinks.c
|
|
This file contains three routines, which went through
|
|
numerous iterations and simplifications:
|
|
.VL 14
|
|
.B
|
|
.LI iscondlink()
|
|
.R
|
|
Takes a file name and returns TRUE or FALSE if the name is a Pyramid
|
|
style conditional symbolic link.
|
|
.B
|
|
.LI univlink()
|
|
.R
|
|
Depending on what kind of machine
|
|
.I bru
|
|
is compiled on, returns either the AT&T or UCB part
|
|
of a conditional symbolic link.
|
|
For simplicity in
|
|
.BR mksymlink() ,
|
|
it just returns its argument when on a Pyramid.
|
|
.B
|
|
.LI namelink()
|
|
.R
|
|
Returns a printable version of the conditional symbolic link.
|
|
This is used by the
|
|
.B verbosity ()
|
|
routine.
|
|
.LE 1
|
|
Almost all knowledge of Pyramid conditional symbolic links
|
|
is isolated here.
|
|
.LE
|
|
.P
|
|
All this work to make
|
|
.I bru
|
|
function in any of the given environments, pure 4.2 BSD, pure AT&T System V,
|
|
and the Pyramid OSx hybrid, is due to the fact that we at Georgia Tech
|
|
want to be able to use one universal backup system for all our machines,
|
|
and we have all three kinds, 4.2\ BSD Vaxen, a Pyramid 90x, and AT&T 3B20's
|
|
and 3B2's.
|
|
.P
|
|
Although 4.2\ BSD has problems with symbolic links,
|
|
the overall ease with which
|
|
.I bru
|
|
was converted is good testimony to its portability.
|
|
Determining what the proper behavior should be in any given situation
|
|
was considerably harder than actually implementing the decision.
|
|
Furthermore, the portability of archives between machines is now
|
|
increased, since
|
|
.I bru
|
|
will do its best to restore files which the particular version of
|
|
the operating system may not support (fifos and symbolic links).
|
|
.\" Who me, blow my own horn? :-)
|
|
.TC
|
|
.CS
|