   This file documents Taylor UUCP, version 1.05.

   Copyright (C) 1992, 1993 Ian Lance Taylor

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "Copying" are included exactly as in the
original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "Copying" may be included in
a translation approved by the author instead of in the original English.

Security
========

   This discussion of UUCP security applies only to Unix.  It is a bit
cursory; suggestions for improvement are solicited.

   UUCP is traditionally not very secure.  Taylor UUCP addresses some
security issues, but is still far from being a secure system.

   If security is very important to you, then you should not permit any
external access to your computer, including UUCP.  Any opening to the
outside world is a potential security risk.

   By default Taylor UUCP provides few mechanisms to secure local users
of the system from each other.  You can allow increased security by
putting the owner of the UUCP programs (normally `uucp') into a separate
group; the use of this is explained in the following paragraphs, which
refer to this separate group as `uucp-group'.

   When the `uucp' program is invoked to copy a file to a remote
system, it will by default copy the file into the UUCP spool directory.
When the `uux' program is used, the `-C' switch must be used to copy
the file into the UUCP spool directory.  In any case, once the file has
been copied into the spool directory, other local users will not be
able to access it.

   When a file is requested from a remote system, UUCP will only permit
it to be placed in a directory which is writable by the requesting user.
The directory must also be writable by UUCP.  A local user can create a
directory with a group of `uucp-group' and set the mode to permit group
write access.  This will allow the file be requested without permitting
it to be viewed by any other user.

   There is no provision for security for `uucp' requests (as opposed
to `uux' requests) made by a user on a remote system.  A file sent over
by a remote request may only be placed in a directory which is world
writable, and the file will be world readable and writable.  This will
permit any local user to destroy or replace the contents of the file.
A file requested by a remote system must be world readable, and the
directory it is in must be world readable.  Any local user will be able
to examine, although not necessarily modify, the file before it is sent.

   There are some security holes and race conditions that apply to the
above discussion which I will not elaborate on.  They are not hidden
from anybody who reads the source code, but they are somewhat technical
and difficult (though scarcely impossible) to exploit.  Suffice it to
say that even under the best of conditions UUCP is not completely
secure.

   For many sites, security from remote sites is a more important
consideration.  Fortunately, Taylor UUCP does provide some support in
this area.

   The greatest security is provided by always dialing out to the other
site.  This prevents anybody from pretending to be the other site.  Of
course, only one side of the connection can do this.

   If remote dialins must be permitted, then it is best if the dialin
line is used only for UUCP.  If this is the case, then you should
create a call-in password file (see Configuration File Names.) and
let `uucico' do its own login prompting.  For example, to let remote
sites log in on a port named `entry' in the port file (see port File.)
you might invoke `uucico -p entry'.  This would cause `uucico'
to enter an endless loop of login prompts and daemon executions.  The
advantage of this approach is that even if remote users break into the
system by guessing or learning the password, they will only be able to
do whatever `uucico' permits them to do.  They will not be able to
start a shell on your system.

   If remote users can dial in and log on to your system, then you have
a security hazard more serious than that posed by UUCP.  But then, you
probably knew that already.

   Once your system has connected with the remote UUCP, there is a fair
amount of control you can exercise.  You can use the `remote-send' and
`remote-receive' commands to control the directories the remote UUCP
can access.  You can use the `request' command to prevent the remote
UUCP from making any requests of your system at all; however, if you do
this it will not even be able to send you mail or news.  If you do
permit remote requests, you should be careful to restrict what commands
may be executed at the remote system's request.  The default is `rmail'
and `rnews', which will suffice for most systems.

   If different remote systems call in and they must be granted
different privileges (perhaps some systems are within the same
organization and some are not) then the `called-login' command should
be used for each system to require that they different login names.
Otherwise it would be simple for a remote system to use the `myname'
command and pretend to be a different system.  The `sequence' command
can be used to detect when one system pretended to be another, but
since the sequence numbers must be reset manually after a failed
handshake this can sometimes be more trouble than it's worth.

UUCP protocol internals
***********************

   This chapter describes how the various UUCP protocols work, and
discusses some other internal UUCP issues.

   This chapter is quite technical.  You do not need to understand it,
or even read it, in order to use Taylor UUCP.  It is intended for people
who are interested in how UUCP code works.

   This chapter is also, unfortunately, somewhat out of date, although I
believe that is incomplete rather than inaccurate.  I post this
information to the newsgroups `comp.mail.uucp' and `news.answers' each
month; if you want to write code based on this information, please get
the most recent copy.

   Most of the discussion covers the protocols used by all UUCP
packages, not just Taylor UUCP.  Any information specific to Taylor
UUCP is indicated as such.  There are some pointers to the actual
functions in the Taylor UUCP source code, for those who are extremely
interested in actual UUCP implementation.

UUCP Grades
===========

   Modern UUCP packages support grades for each command.  The grades
generally range from `A' (the highest) to `Z' followed by `a' to `z'.
Taylor UUCP also supports `0' to `9' before `A'.  Some UUCP packages
may permit any ASCII character as a grade.

   On Unix, these grades are encoded in the name of the command file.  A
command file name generally has the form

     C.nnnngssss

where NNNN is the remote system name for which the command is queued, G
is a single character grade, and SSSS is a four character sequence
number.  For example, a command file created for the system `airs' at
grade `Z' might be named

     C.airsZ2551

   The remote system name will be truncated to seven characters, to
ensure that the command file name will fit in the 14 character file
name limit of the traditional Unix file system.  UUCP packages which
have no other means of distinguishing which command files are intended
for which systems thus require all *systems they connect to* to have
names that are unique in the first seven characters.  Some UUCP
packages use a variant of this format which truncates the system name
to six characters.  HDB uses a different spool directory format, which
allows up to fourteen characters to be used for each system name.  The
Taylor UUCP spool directory format is configurable.  The new Taylor
spool directory format permits system names to be as long as file
names; the maximum length of a file name depends on the particular Unix
file system being used.

   The sequence number in the command file name may be a decimal
integer, or it may be a hexadecimal integer, or it may contain any
alphanumeric character.  Different UUCP packages are different.

   Taylor UUCP creates command files in the function
`zsysdep_spool_commands'.  The file name is constructed by the function
`zsfile_name', which knows about all the different types of spool
directories supported by Taylor UUCP.  The Taylor UUCP sequence number
can contain any alphanumeric character; the next sequence number is
determined by the function `fscmd_seq'.

   I do not know how command grades are handled in non-Unix UUCP
packages.

   Modern UUCP packages allow you to restrict file transfer by grade
depending on the time of day.  Typically this is done with a line in
the `Systems' (or `L.sys') file like this:

     airs Any/Z,Any2305-0855 ...

   This allows only grades `Z' and above to be transferred at any time.
Lower grades may only be transferred at night.  I believe that this
grade restriction applies to local commands as well as to remote
commands, but I am not sure.  It may only apply if the UUCP package
places the call, not if it is called by the remote system.  Taylor UUCP
can use the `timegrade' and `call-timegrade' commands (see When to Call.)
to achieve the same effect (and supports the above format when
reading `Systems' or `L.sys').

   This sort of grade restriction is most useful if you know what grades
are being used at the remote site.  The default grades used depend on
the UUCP package.  Generally `uucp' and `uux' have different defaults.
A particular grade can be specified with the `-g' option to `uucp' or
`uux'.  For example, to request execution of rnews on airs with grade
`d', you might use something like

     uux -gd - airs!rnews <article

   `uunet' queues up mail at grade `Z' and news at grade `d'.  The
example above would allow mail to be received at any time, but would
only permit news to be transferred at night.

UUCP Lock File Format
=====================

   This discussion applies only to Unix.  I have no idea how UUCP locks
ports on other systems.

   UUCP creates files to lock serial ports and systems.  On most (if not
all) systems, these same lock files are also used by cu to coordinate
access to serial ports.  On some systems getty also uses these lock
files.

   The lock file normally contains the process ID of the locking
process.  This makes it easy to determine whether a lock is still
valid.  The algorithm is to create a temporary file and then link it to
the name that must be locked.  If the link fails because a file with
that name already exists, the existing file is read to get the process
ID.  If the process still exists, the lock attempt fails.  Otherwise
the lock file is deleted and the locking algorithm is retried.

   Older UUCP packages put the lock files in the main UUCP spool
directory, /usr/spool/uucp.  HDB UUCP generally puts the lock files in
a directory of their own, usually /usr/spool/locks or /etc/locks.

   The original UUCP lock file format encoded the process ID as a four
byte binary number.  The order of the bytes was host-dependent.  HDB
UUCP stores the process ID as a ten byte ASCII decimal number, with a
trailing newline.  For example, if process 1570 holds a lock file, it
would contain the eleven characters space, space, space, space, space,
space, one, five, seven, zero, newline.  Some versions of UUCP add a
second line indicating which program created the lock (uucp, cu, or
getty).  I have also seen a third type of UUCP lock file which did not
contain the process ID at all.

   The name of the lock file is generally "LCK.." followed by the base
name of the device.  For example, to lock /dev/ttyd0 the file LCK..ttyd0
would be created.  There are various exceptions.  On SCO Unix, the lock
file name is always forced to lower case even if the device name has
upper case letters.  System V Release 4 UUCP forms the lock file name
using the major and minor device numbers rather than the device name
(this is pretty sensible if you think about it).

   Taylor UUCP can be configured to use various different types of
locking.  The actual locking code is in the function `fsdo_lock'.

The Common UUCP Protocol
========================

   The UUCP protocol is a conversation between two UUCP packages.  A
UUCP conversation consists of three parts: an initial handshake, a
series of file transfer requests, and a final handshake.

   Before the initial handshake, the caller will usually have logged in
the called machine and somehow started the UUCP package there.  On Unix
this is normally done by setting the shell of the login name used to
`uucico'.

Initial Handshake
-----------------

   All messages in the initial handshake begin with a `^P' (a byte with
the octal value \020) and end with a null byte (\000).

   Taylor UUCP implements the initial handshake for the calling machine
in `fdo_call', and for the called machine in `faccept_call'.

   The initial handshake goes as follows.  It is begun by the called
machine.

called: `\020Shere=HOSTNAME\000'
     The HOSTNAME is the UUCP name of the called machine.  Older UUCP
     packages do not output it, and simply send `\020Shere\000'.

caller: `\020SHOSTNAME OPTIONS\000'
     The HOSTNAME is the UUCP name of the calling machine.  The
     following OPTIONS may appear (or there may be none):

    `-QSEQ'
          Report sequence number for this conversation.  The sequence
          number is stored at both sites, and incremented after each
          call.  If there is a sequence number mismatch, something has
          gone wrong (somebody may have broken security by pretending
          to be one of the machines) and the call is denied.  If the
          sequence number changes on one of the machines, perhaps
          because of an attempted breakin or because a disk backup was
          restored, the sequence numbers on the two machines must be
          reconciled manually.

    `-xLEVEL'
          Requests the called system to set its debugging level to the
          specified value.  This is not supported by all systems.
          Taylor UUCP currently never generates this switch.  When it
          sees it, it restricts the value according to
          `max-remote-debug' (see Miscellaneous (sys).).

    `-pGRADE'
    `-vgrade=GRADE'
          Requests the called system to only transfer files of the
          specified grade or higher.  This is not supported by all
          systems.  Some systems support `-p', some support `-vgrade='.
          Taylor UUCP supports both.

    `-R'
          Indicates that the calling UUCP understands how to restart
          failed file transmissions.  Supported only by System V
          Release 4 UUCP.

    `-ULIMIT'
          Reports the `ulimit' value of the calling UUCP.  The limit is
          specified as a base 16 number in C notation (e.g.,
          `-U0x1000000').  This number is the number of 512 byte blocks
          in the largest file which the calling UUCP can create.  The
          called UUCP may not transfer a file larger than this.
          Supported by System V Release 4 UUCP.  Taylor UUCP
          understands this option, but never generates it.

    `-N'
          Indicates that the calling UUCP understands the Taylor UUCP
          size limiting extensions.  Supported only by Taylor UUCP.

called: `\020ROK\000'
     There are actually several possible responses.

    `ROK'
          The calling UUCP is acceptable, and the handshake proceeds to
          the protocol negotiation.  Some options may also appear; see
          below.

    `ROKN'
          The calling UUCP is acceptable, it specified `-N', and the
          called UUCP also understands the Taylor UUCP size limiting
          extensions.  Supported only by Taylor UUCP.

    `RLCK'
          The called UUCP already has a lock for the calling UUCP,
          which normally indicates the two machines are already
          communicating.

    `RCB'
          The called UUCP will call back.  This may be used to avoid
          impostors.  Note that only one machine out of each pair
          should call back, or no conversation will ever begin.

    `RBADSEQ'
          The call sequence number is wrong (see the `-Q' discussion
          above).

    `RLOGIN'
          The calling UUCP is using the wrong login name.

    `RYou are unknown to me'
          The calling UUCP is not known to the called UUCP, and the
          called UUCP does not permit connections from unknown systems.

     If the response is `ROK', the following options are supported by
     System V Release 4 UUCP.

    `-R'
          The called UUCP knows how to restart failed file
          transmissions.

    `-ULIMIT'
          Reports the ulimit value of the called UUCP.  The limit is
          specified as a base 16 number in C notation.  This number is
          the number of 512 byte blocks in the largest file which the
          called UUCP can create.  The calling UUCP may not send a file
          larger than this.

    `-xLEVEL'
          I'm told that this is sometimes sent by SVR4 UUCP, but I'm
          not sure exactly what it means.  It may request the calling
          UUCP to set its debugging level to the specified value.

     If the response is not `ROK' (or `ROKN') both sides hang up the
     phone, abandoning the call.

called: `\020PPROTOCOLS\000'
     The `P' is a literal character.  Note that the called UUCP outputs
     two strings in a row.  The PROTOCOLS string is a list of UUCP
     protocols supported by the caller.  Each UUCP protocol has a single
     character name.  For example, the called UUCP might send
     `\020Pgf\000'.

caller: `\020UPROTOCOL\000'
     The `U' is a literal character.  The calling UUCP selects which
     PROTOCOL to use out of the protocols offered by the called UUCP.
     If there are no mutually supported protocols, the calling UUCP
     sends `\020UN\000' and both sides hang up the phone.  Otherwise the
     calling UUCP sends something like `\020Ug\000'.

   Most UUCP packages will consider each locally supported protocol in
turn and select the first one supported by the called UUCP.  With some
versions of HDB UUCP, this can be modified by giving a list of protocols
after the device name in the Devices file or the `Systems' file.
Taylor UUCP provides the `protocol' command which may be used either
for a system (see Protocol Selection.) or a port (see port File.).

   After the protocol has been selected and the initial handshake has
been completed, both sides turn on the selected protocol.  For some
protocols (notably `g') a further handshake is done at this point.

   Each protocol supports a method for sending a command to the remote
system.  This method is used to transmit a series of commands between
the two UUCP packages.  At all times, one package is the master and the
other is the slave.  Initially, the calling UUCP is the master.

   If a protocol error occurs during the exchange of commands, both
sides move immediately to the final handshake.

File Requests
-------------

   The master will send one of four commands: `S', `R', `X' or `H'.

   Any file name referred to below is either an absolute pathname
beginning with `/', a public directory pathname beginning with `~/', a
pathname relative to a user's home directory beginning with `~USER/',
or a spool directory file name.  File names in the spool directory are
not pathnames, but instead are converted to pathnames within the spool
directory by UUCP.  They always begin with `C.' (for a command file
created by `uucp' or `uux'), `D.' (for a data file created by `uucp',
`uux' or by an execution, or received from another system for an
execution), or `X.' (for an execution file created by `uux' or received
from another system).

   Taylor UUCP chooses which request to send next in the function
`fuucp'.  This is also where Taylor UUCP processes incoming commands
from the remote system.

S Request
.........

   master: `S FROM TO USER -OPTIONS TEMP MODE NOTIFY SIZE'

   The `S' and the `-' are literal characters.  This is a request by
the master to send a file to the slave.  Taylor UUCP handles the `S'
request in the file `send.c'.

FROM
     The name of the file to send.  If the `C' option does not appear in
     OPTIONS, the master will actually open and send this file.
     Otherwise the file has been copied to the spool directory, where
     it is named TEMP.  The slave ignores this field unless TO is a
     directory, in which case the basename of FROM will be used as the
     file name.  If FROM is a spool directory filename, it must be a
     data file created for or by an execution, and must begin with `D.'.

TO
     The name to give the file on the slave.  If this field names a
     directory the file is placed within that directory with the
     basename of FROM.  A name ending in `/' is taken to be a directory
     even if one does not already exist with that name.  If TO begins
     with `X.', an execution file will be created on the slave.
     Otherwise, if TO begins with `D.' it names a data file to be used
     by some execution file.  Otherwise, TO should not be in the spool
     directory.

USER
     The name of the user who requested the transfer.

OPTIONS
     A list of options to control the transfer.  The following options
     are defined (all options are single characters):

    `C'
          The file has been copied to the spool directory (the master
          should use TEMP rather than FROM).

    `c'
          The file has not been copied to the spool directory (this is
          the default).

    `d'
          The slave should create directories as necessary (this is the
          default).

    `f'
          The slave should not create directories if necessary, but
          should fail the transfer instead.

    `m'
          The master should send mail to USER when the transfer is
          complete.

    `n'
          The slave should send mail to NOTIFY when the transfer is
          complete.

TEMP
     If the `C' option appears in OPTIONS, this names the file to be
     sent.  Otherwise if FROM is in the spool directory, TEMP is the
     same as FROM.  Otherwise TEMP is a dummy string, normally `D.0'.
     After the transfer has been succesfully completed, the master will
     delete the file TEMP.

MODE
     This is an octal number giving the mode of the file on the master.
     If the file is not in the spool directory, the slave will always
     create it with mode 0666, except that if (MODE & 0111) is not zero
     (the file is executable), the slave will create the file with mode
     0777.  If the file is in the spool directory, some UUCP packages
     will use the algorithm above and some will always create the file
     with mode 0600 (Taylor UUCP does the latter).

NOTIFY
     This field is only used if the `n' option appears in OPTIONS.
     Otherwise, it may not appear, or it may be the string `dummy', or
     it may simply be a pair of double quotes.  If the `n' option is
     specified, then when the transfer is successfully completed the
     slave will send mail to NOTIFY, which must be a legal mailing
     address on the slave.

SIZE
     This field is only present when doing size negotiation, either with
     Taylor UUCP or SVR4 UUCP.  It is the size of the file in bytes.
     SVR4 UUCP sends the size in base 16 as 0x... while Taylor UUCP
     sends the size as a decimal integer (a later version of Taylor
     UUCP will probably change to the SVR4 behaviour).

   The slave then responds with an S command response.

`SY START'
     The slave is willing to accept the file, and file transfer begins.
     The START field will only be present when using SVR4 file
     restart.  It specifies the byte offset into the file at which to
     start sending.  If this is a new file, START will be 0x0.

`SN2'
     The slave denies permission to transfer the file.  This can mean
     that the destination directory may not be accessed, or that no
     requests are permitted.  It implies that the file transfer will
     never succeed.

`SN4'
     The slave is unable to create the necessary temporary file.  This
     implies that the file transfer might succeed later.

`SN6'
     This is only used by Taylor UUCP size negotiation.  It means that
     the slave considers the file too large to transfer at the moment,
     but it may be possible to transfer it at some other time.

`SN7'
     This is only used by Taylor UUCP size negotiation.  It means that
     the slave considers the file too large to ever transfer.

   If the slave responds with `SY', a file transfer begins.  When the
file transfer is complete, the slave sends a `C' command response.
Taylor UUCP generates this confirmation in `fprecfile_confirm' and
checks it in `fpsendfile_confirm'.

`CY'
     The file transfer was successful.

`CN5'
     The temporary file could not be moved into the final location.
     This implies that the file transfer will never succeed.

   After the `C' command response has been received (in the `SY' case)
or immediately (in an `SN' case) the master will send another command.

R Request
.........

   master: `R FROM TO USER -OPTIONS SIZE'

   The `R' and the `-' are literal characters.  This is a request by
the master to receive a file from the slave.  I do not know how SVR4
UUCP implements file transfer restart in this case.  Taylor UUCP
implements the `R' request in the file `rec.c'.

FROM
     This is the name of the file on the slave which the master wishes
     to receive.  It must not be in the spool directory, and it may not
     contain any wildcards.

TO
     This is the name of the file to create on the master.  I do not
     believe that it can be a directory.  It may only be in the spool
     directory if this file is being requested to support an execution
     either on the master or on some system other than the slave.

USER
     The name of the user who requested the transfer.

OPTIONS
     A list of options to control the transfer.  The following options
     are defined (all options are single characters):

    `d'
          The master should create directories as necessary (this is
          the default).

    `f'
          The master should not create directories if necessary, but
          should fail the transfer instead.

    `m'
          The master should send mail to USER when the transfer is
          complete.

SIZE
     This only appears if Taylor UUCP size negotiation is being used.
     It specifies the largest file which the master is prepared to
     accept (when using SVR4 UUCP, this was specified in the `-U'
     option during the initial handshake).

   The slave then responds with an `R' command response.

`RY MODE'
     The slave is willing to send the file, and file transfer begins.
     mODE is the octal mode of the file on the slave.  The master uses
     this to set the mode of the file on the master's system just as the
     slave does the MODE argument in the send command (see S Request.).

`RN2'
     The slave is not willing to send the file, either because it is not
     permitted or because the file does not exist.  This implies that
     the file request will never succeed.

`RN6'
     This is only used by Taylor UUCP size negotiation.  It means that
     the file is too large to send, either because of the size limit
     specifies by the master or because the slave considers it too
     large.  The file transfer might succeed later, or it might not
     (this will be cleared up in a later release of Taylor UUCP).

   If the slave responds with `RY', a file transfer begins.  When the
file transfer is complete, the master sends a `C' command.  The slave
pretty much ignores this, although it may log it.  Taylor UUCP sends
this confirmation in `fprecfile_confirm' and checks it in
`fpsendfile_confirm'.

`CY'
     The file transfer was successful.

`CN5'
     The temporary file could not be moved into the final location.

   After the `C' command response has been sent (in the `RY' case) or
immediately (in an `RN' case) the master will send another command.

X Request
.........

   master: `X FROM TO USER -OPTIONS'

   The `X' and the `-' are literal characters.  This is a request by
the master to, in essence, execute `uucp' on the slave.  The slave
should execute `uucp FROM TO'.  Taylor UUCP handles the `X' request in
the file `xcmd.c'.

FROM
     This is the name of the file or files on the slave which the master
     wishes to transfer.  Any wildcards are expanded on the slave.  If
     the master is requesting that the files be transferred to itself,
     the request would normally contain wildcard characters, since
     otherwise an `R' command would suffice.  The master can also use
     this command to request that the slave transfer files to a third
     system.

TO
     This is the name of the file or directory to which the files
     should be transferred.  This will normally use a UUCP name.  For
     example, if the master wishes to receive the files itself, it
     would use `MASTER!PATH'.

USER
     The name of the user who requested the transfer.

OPTIONS
     A list of options to control the transfer.  It is not clear which,
     if any, options are supported by most UUCP packages.  Taylor UUCP
     ignores the options field.

   The slave then responds with an X command response.

`XY'
     The request was accepted, and the appropriate file transfer
     commands have been queued up for later processing.

`XN'
     The request was denied.  No particular reason is given.

   In either case, the master will then send another command.

H Request
.........

   master: `H'

   This is used by the master to hang up the connection.  The slave will
respond with an `H' command response.

`HY'
     The slave agrees to hang up the connection.  In this case the
     master sends another `HY' command.  In some UUCP packages,
     including Taylor UUCP, the slave will then send a third `HY'
     command.  At this point the protocol is shut down, and the final
     handshake is begun.

`HN'
     The slave does not agree to hang up.  In this case the master and
     the slave exchange roles.  The next command will be sent by the
     former slave, which is the new master.  The roles may be reversed
     several times during a single connection.

Final Handshake
---------------

   After the protocol has been shut down, the final handshake is
performed.  This handshake has no real purpose, and some UUCP packages
simply drop the connection rather than do it (in fact, some will drop
the connection immediately after both sides agree to hangup, without
even closing down the protocol).

caller: `\020OOOOOO\000'
called: `\020OOOOOOO\000'
   That is, the calling UUCP sends six letter O's and the called UUCP
replies with seven letter O's.  Some UUCP packages always send six O's.

The UUCP `g' Protocol
=====================

   The `g' protocol is a packet based flow controlled error correcting
protocol that requires an eight bit clear connection.  It is the
original UUCP protocol, and is supported by all UUCP implementations.
Many implementations of it are only able to support small window and
packet sizes, specifically a window size of 3 and a packet size of 64
bytes, but the protocol itself can support up to a window size of 7 and
a packet size of 4096 bytes.  Complaints about the inefficiency of the
`g' protocol generally refer to specific implementations, rather than
the correctly implemented protocol.

   The `g' protocol was originally designed for general packet drivers,
and thus contains some features that are not used by UUCP, including an
alternate data channel and the ability to renegotiate packet and window
sizes during the communication session.

   The `g' protocol is spoofed by many Telebit modems.  When spoofing is
in effect, each Telebit modem uses the `g' protocol to communicate with
the attached computer, but the data between the modems is sent using a
Telebit proprietary error correcting protocol.  This allows for very
high throughput over the Telebit connection, which, because it is
half-duplex, would not normally be able to handle the `g' protocol very
well at all.

   This discussion of the `g' protocol explains how it works, but does
not discuss useful error handling techniques.  Some discussion of this
can be found in Jamie E. Hanrahan's paper (see Documentation References.).
A detailed examination of the source code would also be
profitable.

   The Taylor UUCP code to handle the `g' protocol is in the file
`protg.c'.  There are a number of functions; the most important ones
are `fgstart', `fgsend_control', `fgsenddata', and `fgprocess_data'.

   All `g' protocol communication is done with packets.  Each packet
begins with a six byte header.  Control packets consist only of the
header.  Data packets contain additional data.

   The header is as follows:

`\020'
     Every packet begins with a `^P'.

K (1 <= K <= 9)
     The K value is always 9 for a control packet.  For a data packet,
     the K value indicates how much data follows the six byte header.
     The amount of data is 2 ** (K + 4), where ** indicates
     exponentiation.  Thus a K value of 1 means 32 data bytes and a K
     value of 8 means 4096 data bytes.  The K value for a data packet
     must be between 1 and 8 inclusive.

checksum low byte
checksum high byte
     The checksum value is described below.

control byte
     The control byte indicates the type of packet, and is described
     below.

xor byte
     This byte is the xor of K, the checksum low byte, the checksum
     high byte and the control byte (i.e. the second, third, fourth and
     fifth header bytes).  It is used to ensure that the header data is
     valid.

   The control byte in the header is composed of three bit fields,
referred to here as TT (two bits), XXX (three bits) and YYY (three
bits).  The complete byte is TTXXXYYY, or (TT << 6) + (XXX << 3) + YYY.

   The TT field takes on the following values:

0
     This is a control packet.  In this case the K byte in the header
     must be 9.  The XXX field indicates the type of control packet;
     the types are described below.

1
     This is an alternate data channel packet.  This is not used by
     UUCP.

2
     This is a data packet, and the entire contents of the attached data
     field (whose length is given by the K byte in the header) are
     valid.  The XXX and YYY fields are described below.

3
     This is a short data packet.  Let the length of the data field (as
     given by the K byte in the header) be `l'.  Let the first byte in
     the data field be `b1'.  If `b1' is less than 128 (if the most
     significant bit of `b1' is 0), then there are `l - b1' valid bytes
     of data in the data field, beginning with the second byte.  If `b1
     >= 128', let `b2' be the second byte in the data field.  Then
     there are `l - ((b1 & 0x7f) + (b2 << 7))' valid bytes of data in
     the data field, beginning with the third byte.  In all cases `l'
     bytes of data are sent (and all data bytes participate in the
     checksum calculation) but some of the trailing bytes may be
     dropped by the receiver.  The XXX and YYY fields are described
     below.

   In a data packet (short or not) the XXX field gives the sequence
number of the packet.  Thus sequence numbers can range from 0 to 7,
inclusive.  The YYY field gives the sequence number of the last
correctly received packet.

   Each communication direction uses a window which indicates how many
unacknowledged packets may be transmitted before waiting for an
acknowledgement.  The window may range from 1 to 7 packets, and may be
different in each direction. For example, if the window is 3 and the
last packet acknowledged was packet number 6, packet numbers 7, 0 and 1
may be sent but the sender must wait for an acknowledgement before
sending packet number 2.  This acknowledgement could come as the YYY
field of a data packet or as the YYY field of a `RJ' or `RR' control
packet (described below).

   Each packet must be transmitted in order (the sender may not skip
sequence numbers).  Each packet must be acknowledged, and each packet
must be acknowledged in order.

   In a control packet, the XXX field takes on the following values:

1 `CLOSE'
     The connection should be closed immediately.  This is typically
     sent when one side has seen too many errors and wants to give up.
     It is also sent when shutting down the protocol.  If an unexpected
     `CLOSE' packet is received, a `CLOSE' packet should be sent in
     reply and the `g' protocol should halt, causing UUCP to enter the
     final handshake.

2 `RJ' or `NAK'
     The last packet was not received correctly.  The YYY field
     contains the sequence number of the last correctly received packet.

3 `SRJ'
     Selective reject.  The YYY field contains the sequence number of a
     packet that was not received correctly, and should be
     retransmitted.  This is not used by UUCP, and most implementations
     will not recognize it.  Taylor UUCP will recognize it but not
     generate it.

4 `RR' or `ACK'
     Packet acknowledgement.  The YYY field contains the sequence
     number of the last correctly received packet.

5 `INITC'
     Third initialization packet.  The YYY field contains the maximum
     window size to use.

6 `INITB'
     Second initialization packet.  The YYY field contains the packet
     size to use.  It requests a size of 2 ** (YYY + 5).  Note that
     this is not the same coding used for the K byte in the packet
     header (it is 1 less).  Some UUCP implementations can handle any
     packet size up to that specified; some can only handled exactly
     the size specified.  Taylor UUCP will always accept any packet
     size.

7 `INITA'
     First initialization packet.  The YYY field contains the maximum
     window size to use.

   To compute the checksum, call the control byte (the fifth byte in the
header) `c'.

   The checksum of a control packet is simply `0xaaaa - c'.

   The checksum of a data packet is `0xaaaa - (CHECK ^ c)' (`^' denotes
exclusive or, as in C), and `CHECK' is the result of the following
routine run on the contents of the data field (every byte in the data
field participates in the checksum, even for a short data packet).
Below is the routine used by Taylor UUCP; it is a slightly modified
version of a routine which John Gilmore patched from G.L.  Chesson's
original paper.  The `z' argument points to the data and the `c'
argument indicates how much data there is.

     int
     igchecksum (z, c)
          register const char *z;
          register int c;
     {
       register unsigned int ichk1, ichk2;

       ichk1 = 0xffff;
       ichk2 = 0;

       do
         {
           register unsigned int b;

           /* Rotate ichk1 left.  */
           if ((ichk1 & 0x8000) == 0)
             ichk1 <<= 1;
           else
             {
               ichk1 <<= 1;
               ++ichk1;
             }

           /* Add the next character to ichk1.  */
           b = *z++ & 0xff;
           ichk1 += b;

           /* Add ichk1 xor the character position in the buffer
              counting from the back to ichk2.  */
           ichk2 += ichk1 ^ c;

           /* If the character was zero, or adding it to ichk1
              caused an overflow, xor ichk2 to ichk1.  */
           if (b == 0 || (ichk1 & 0xffff) < b)
             ichk1 ^= ichk2;
         }
       while (--c > 0);

       return ichk1 & 0xffff;
     }

   When the `g' protocol is started, the calling UUCP sends an INITA
control packet with the window size it wishes the called UUCP to use.
The called UUCP responds with an INITA packet with the window size it
wishes the calling UUCP to use.  Pairs of INITB and INITC packets are
then similarly exchanged.  When these exchanges are completed, the
protocol is considered to have been started.  The window size is sent
twice, with both the INITA and the INITC packets.

   When a UUCP package transmits a command, it sends one or more data
packets.  All the data packets will normally be complete, although some
UUCP packages may send the last one as a short packet.  The command
string is sent with a trailing null byte, to let the receiving package
know when the command is finished.  Some UUCP packages require the last
byte of the last packet sent to be null, even if the command ends
earlier in the packet.  Some packages may require all the trailing bytes
in the last packet to be null, but I have not confirmed this.

   When a UUCP package sends a file, it will send a sequence of data
packets.  The end of the file is signalled by a short data packet
containing zero valid bytes (it will normally be preceeded by a short
data packet containing the last few bytes in the file).

   Note that the sequence numbers cover the entire communication
session, including both command and file data.

   When the protocol is shut down, each UUCP package sends a `CLOSE'
control packet.

The UUCP `f' Protocol
=====================

   The `f' protocol is a seven bit protocol which checksums an entire
file at a time.  It only uses the characters between \040 and \176
(ASCII space and `~') inclusive as well as the carriage return
character.  It can be very efficient for transferring text only data,
but it is very inefficient at transferring eight bit data (such as
compressed news).  It is not flow controlled, and the checksum is fairly
insecure over large files, so using it over a serial connection requires
handshaking (`XON'/`XOFF' can be used) and error correcting modems.
Some people think it should not be used even under those circumstances.

   I believe the `f' protocol originated in BSD versions of UUCP.  It
was originally intended for transmission over X.25 PAD links.

   The Taylor UUCP code for the `f' protocol is in `protf.c'.

   The `f' protocol has no startup or finish protocol.  However, both
sides typically sleep for a couple of seconds before starting up,
because they switch the terminal into `XON'/`XOFF' mode and want to
allow the changes to settle before beginning transmission.

   When a UUCP package transmits a command, it simply sends a string
terminated by a carriage return.

   When a UUCP package transmits a file, each byte b of the file is
translated according to the following table:

            0 <= b <=  037: 0172, b + 0100 (0100 to 0137)
          040 <= b <= 0171:       b        ( 040 to 0171)
         0172 <= b <= 0177: 0173, b - 0100 ( 072 to  077)
         0200 <= b <= 0237: 0174, b - 0100 (0100 to 0137)
         0240 <= b <= 0371: 0175, b - 0200 ( 040 to 0171)
         0372 <= b <= 0377: 0176, b - 0300 ( 072 to  077)

   That is, a byte between \040 and \171 inclusive is transmitted as is,
and all other bytes are prefixed and modified as shown.

   When all the file data is sent, a seven byte sequence is sent: two
bytes of \176 followed by four ASCII bytes of the checksum as printed
in base 16 followed by a carriage return.  For example, if the checksum
was 0x1234, this would be sent: "\176\1761234\r".

   The checksum is initialized to 0xffff.  For each byte that is sent
it is modified as follows (where `b' is the byte before it has been
transformed as described above):

     /* Rotate the checksum left.  */
     if ((ichk & 0x8000) == 0)
       ichk <<= 1;
     else
       {
         ichk <<= 1;
         ++ichk;
       }

     /* Add the next byte into the checksum.  */
     ichk += b;

   When the receiving UUCP sees the checksum, it compares it against its
own calculated checksum and replies with a single character followed by
a carriage return.

`G'
     The file was received correctly.

`R'
     The checksum did not match, and the file should be resent from the
     beginning.

`Q'
     The checksum did not match, but too many retries have occurred and
     the communication session should be abandoned.

   The sending UUCP checks the returned character and acts accordingly.

The UUCP `t' Protocol
=====================

   The `t' protocol is intended for TCP links.  It does no error
checking or flow control, and requires an eight bit clear channel.

   I believe the `t' protocol originated in BSD versions of UUCP.

   The Taylor UUCP code for the `t' protocol is in `prott.c'.

   When a UUCP package transmits a command, it first gets the length of
the command string, C.  It then sends ((C / 512) + 1) * 512 bytes (the
smallest multiple of 512 which can hold C bytes plus a null byte)
consisting of the command string itself followed by trailing null bytes.

   When a UUCP package sends a file, it sends it in blocks.  Each block
contains at most 1024 bytes of data.  Each block consists of four bytes
containing the amount of data in binary (most significant byte first,
the same format as used by the Unix function `htonl') followed by that
amount of data.  The end of the file is signalled by a block containing
zero bytes of data.

The UUCP `e' Protocol
=====================

   The `e' protocol is similar to the `t' protocol.  It does no flow
control or error checking and is intended for use over TCP.

   The `e' protocol originated in versions of HDB UUCP.

   The Taylor UUCP code for the `e' protocol is in `prote.c'.

   When a UUCP package transmits a command, it simply sends the command
as an ASCII string terminated by a null byte.

   When a UUCP package transmits a file, it sends the complete size of
the file as an ASCII decimal number.  The ASCII string is padded out to
20 bytes with null bytes (i.e., if the file is 1000 bytes long, it sends
`1000\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0').  It then sends the entire file.

The UUCP `x' Protocol
=====================

   I believe that the `x' protocol was intended for use over X.25
virtual circuits.  It relies on a write of zero bytes being read as zero
bytes without stopping communication.  I have heard that it does not
work correctly.  If someone would care to fill this in more, I would be
grateful.  Taylor UUCP does not implement the `x' protocol.

The UUCP `d' Protocol
=====================

   This is apparently used for DataKit connections, and relies on a
write of zero bytes being read as zero bytes, much as the `x' protocol
does.  I don't really know anything else about it.  Taylor UUCP does not
implement the `d' protocol.

The UUCP `G' Protocol
=====================

   The `G' protocol is apparently simply the `g' protocol, except that
it is known to support all possible window and packet sizes.  It was
introduced by SVR4 UUCP; the SVR4 implementation of the `g' protocol is
apparently fixed at a packet size of 64 and a window size of 7.  Taylor
UUCP does not recognize the `G' protocol.  It does support all window
and packet sizes for the `g' protocol.