source: trunk/packs/dotfiles/add.1 @ 8535

.TH ADD 1 "1 December 1994"
.ds ]W MIT Athena
.SH NAME
add - attach a filesystem, add it to your path and manpath

.SH SYNOPSIS
add [ options ] filesystemname filesystemname ...

.SH DESCRIPTION
\fIadd\fR is an alias provided by the standard Athena dotfiles.  It is
intended to make the process of using software that is stored in
remote filesystems easier.  In normal use, it requires one argument,
the name of a filesystem to \fIadd\fR.  In that case, it adds the
appropriate binary directory (arch/pmax_ul4/bin, decmipsbin, etc.) to
the end of your command search path so that you can find programs in
the locker, and adds the man directory to your MANPATH so that
\fIman\fR can find manpages that may be installed in that filesystem.
(See \fIlockers\fR(7) for suggestions on how to organize and maintain
lockers.)

When no arguments are used, \fIadd\fR will print out the (possibly
abbreviated) value of the user's PATH variable. This is equivalent to
specifying the \fI-v\fR option.

\fIadd\fR may also take multiple filesystem arguments. In this case,
\fIadd locker1 locker2 locker3\fR is functionally equivalent to,
though more efficient than, \fIadd locker1; add locker2; add
locker3\fR. Thus when adding lockers to the front of your PATH, they
will appear as \fIlocker3 locker2 locker1\fR at the front of your
PATH.

\fIadd\fR may be used interactively while logged in, or in your
~/.environment file.

Typing "alias add" will reveal that it is an alias which sources the
csh script \fI/usr/athena/lib/init/add\fR.

.SH OPTIONS
\fIadd\fR accepts the following options:
.TP 9
.B \-f
\fIadd\fR normally adds lockers to the end of your path. This option
causes it to add lockers to the front of your path instead. If the
locker is already in your path but not at the front, it will be moved
there. However, when -f is used in your ~/.environment file, it does
not affect lockers already in your path.

This is feature useful when you want to cause programs in the lockers
to replace programs found in other places, such as on the system
packs. You usually want lockers added to the end of your path,
however, to prevent the possibility of locker maintainers replacing
important binaries with things you don't expect.
.TP 9
.B \-r
This option causes \fIadd\fR to remove the specified lockers from your
path. This option has no effect when used in your ~/.environment file.
.TP 9
.B \-w
This option causes \fIadd\fR to warn you in the event a locker you have
asked to be added does not support your platform. A binary directory
will not be added to your PATH, but if a man directory exists it will
still be added to your MANPATH. \fIadd\fR normally says nothing in this
case.
.TP 9
.B \-d
This option causes \fIadd\fR to generate debugging output relating to
the changes it is making to the user's PATH and MANPATH.
.TP
.B \-v
.br
.ns
.HP 9
.B \-v0
.br
By default, \fI-v\fR causes \fIadd\fR to display the output of attach
for the user, which is normally suppressed. It also, by default, turns
on debugging output (above). If \fIadd\fR is running in \fInew\fR mode,
debugging is not turned on (see \fI-n\fR below). \fI-v0\fR never turns
on debugging output.

Verbose mode works by invoking \fIattach\fR twice - once for output to the
user, and once for output to \fIadd\fR itself to find out where the
locker is mounted.
.TP 9
.B \-n
This option specifies that \fIadd\fR should not engage in potentially
disagreeable backwards-compatibility behavior. Specifically, it causes
the \fI-v\fR option not to turn on debugging output. Additionally, the
"new" behavior of \fIadd\fR does verbose adds in a way with more reliable
output; the old way is more likely to give you inconsistent error messages
in cases where you don't have Kerberos authentication or are attempting
to attach restricted lockers you do not have access to.
.TP 9
.B \-p
This option causes \fIadd\fR to print the contents of the user's PATH. In
the case where a path element is of the form /mit/foo/arch/pmax_ul4/bin,
\fIadd\fR substitutes the string {add foo} for that path element. This
serves to shorten and make more readable the user's PATH.
.TP 9
.B \-e
This option is used for supporting the use of \fIadd\fR in the user's
~/.environment file. The user need never specify this option as that is
taken care of by a special version of the alias that is in effect when
the .environment file is run. This option causes \fIadd\fR to modify
the shell variables \fIathena_path\fR and \fIathena_manpath\fR instead
of the environment variables PATH and MANPATH as it normally does.
.TP 9
.B \-a
This option causes \fIadd\fR to pass all remaining options on the command
line directly to \fIattach\fR. This is useful for passing flags meant to
be interpreted by \fIattach\fR and not by \fIadd\fR.

.SH VARIABLES
The shell variable \fIadd_flags\fR may be set to specify default flags
that \fIadd\fR is intended to use for all commands. For example, if
you desire that attach always be verbose and give warnings for lockers
that do not have binary directories supporting your platform, you might
put a ``set add_flags = "-v -w"'' in your ~/.cshrc.mine file.

The shell variable \fIbindir\fR is used when generating old style
paths.

The environment variable \fIATHENA_SYS\fR is used to determine the
sysname value when determining path names for new style paths.

.SH FILES
.PP
/usr/athena/lib/init/cshrc    global Athena cshrc file
/usr/athena/lib/init/add      the script the add alias calls
.br
~/.cshrc                      user's cshrc file
~/.environment                user's environment file

.SH "SEE ALSO"
attach(1), athdir(1), man(1), csh(1), lockers(7)

.SH BUGS
``\fIadd\fR -a -v foo'' and other similar commands attempting to modify
the output behaviour of \fIattach\fR directly will cause \fIadd\fR to
fail.  Such options will override the -p that \fIadd\fR passes to
\fIattach\fR.  This is because \fIadd\fR does not attempt to insert
the -p between \fIattach\fR's flags and lockernames; it places it
first.

Since \fIadd\fR does not parse the arguments to \fIattach\fR, and
because \fIattach\fR may return ambiguous error codes (in the case of
attempting to attach multiple lockers), \fIadd\fR's behavior may be
suboptimal in certain situations. For example, ``\fIadd\fR -v sdjfb''
will invoke \fIattach\fR twice, even though the first time returned an
error, because it doesn't know any better.