New UNIX Kermit (Part 2 of 5)
Sam Chin
tsc2597 at acf4.UUCP
Thu Feb 28 14:01:00 AEST 1985
# This is a shell archive. Remove anything before this line,
# then unpack it by saving it in a file and typing "sh file".
#
# Wrapped by acf4!tsc2597 on Wed Feb 27 22:19:17 EST 1985
# Contents: ckermi.doc ckermi.h ckermi.mak
echo x - ckermi.doc
sed 's/^@//' > "ckermi.doc" <<'@//E*O*F ckermi.doc//'
-*-Text-*-
Version 4.0 of Unix Kermit
D R A F T # 3
Frank da Cruz
Columbia University
Center for Computing Activities
February 4, 1985
NOTE -- This preliminary documentation is in plain text. It needs
to become input for two text formatters - Scribe and Nroff, the
former for inclusion in the Kermit User Guide, and the latter for
Unix man pages. This might be done by defining formatting macros
in M4, which generate the appropriate Scribe and Nroff commands for
sectioning, itemization, description, etc. (Volunteers?)
ANOTHER NOTE -- This documentation describes a pre-release test version
of Unix Kermit. The program and documentation are very likely to change
during the testing period. At the end of the testing period, the
organization of the program and its functional characteristics should be
relatively stable, so that further changes will provide either additional
functionality or bug fixes.
C-Kermit is a completely new implementation of Kermit, written modularly and
transportably in C. The protocol state transition table is written in
'wart', a (not proprietary) lex-like preprocessor for C. System-dependent
primitive functions are isolated into separately compiled modules so that the
program should be easily portable among Unix systems and also to non-Unix
systems that have C compilers.
Features:
Local operation: yes
Remote operation: yes
Transfer text files: yes
Transfer binary files: yes
Wildcard send: yes
File transfer interruption: yes (per-file and entire batch)
Filename collision avoidance: yes (selectable)
Can time out: yes
8th-bit prefixing: yes (used only when necessary)
Repeat count prefixing: yes
Alternate block checks: yes (6-bit and 12-bit checksums, 16-bit CRC)
Terminal emulation: yes (more efficient than previous releases)
Communication settings: yes (flow, handshake, speed, parity, duplex)
Transmit BREAK: yes
IBM mainframe communication: yes
Transaction logging: yes
Session logging: yes
Debug logging: yes
Packet logging: yes
Act as server: yes
Talk to server: yes
Advanced server functions: yes
Local file management: yes
Command/Init files: yes
Missing (not done yet):
File attributes: no
Command macros: no
Login scripts: no
Raw file transmit: no
C-Kermit provides traditional Unix command line operation as well as
interactive command prompting and execution. The command line options
provide access to a minimal subset of C-Kermit's capabilities; the
interactive command set is far richer.
COMMAND LINE OPERATION:
The C-Kermit command line syntax has been changed from that of earlier
releases of Unix Kermit to conform to the "Proposed Syntax Standards for
Unix System Commands" put forth by Kathy Hemenway and Helene Armitage of
AT&T Bell Laboratories in Unix/World Vol.1, No.3, 1984. The rules that
apply are:
@. Command names must be between 2 and 9 characters ("kermit" is 6).
@. Command names must include lower case letters and digits only.
@. An option name is a single character.
@. Options are delimited by '-'.
@. Options with no arguments may be grouped (bundled) behind one delimiter.
@. Option-arguments cannot be optional.
@. Arguments immediately follow options, separated by whitespace.
@. The order of options does not matter.
@. '-' preceded and followed by whitespace means standard input.
A group of bundled options may end with an option that has an argument.
C-Kermit command line options may specify either actions or settings. If
C-Kermit is invoked with a command line that specifies no actions, then it
will issue a prompt and begin interactive dialog.
Action options specify either protocol transactions or terminal connection.
-s fn Send the specified file or files. If fn contains wildcard (meta)
characters, the Unix shell expands it into a list. If fn
is '-' then kermit sends from standard input, which must
come from a file ('kermit -s - < foo.bar') or a parallel process
('ls -l | kermit -s -'); you cannot use this mechanism to send
terminal typein. If you want to send a file whose name is "-"
you can precede it with a path name, as in 'kermit -s ./-'.
-r Receive a file or files. Wait passively for files to arrive.
-k Receive (passively) a file or files, sending them to standard
output. This option can be used in several ways:
kermit -k
Displays the incoming files on your screen; to be used only
in local mode (see below).
kermit -k > fn
Sends the incoming file or files to the named file, fn.
If more than one file arrives, all are concatenated together
into the single file fn.
kermit -k | command
Pipes the incoming data (single or multiple files) to the
indicated command, as in 'kermit -k | sort > sorted.stuff'.
-a fn If you have specified a file transfer option, you may specify an
alternate name for a single file with the -a option. For example,
'kermit -s foo -a bar' sends the file foo with the name bar.
If more than one file arrives or is sent, only the first file is
affected by the -a option. 'kermit -ra baz' stores the first
incoming file under the name baz.
-x Begin server operation. May be used in either local or remote mode.
Before proceeding, a few words about remote and local operation are
necessary. C-Kermit is "local" if it is running on PC or workstation that
you are using directly, or if it is running on a multiuser system and
transferring files over an external communication line -- not your job's
controlling terminal or console. C-Kermit is remote if it is running on a
multiuser system and transferring files over its own controlling terminal's
communication line, connected to your PC or workstation.
If you are running C-Kermit on a PC, it is in local mode by default,
with the "back port" designated for file transfer and terminal connection.
If you are running C-Kermit on a multiuser (timesharing) system, it is
in remote mode unless you explicitly point it at an external line for
file transfer or terminal connection. The following command sets
C-Kermit's "mode":
-l dev Line -- Specify a terminal line to use for file transfer and
terminal connection, as in 'kermit -l /dev/ttyi5'.
When an external line is being used, you might also need some additional
options for successful communication with the remote system:
-b n Baud -- Specify the baud rate for the line given in the -l option,
as in 'kermit -l /dev/ttyi5 -b 9600'. This option should always be
included with the -l option, since the speed of an external line
is not necessarily what you expect.
-p x Parity -- e,o,m,s,n (even, odd, mark, space, or none). If parity
is other than none, then the 8th-bit prefixing mechanism will be
used for transferring 8-bit binary data, provided the opposite
Kermit agrees. The default parity is none.
-t Specifies half duplex, line turnaround with XON as the handshake
character.
The following commands may be used only with a C-Kermit which is local --
either by default or else because the -l option has been specified.
-g fn Actively request a remote server to send the named file or files;
fn is a file specification in the remote host's own syntax. If
fn happens to contain any special shell characters, like '*',
these must be quoted, as in 'kermit -g x\*.\?'.
-f Send a 'finish' command to a remote server.
-c Establish a terminal connection over the specified or default
communication line, before any protocol transaction takes place.
Get back to the local system by typing the escape character
(normally Control-Backslash) followed by the letter 'c'.
-n Like -c, but after a protocol transaction takes place; -c and -n
may both be used in the same command.
On a timesharing system, the -l and -b options will also have to be included
with the -r, -k, or -s options if the other Kermit is on a remote system.
If C-Kermit is in local mode, the screen (stdout) is continously updated to
show the progress of the file transer. A dot is printed for every 4 data
packets, other packets are shown by type (e.g. 'S' for Send-Init), 'T' is
printed when there's a timeout, and '%' for each retransmission. In
addition, you may type (to stdin) certain interrupt commands during file
transfer:
Control-F: Interrupt the current File, and go on to the next (if any).
Control-B: Interrupt the entire Batch of files, terminate the transaction.
Control-R: Resend the current packet
Control-A: Display a status report for the current transaction.
(These interrupt characters differ from the ones used in other Kermit
implementations to avoid conflict with Unix shell interrupt characters.)
Several other command-line options are provided:
-i Specifies that files should be sent or received exactly "as is"
with no conversions. This option is necessary for transmitting
binary files. It may also be used to slightly boost efficiency
in Unix-to-Unix transfers of text files by eliminating CRLF/newline
conversion.
-w Write-Protect -- Avoid filename collisions for incoming files.
-q Quiet -- Suppress screen update during file transfer, for instance
to allow a file transfer to proceed in the background.
-d Debug --Record debugging information in the file debug.log in
the current directory. Use this option if you believe the program
is misbehaving, and show the resulting log to your local
kermit maintainer.
-h Help -- Display a brief synopsis of the command line options.
The command line may contain no more than one protocol action option.
Files are sent with their own names, except that lowercase letters are
raised to upper, pathnames are stripped off, tilde ('~') characters changed
to 'X', and if the file name begins with a period, an 'X' is inserted before
it. Incoming files are stored under their own names except that uppercase
letters are lowered, and, if -w was specified, a "generation number" is
appended to the name if it has the same name as an existing file which would
otherwise be overwritten. If the -a option is included, then the same rules
apply to its argument. The file transfer display shows any transformations
performed upon filenames.
During file transfer, files are encoded as follows:
@. Control characters are converted to prefixed printables.
@. Sequences of repeated characters are collapsed via repeat counts, if
the other Kermit is also capable of repeated-character compression.
@. If parity is being used on the communication line, data characters with
8th (parity) bits on are specially prefixed, provided the other Kermit
is capable of 8th-bit prefixing (if not, 8-bit binary files cannot be
successfully transferred).
@. Conversion is done between Unix newlines and carriage-return-linefeed
sequences unless the -i option was specified.
Command Line Examples:
kermit -l /dev/ttyi5 -b 1200 -cn -r
This command connects you to the system on the other end of ttyi5 at
1200 baud, where you presumably log in and run Kermit with a 'send'
command. After you escape back, C-Kermit waits for a file (or files) to
arrive. When the file transfer is completed, you are again connected to
the remote system so that you can logout.
kermit -l /dev/ttyi4 -b 1800 -cntp m -r -a foo
This command is like the preceding one, except the remote system in this
case uses half duplex communication with mark parity. The first file
that arrives is stored under the name foo.
kermit -l /dev/ttyi6 -b 9600 -nf
This command would be used to shut down a remote server and then connect
to the remote system, in order to log out or to make further use of it.
kermit -l /dev/ttyi6 -b 9600 -qg foo.\* &
This command causes C-Kermit to be invoked in the background, getting a group
of files from a remote server (note the quoting of the '*' character). No
display occurs on the screen, and the keyboard is not sampled for
interruption commands. This allows other work to be done while file
transfers proceed in the background.
kermit -l /dev/ttyi6 -b 9600 -g foo.\* > foo.log < /dev/null &
This command is like the previous one, except the file transfer display has
been redirected to the file foo.log. Standard input is redirected to prevent
C-Kermit from sampling it for interruption commands.
kermit -iwx
This command starts up C-Kermit as a server. Files are transmitted with
no newline/carriage-return-linefeed conversion; the -i option is necessary
for binary file transfer and useful for Unix-to-Unix transfers. Incoming
files that have the same names as existing files are given new, unique names.
kermit -l /dev/ttyi6 -b 9600
This command sets the communication line and speed. Since no action is
specified, C-Kermit issues a prompt and enters an interactive dialog with
you. Any settings given on the command line remain in force during the
dialog, unless explicitly changed.
kermit
This command starts up Kermit interactively with all default settings.
A final example shows how Unix Kermit might be used to send an entire
directory tree from one system to another, using the tar program as Kermit's
standard input and output. On the orginating system, in this case the
remote, type (for instance):
tar cf - /usr/fdc | kermit -is -
This causes tar to send the directory /usr/fdc (and all its files and all
its subdirectories and all their files...) to standard output instead of a
tape; kermit receives this as standard input and sends it as a binary file.
On the receiving system, in this case the local one, type (for instance):
kermit -il /dev/ttyi5 -b 9600 -k | tar xf -
Kermit receives the tar archive, and sends it via standard output to tar,
which extracts it into a replica of the original directory tree.
INTERACTIVE OPERATION
C-Kermit's interactive command prompt is "C-Kermit>". In response to this
prompt, you may type any valid command. C-Kermit executes the command and
then prompts you for another command. The process continues until you
command the program to terminate.
Commands begin with a keyword, normally an English verb, such as "send".
You may omit trailing characters from any keyword, so long as you specify
sufficient characters to distinguish it from any other keyword valid in that
field. Certain commonly-used keywords (such as "send", "receive", "connect")
have special non-unique abbreviations ("s" for "send", even though this would
not otherwise distinguish it from "set").
You may type '?' at any point to get a help message explaining what is
possible, or expected, at that point. You may type ESC to request
completion of the current keyword or file name, or insertion of a default
value (the result will be a beep if the requested operation fails). You may
edit your commands with DEL or Backspace (erase rightmost character),
Control-W (erase rightmost word), or Control-U (erase entire command). The
screen should show the effects of this editing. On a hardcopy terminal, you
can type Control-R to redisplay the current command to show the effects of
any editing. The command is entered by typing carriage return, linefeed, or
formfeed. If you make any mistakes, you will receive an informative error
message and a new prompt -- make liberal use of '?' and ESC to feel your way
through the commands. One important command is "help" -- you should use it
the first time you run C-Kermit.
If you need to include special characters (like '?') in a command, you
may precede them with a backslash ('\') and they will be accepted without
triggering any special function.
Interactive C-Kermit accepts commands from files as well as from the
keyboard. When you enter interactive mode, C-Kermit looks for the file
@.kermrc in your home or current directory (first it looks in the home
directory, then in the current one) and executes any commands it finds there.
These commands must be in interactive format, not Unix command-line format.
A "take" command is also provided for use at any time during an interactive
session. Command files may be nested to any reasonable depth.
Here is a brief list of C-Kermit interactive commands:
! Execute a Unix shell command.
bye Terminate and log out a remote Kermit server.
close Close a log file.
connect Establish a terminal connection to a remote system.
cwd Change Working Directory.
directory Display a directory listing.
echo Display arguments literally.
exit Exit from the program, closing any open logs.
finish Instruct a remote Kermit server to exit, but not log out.
get Get files from a remote Kermit server.
help Display a help message for a given command.
log Open a log file -- debugging, packet, session, transaction.
quit Same as 'exit'.
receive Passively wait for files to arrive.
remote Issue file management commands to a remote Kermit server.
send Send files.
server Begin server operation.
set Set various parameters.
show Display values of 'set' parameters.
space Display current disk space usage.
statistics Display statistics about most recent transaction.
take Execute commands from a file.
The 'set' parameters are:
block-check Level of packet error detection.
delay How long to wait before sending first packet.
duplex Specify which side echoes during 'connect'.
end-of-packet Terminator for outbound packets.
escape-character Character to prefix "escape commands" during 'connect'.
file Set various file parameters.
flow-control Communication line full-duplex flow control.
handshake Communication line half-duplex turnaround character.
line Communication line device name.
packet-length Maximum length for packets.
pad-character Character to use for inter-packet padding.
padding How much inter-packet padding to use.
parity Communication line character parity.
prompt Change the C-Kermit program's prompt.
speed Communication line speed.
start-of-packet Packet prefix character.
timeout Timer interval to detect lost packets.
The 'remote' commands are:
cwd Change remote working directory.
delete Delete remote files.
directory Display a listing of remote file names.
help Request help from a remote server.
host Issue a command to the remote host in its own command language.
space Display current disk space usage on remote system.
type Display a remote file on your screen.
Most of these commands are described adequately in the Kermit User Guide.
Special aspects of certain Unix Kermit commands are described below. The
following notation is used:
fn A Unix file specification, possibly containing the "wildcard"
characters '*' or '?' ('*' matches all character strings, '?' matches
any single character).
fn1 A Unix file specification which may not contain '*' or '?'.
rfn A remote file specification in the remote system's own syntax, which
may denote a single file or a group of files.
rfn1 A remote file specification which should denote only a single file.
n A decimal number between 0 and 94.
c A decimal number between 0 and 127 representing the value of an
ASCII character.
cc A decimal number between 0 and 31, or else exactly 127,
representing the value of an ASCII control character.
[ ] Any field in square braces is optional.
{x,y,z} Alternatives are listed in curly braces.
The 'send' command:
Syntax: send fn
or: send fn1 rfn1
Send the file or files denoted by fn to the other Kermit, which should be
running as a server, or which should be given the 'receive' command. Each
file is sent under its own name (as described above, or to the extent
specified by the 'set file names' command). If the second form is used,
i.e. with fn1 denoting a single Unix file, rfn1 may be specified as a name
to send it under. The 'send' command may be abbreviated to 's', even though
's' is not a unique abbreviation for a top-level C-Kermit command.
The wildcard (meta) characters '*' and '?' are accepted in fn. If '?' is to
be included, it must be prefixed by '\' to override its normal function of
providing help. '*' matches an string, '?' matches any single character.
Other notations for file groups, like 'x[a-m]y', are not supported. When
fn contains '*' or '?' characters, there is a limit to the number of files
that can be matched, which varies from system to system. If you get the
message "Too many files match" then you'll have to make a more judicious
selection. If fn was of the form 'usr/longname/anotherlongname/*' then
C-Kermits string space will fill up rapidly -- try doing a cwd to the path
in question and reissuing the command.
The 'receive' command:
Syntax: receive
or: receive fn1
Passively wait for files to arrive from the other Kermit, which must be
given the 'send' command -- the 'receive' command does not work in
conjunction with a server. If fn1 is specified, store the first incoming
file under that name. The 'receive' command may be abbreviated to 'r'.
The 'get' command:
Syntax: get rfn
or: get
rfn
fn1
Request a remote Kermit server to send the named file or files. Since a
remote file specification (or list) might contain spaces, which normally
delimit fields of a C-Kermit command, an alternate form of the command is
provided to allow the inbound file to be given a new name: type 'get' alone
on a line, and you will be prompted separately for the remote and local
file specifications. As with 'receive', if more than one file arrives as
a result of the 'get' command, only the first will be stored under the
alternate name given by fn1; the remaining files will be stored under their
own names if possible. If a '?' is to be included in the remote file
specification, you must prefix it with '\' to suppress its normal function
of providing help.
The 'server' command:
This command places C-Kermit in server mode on the currently selected
communication line. All further commands must arrive as valid Kermit
packets from the Kermit on the other end of the line. The Unix Kermit
server can respond to the following commands:
Command Server Response
GET Sends files
SEND Receives files
FINISH Exits to level from which it was invoked
REMOTE DIRECTORY Sends directory lising
REMOTE DELETE Removes files
REMOTE CWD Changes working directory
REMOTE TYPE Sends files to your screen
REMOTE SPACE Reports about its disk usage
REMOTE WHO Shows who's logged in
REMOTE HOST Executes a Unix shell command
REMOTE HELP Lists these capabilities
Note that the Unix Kermit server cannot respond to a BYE command; it
cannot log itself out. If the Kermit server is directed at an external line
(i.e. it is in "local mode") then the console may be used for other work if
you have 'set file display off', or else it may be used to observe file
transfers and enter status or interruption commands.
The 'remote', 'bye', and 'finish' commands:
C-Kermit may itself request services from a remote Kermit server. In
addition to the 'send' and 'get' commands, the following may also be used:
remote cwd [directory]
If the optional remote directory specification is included, you will
be prompted on a separate line for a password, which will not echo as
you type it.
remote delete rfn delete remote file or files.
remote directory [rfn] directory listing of remote files.
remote host command command in remote host's own command language.
remote space disk usage report from remote host.
remote type display remote file or files on the screen.
remote who [user] display information about who's logged in.
remote help display remote server's capabilities.
bye and finish:
When connected to a remote Kermit server, these commands cause the remote
server to terminate; 'finish' returns it to Kermit or system command level
(depending on the implementation or how it was invoked); 'bye' also requests
it to log itself out.
The 'log' and 'close' commands:
Syntax: log {debugging, packets, session, transactions} [fn1]
C-Kermit's progress may be logged in various ways. The 'log' command
opens a log, the 'close' command closes it. In addition, all open logs
are closed by the 'exit' and 'quit' commands. A name may be specified for
a log file; if the name is omitted, the file is created with a default
name as shown below.
log debugging
This produces a voluminous log of the internal workings of C-Kermit,
of use to Kermit developers or maintainers in tracking down suspected
bugs in the C-Kermit program. Use of this feature dramatically slows
down the Kermit protocol. Default name: debug.log.
log packets
This produces a record of all the packets that go in and out of the
communication port. This log is of use to Kermit maintainers who are
tracking down protocol problems in either C-Kermit or any Kermit that
C-Kermit is connected to. Default name: packet.log.
log session
This log will contain a copy of everything you see on your screen during
the 'connect' command, except for local messages or interaction with
local escape commands. Default name: session.log.
log transactions
The transaction log is a record of all the files that were sent or
received while transaction logging was in effect. It includes time
stamps and statistics, filename transformations, and records of any
errors that may have occurred. The transaction log allows you to have
long unattended file transfer sessions without fear of missing some
vital screen message. Default name: transaction.log.
The 'close' command explicitly closes a log, e.g. 'close debug'.
Local file management commands:
Unix Kermit allows some degree of local file management from interactive
command level:
directory [fn]
Displays a listing of the names, modes, sizes, and dates of files
matching fn (which defaults to '*'). Equivalent to 'ls -l'.
cwd [directory-name]
Changes Kermit's working directory to the one given, or to the your
default directory if the directory name is omitted. Equivalent to 'cd'.
space
Display information about disk space and/or quota in the current
directory and device.
! command
The command is executed by the Unix shell. Use this for all other
file management commands. This command has certain peculiarities:
. A space must separate the '!' from the shell command.
. A 'cd' command executed in this manner will have no effect -- use the
C-Kermit 'cwd' command instead.
The 'set' and 'show' commands:
Since Kermit is designed to allow diverse systems to communicate, it is
often necessary to issue special instructions to allow the program to adapt
to peculiarities of the another system or the communication path. These
instructions are accomplished by the 'set' command. The 'show' command may
be used to display current settings. Here is a brief synopsis of settings
available in the current release of C-Kermit:
block-check {1, 2, 3}
Determines the level of per-packet error detection. 1 is a 6-bit
checksum, folded to include the values of all bits from each character.
2 is a 12-bit checksum. 3 is a 16-bit cyclic redundancy check. The
higher the block check, the better the error detection and correction
and the higher the resulting overhead. Type 1 is most commonly used; it
is supported by all Kermit implementations, and it has proven adequate in
most circumstances. Types 2 or 3 would be used to advantage when
transferring 8-bit binary files over noisy lines.
delay n
How many seconds to wait before sending the first packet after a 'send'
command. Used in remote mode to give you time to escape back to your
local Kermit and issue a 'receive' command. Normally 5 seconds.
duplex {full, half}
For use during 'connect'. Specifies which side is doing the echoing;
'full' means the other side, 'half' means C-Kermit must echo typein itself.
end-of-packet cc
Specifies the character needed by the other Kermit to recognize the end
of a packet. C-Kermit sends this character at the end of each packet.
Normally 13 (carriage return), which most Kermit implementations
require. Other Kermits require no terminator at all, still others may
require a different terminator, like linefeed (10).
escape-character cc
For use during 'connect' to get C-Kermit's attention. The escape
character acts as a prefix to an 'escape command', for instance to
close the connection and return to C-Kermit or Unix command level.
The normal escape character is Control-Backslash (28).
file {display, names, type, warning}
Establish various file-related parameters:
display {on, off}
Normally 'on'; when in local mode, display progress of file
transfers on the screen (stdout), and listen to the keyboard (stdin)
for interruptions. If off (-q on command line) none of this is
done, and the file transfer may proceed in the background oblivious
to any other work concurrently done at the console terminal.
names {converted, literal}
Normally converted, which mean that outbound filenames have path
specifications stripped, lowercase letters raised to upper,
tildes and extra periods changed to 'X's, and an 'X' inserted in
front of any name that starts with period. Incoming files have
uppercase letters lowered. Literal means that none of these
conversions are done; therefore, any directory path appearing in a
received file specification must exist and be write-accessible.
Literal naming is obviously of limited utility, and intended
principally for file transfers between very similar Unix systems.
type {binary, text}
Normally text, which means that conversion is done between Unix
newline characters and the carriage-return/linefeed sequences
required by the canonical Kermit file transmission format, and in
common use on non-Unix systems. Binary means to transmit file
contents without conversion. Binary (-i in command line notation)
is necessary for binary files, and desirable in all Unix-to-Unix
transactions to cut down on overhead.
warning {on, off}
Normally off, which means that incoming files will silently
overwrite existing files of the same name. When on (-w on command
line) Kermit will check if an arriving file would overwrite an
existing file; if so, it will construct a new name for the arriving
file, of the form foo~n, where foo is the name they share and n is a
"generation number"; if foo exists, then the new file will be called
foo~1. If foo and foo~1 exist, the new file will be foo~2, and so on.
flow-control {none, xon/xoff}
Normally xon/xoff for full duplex flow control. Should be set to 'none'
if the other system cannot do xon/xoff flow control.
handshake {xon, xoff, cr, lf, bell, esc, none}
Normally none. Otherwise, half-duplex communication line turnaround
handshaking is done, which means Unix Kermit will not reply to a packet
until it has received the indicated handshake character or has timed out
waiting for it.
line [device-name]
The device name for the communication line to be used for file transfer
and terminal connection, e.g. /dev/ttyi3. If you specify a device name,
Kermit will be in local mode, and you should remember to issue any other
necessary 'set' commands, such as 'set speed'. If you omit the device
name, Kermit will revert to its default mode of operation.
packet-length n
Specify the maximum packet length to use. Normally 90. Shorter packet
lengths can be useful on noisy lines, or with systems or front ends or
networks that have small buffers. The shorter the packet, the higher
the overhead, but the lower the chance of a packet being corrupted by
noise, and the less time to retransmit corrupted packets.
pad-character cc
C-Kermit normally does not need to have incoming packets preceded
with pad characters. This command allows C-Kermit to request the
other Kermit to use cc as a pad character. Default cc is NUL,
ASCII 0.
padding n
How many pad characters to ask for, normally 0.
parity {even, odd, mark, space, none}
Specify character parity for use in packets and terminal connection,
normally none. If other than none, C-Kermit will seek to use the
8th-bit prefixing mechanism for transferring 8-bit binary data, which
can be used successfully only if the other Kermit agrees; if not,
8-bit binary data cannot be successfully transferred.
prompt [string]
The given string will be substituted for "C-Kermit>" as this program's
prompt. If the string is omitted, the prompt will revert to "C-Kermit>".
speed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600}
The baud rate for the external communication line. Cannot be used to
change the speed of your own console terminal. Many Unix systems are
set up in such a way that you must give this command after a 'set line'
command before you can use the line.
start-of-packet cc
The Kermit packet prefix is Control-A (1). The only reasons it should
ever be changed would be: Some piece of equipment somewhere between the
two Kermit programs will not pass through a Control-A; or, some piece of
of equipment similarly placed is echoing its input. In the latter case,
the recipient of such an echo can change the packet prefix for outbound
packets to be different from that of arriving packets, so that the
echoed packets will be ignored. The opposite Kermit must also be told
to change the prefix for its inbound packets. Unix Kermit presently can
be told to change only its outbound packet prefix.
timeout n
Normally, each Kermit partner sets is packet timeout interval based on
what the opposite Kermit requests. This command allows you to override
the normal procedure and specify a timeout interval. If you specify 0,
then no timeouts will occur, and Unix Kermit will wait forever for
expected packets to arrive.
The 'show' command:
Syntax: show {parameters, versions}
The show command displays the values of all the 'set' parameters described
above. If you type 'show versions', then C-Kermit will display the version
numbers and dates of all its internal modules. You should use the 'show
versions' command to ascertain the vintage of your Kermit program before
reporting problems to Kermit maintainers.
The 'statistics' command:
The statistics command displays information about the most recent Kermit
protocol transaction, including file and communication line i/o, as well
as what encoding options were in effect (such as 8th-bit prefixing,
repeat-count compression).
The 'take' and 'echo' commands:
Syntax: take fn1
The 'take' command instructs C-Kermit to execute commands from the named
file. The file may contain any interactive C-Kermit commands, including
'take'; command files may be nested to any reasonable depth. The 'echo'
command may be used within command files to issue greetings, announce
progress, etc.
Command files may be used in lieu of command macros, which have not been
implemented in this version of C-Kermit. For instance, if you commonly
connect to a system called 'B' that is connected to the other end of the
communication line which is plugged into ttyh7 and which runs at 4800 baud,
you could create a file called b containing the commands
set line /dev/ttyh7
set speed 4800
echo Connecting to System B...
connect
and then simply type 'take b' (or 't b' since no other commands begin with
the letter 't') whenever you wished to connect to system B.
For connecting to IBM mainframes, a number of 'set' commands are required;
these, too, are conveniently collected into a 'take' file:
set speed 1200
set parity mark
set handshake xon
set flow-control none
set duplex half
An implicit 'take' command is executed upon your .kermrc file upon
C-Kermit's initial entry into interactive dialog. The .kermrc file should
contain 'set' or other commands you want to be in effect at all times.
For instance, you might want override the default action when incoming files
have the same names as existing files -- in that case, put the command
set file warning on
in your .kermrc file.
Commands executed from take files are not echoed at the terminal. If you
want to see the commands as well as their output, you could feed the
command file to C-Kermit via redirected stdin, as in 'kermit < x'.
The 'connect' command:
The connect comand links your terminal to another computer as if it were
a local terminal to that computer, through the device specified in the most
recent 'set line' command, or through the default device if your system
is a PC or workstation. All characters you type at your keyboard
are sent out the communication line, all characters arriving at the
communication port are displayed on your screen. Current settings of speed,
parity, duplex, and flow-control are honored. If you have issued a 'log
session' command, everything you see on your screen will also be recorded
to your session log. This provides a way to "capture" files from systems
that don't have Kermit programs available.
To get back to your own system, you must type the escape character, which
is Control-Backslash (^\) unless you have changed it with the 'set escape'
command, followed by a single-character command, such as 'c' for "close
connection". Single-character commands include:
C - Close the connection
B - Send a BREAK signal
0 - (zero) send a null
S - Give a status report about the connection
^\ - Send Control-Backslash itself (whatever you have defined the
escape character to be, typed twice in a row sends one copy of it).
Lower-case and control equivalents for these letters are also accepted. A
space typed after the escape character is ignored. Any other character will
produce a beep.
No special provisions are made for controlling modems or dialers. Thus, to
dial out through a Hayes-like modem, you would have to type the modem
commands yourself.
set line /dev/dialer
set speed 1200
connect
ATD5551212
Here, ATD is the dialing command. You would look for a return code from the
modem (in this case '1' if a connection is made, '3' if no carrier
detected), and act accordingly.
'c' is an acceptable non-unique abbreviation for 'connect'.
The 'help' command:
Syntax: help
or: help keyword
or: help {set, remote} keyword
Brief help messages or menus are always available at interactive command
level by typing a question mark at any point. A slightly more verbose form
of help is available through the 'help' command. The 'help' command with
no arguments prints a brief summary of how to enter commands and how to
get further help. 'help' may be followed by one of the top-level C-Kermit
command keywords, such as 'send', to request information about a command.
Commands such as 'set' and 'remote' have a further level of help. Thus you
may type 'help', 'help set', or 'help set parity'; each will provide a
successively more detailed level of help.
The 'exit' and 'quit' commands:
These two commands are identical. Both of them do the following:
@. Attempt to insure that the terminal is returned to normal.
@. Relinquish access to any communication line assigned via 'set line'.
@. Close any open log files.
After exit from C-Kermit, your default directory will be the same as when
you started the program.
C-Kermit under Berkeley Unix:
C-Kermit may be interrupted at command level or during file transfer by
typing Control-C. The program will perform its normal exit function,
restoring the terminal. If a protocol transaction was in progress, an
error packet will be sent to the opposite Kermit so that it can terminate
cleanly.
During execution of a system command, C-Kermit can often be returned to
command level by typing a single Control-C.
C-Kermit may also be interrupted by ^Z to put the process in the background.
In this case the terminal is not restored. You will have to type
Control-J followed by "reset" followed by another Control-J to get your
terminal back to normal. C-Kermit can be halted in a similar manner by
typing Control-Backslash, except that instead of moving it to the
background, a core dump is produced.
Control-C, Control-Z, and Control-\ lose their normal functions during
terminal connection and also during file transfer when the controlling tty
line is being used for packet i/o.
The BSD implementation of C-Kermit has code to take advantage of a special
nonstandard kernel-mode line driver, which boosts the speed of packet i/o
significantly. The problem is that "raw" mode, needed for packet i/o, also
implies "cbreak" (character wakeup) mode, which is very expensive. The new
line driver is a modification of the "berknet" driver, which allowed raw mode
i/o to take place with process wakeup only upon receipt of a linefeed. The
Berknet driver, unfortunately, strips off the high order bit of each
character and does not allow the line terminator to be specified. The
modification allows all 8 bits to pass through unmolested, allows the wakeup
character to be specified, and allows the buffer to be tested or cleared.
If you are running C-Kermit in "quiet mode" in the foreground, then
interrupting the program with a console interrupt like Control-C will not
restore the terminal to normal conversational operation. This is because
the system call to enable console interrupt traps will cause the program to
block if it's running in the background, and the primary reason for quiet
mode is to allow the program to run in the background without blocking, so
that you can do other work in the foreground.
C-KERMIT RESTRICTIONS AND KNOWN BUGS
1. Initialization of Transactions
C-Kermit running in local mode in conjunction with a remote server presently
does not send a configuration (I) packet prior to sending a generic command,
host command, or 'get' command. This means that the user of C-Kermit cannot
directly control the block check type to be used, and that if the local
C-Kermit is restarted, the remote server might retain settings, such as
repeated character compression, that are not in effect in the new C-Kermit
based upon previous I- or S-packet exchanges. This situation can be cleared
up by sending a short (even a null) file to the remote server, to get the
configuration parameters back in agreement.
ADAPTING C-KERMIT TO OTHER SYSTEMS:
C-Kermit is designed for portability. The level of portability is indicated
in parentheses after the module name: "C" means any system that has a C
compiler that conforms to the description in "The C Programming Language" by
Kernighan & Ritchie (Prentice-Hall, 1978). "Cf" is like "C", but also
requires "standard" features like printf and fprintf, argument passing via
argv/argc, and so on, as described in Kernighan & Ritchie. "Unix" means the
module should be useful under any Unix implementation; it requires features
such as fork() and pipes. Anything else means that the module is particular
to the indicated system. The modules are:
ckmain.c, ckermi.h, ckdebu.h (Cf):
This is the main program. It contains declarations for global variables and
a small amount of code to initialize some variables and invoke the command
parser. In its distributed form, it assumes that command line arguments are
passed to it via argc and argv. Since this portion of code is only several
lines long, it should be easy to replace for systems that have different
styles of user interaction. The header files define symbols and macros used
by the various modules of C-Kermit.
wart.c (Cf), ckprot.w (C):
The ckprot module embodies the Kermit protocol state table and the code to
accomplish state switching. It is written in "wart", a language which may be
regarded as a subset of the Unix "lex" lexical analyzer generator. Wart
implements enough of lex to allow the ckprot module to function. Lex itself
was not used because it is proprietary. The protocol module ckprot.w is read
by wart, and a system-independent C program is produced.
The syntax of a Wart program is illustrated by ckprot.w:
1. C declarations, #includes, #defines, comments.
2. Wart state name declarations, introduced by "%state".
3. Perhaps more of (1).
4. The wart token "%%" to introduce the state table, which is composed
of entries of the format <state-list>input-character { action }
5. Another "%%" to mark the end of the state table.
6. C code which includes an invocation of the wart() function, whose
definition is generated by the wart program. The wart() function
calls upon the input() function (defined externally, in this case in
ckfns.c) to return a single character, which it uses in conjunction
with the current state to index into a big case statement which it
generates from the state table (4).
The state-list is a list of one or more states defined in the %states
directive, enclosed in angle brackets, e.g. <send>, <ssinit,ssdata>.
The state-list may be omitted. The input is a single character, supplied
by the input() function. In Kermit's case, it is normally the packet
type. A period indicates "any input". The action is the C language
code to be executed when the specified input appears when in the state(s)
specified in the state-list. The action normally consists of a function
invocation followed by a switch to a new state. Examples:
<foo>X { bar(); state = Y }
This means "if in state foo the input 'X' appears, invoke the function
bar() and then switch to state Y.
<foo,bar>. { baz(); BEGIN Z; }
If in state foo or bar and any input appears, invoke baz(), then switch to
state Z. BEGIN is a macro predeclared by wart to be "state = " (lex has
a similar macro).
A { }
This means that if an 'A' appears as input in any state, perform no action,
and remain in the same state.
The state table is scanned sequentially, so that constructions like
<foo>A { bar(); }
A { baz(); BEGIN mumble; }
are possible -- this means "if in state foo and the input 'A' appears,
invoke bar() and remain in the current state. If in any other state and
an 'A' appears, invoke baz() and switch to state mumble.
ckfns.c (C):
The module contains all the Kermit protocol support functions -- packet
formation, encoding, decoding, block check calculation, filename and data
conversion, protocol parameter negotiation, and high-level interaction
with the communication line and file system.
ckx???.c (specific to system ???):
ckxbsd.c (Berkeley Unix):
The ckx module contains the system-dependent primitives for communication
line i/o, timers, and interrupts. Certain important variables are defined
in this module, which determine whether C-Kermit is by default remote or
local, what the default communication device is, and so forth. The ckx
module maintains its own private database of file descriptors and modes for
the console terminal and the file transfer communication line so that other
modules (like ckfns or the terminal connect module) need not be concerned
with them. This module will vary significantly among Unix implementations
since the sgtty/ioctl/termio functions and their arguments are among the
least compatible areas of Unix.
ckz???.c (specific to system ???):
ckzbsd.c (Berkeley Unix):
The ckz module contains system-dependent primitives for file i/o, wildcard
(meta character) expansion, file existence and access checking, and system
command execution. It maintains an internal database of i/o "channels"
(file pointers in the case of Unix) for the files C-Kermit cares about --
the input file (the file which is being sent), the output file (the file
being received), the various logs, the screen, and so forth. This module
will vary little among Unix implementations except for the wildcard
expansion code, which requires detailed knowledge of the directory
structure. The ckz module also defines variables containing the system
command strings used to perform certain functions like directory listing,
file deletion, etc.
ckuser.c (Unix):
This is the "user interface" for C-Kermit. It includes the command parser,
the screen output functions, and console input functions. The command
parser comes in two pieces -- the traditional Unix command line decoder
(which is quite small and compact), and the interactive keyword parser
(which is rather large). This module is fully replacable; its interface to
the other modules is very simple, and is explained at the beginning of the
source file. The ckuser module also includes code to execute any commands
directly which don't require the Kermit protocol -- local file management,
etc. The module is rated "Unix" because it makes occasional use of the
system() function.
ckcmd.c, ckcmd.h (Cf):
This is an interactive command parsing package developed for C-Kermit.
It is written portably enough to be usable on any system that has a C
compiler that supports functions like printf. The file name parsing
functions depend upon primitives defined in the ckz module; if these
primitives cannot be supplied for a certain system, then the filename
parsing functions can be deleted, and the package will still be useful
for parsing keywords, numbers, arbitrary text strings, and so forth.
The style of interaction is the same as that found on the DECSYSTEM-20.
ckconu.c (Unix):
This is the connect module. As supplied, it should operate in any Unix
environment, or any C-based environment that provides the fork() function.
The module requires access to global variables that specify line speed,
parity, duplex, flow control, etc, but invokes functions from the ckx module
to accomplish the desired settings and input/output, and functions from the
ckz module to perform session logging. No terminal emulation is performed.
There is no code for controlling modems or dialers. The ckconu function may
be entirely replaced, so long as the global settings are honored by its
replacement. PC implementations of C-Kermit may require the ckcon module to
do screen control, escape sequence interpretation, etc, and may also wish to
write special code to get the best possible performance.
Moving C-Kermit to a new system entails:
1. Creating a new ckx module in C, assembler, or whatever language is
most appropriate for system programming on the new system.
2. Creating a new ckz module, as above.
3. If the system is not Unix-like, then a new ckuser module may be required,
as well as a different invocation of it from ckmain.
4. If the distributed connect module doesn't work or performs poorly, then
it may be replaced. For instance, interrupt-driven i/o may be required,
especially if the system doesn't have forks.
Those who favor a different style of user/program interaction from that
provided in ckuser.c may replace the entire module, for instance with one
that provides a mouse/window/icon environment, a menu/function-key
environment, etc.
IMPORTANT -- This description of the C-Kermit modules is based on a
pre-release test version of the program for Berkeley Unix 4.2. As of this
writing, the program has not yet been moved to any other system. Some
reorganization may be required in order to bring this program up on other
systems.
@//E*O*F ckermi.doc//
chmod u=rw,g=r,o=r ckermi.doc
echo x - ckermi.h
sed 's/^@//' > "ckermi.h" <<'@//E*O*F ckermi.h//'
/* ckermit.h -- Symbol and macro definitions for C-Kermit */
#include <stdio.h>
#include <ctype.h>
#include "ckdebu.h"
/* Mnemonics for ASCII characters */
#define SOH 001 /* ASCII Start of header */
#define BEL 007 /* ASCII Bell (Beep) */
#define BS 010 /* ASCII Backspace */
#define CR 015 /* ASCII Carriage Return */
#define XON 021 /* ASCII XON */
#define SP 040 /* ASCII Space */
#define DEL 0177 /* ASCII Delete (Rubout) */
/* Kermit parameters and defaults */
#define MAXPACK 94 /* Maximum packet size */
#define RBUFL 200 /* Receive buffer length */
#define CTLQ '#' /* Control char prefix I will use */
#define MYEBQ '&' /* 8th-Bit prefix char I will use */
#define MYRPTQ '~' /* Repeat count prefix I will use */
#define MAXTRY 10 /* Times to retry a packet */
#define MYPADN 0 /* How many padding chars I need */
#define MYPADC '\0' /* Which padding character I need */
#define DMYTIM 7 /* Default timeout interval to use. */
#define URTIME 10 /* Timeout interval to be used on me. */
#define DEFTRN 0 /* Default line turnaround handshake */
#define DEFPAR 0 /* Default parity */
#define MYEOL CR /* End-Of-Line character I need on packets. */
#define DRPSIZ 90 /* Default incoming packet size. */
#define DSPSIZ 90 /* Default outbound packet size. */
#define DDELAY 5 /* Default delay. */
#define DSPEED 9600 /* Default line speed. */
/* Files */
#define ZCTERM 0 /* Console terminal */
#define ZSTDIO 1 /* Standard input/output */
#define ZIFILE 2 /* Current input file */
#define ZOFILE 3 /* Current output file */
#define ZDFILE 4 /* Current debugging log file */
#define ZTFILE 5 /* Current transaction log file */
#define ZPFILE 6 /* Current packet log file */
#define ZSFILE 7 /* Current session log file */
#define ZNFILS 8 /* How many defined file numbers */
/* Macros */
#define tochar(ch) ((ch) + SP ) /* Number to character */
#define unchar(ch) ((ch) - SP ) /* Character to number */
#define ctl(ch) ((ch) ^ 64 ) /* Controllify/Uncontrollify */
#define unpar(ch) ((ch) & 127) /* Clear parity bit */
@//E*O*F ckermi.h//
chmod u=rw,g=r,o=r ckermi.h
echo x - ckermi.mak
sed 's/^@//' > "ckermi.mak" <<'@//E*O*F ckermi.mak//'
# Makefile to build C-Kermit for Berkeley Unix 4.2
kermit: ckmain.o ckcmd.o ckuser.o ckprot.o ckfns.o ckconu.o ckxbsd.o ckzbsd.o
cc -o kermit ckmain.o ckcmd.o ckuser.o ckprot.o ckfns.o ckconu.o ckzbsd.o ckxbsd.o
ckmain.o: ckmain.c ckermi.h
ckuser.o: ckuser.c ckcmd.h ckermi.h
ckcmd.o: ckcmd.c ckcmd.h
ckprot.o: ckprot.c ckermi.h
ckprot.c: ckprot.w wart
wart ckprot.w ckprot.c
ckfns.o: ckfns.c ckermi.h
ckzbsd.o: ckzbsd.c ckermi.h
ckxbsd.o: ckxbsd.c
ckconu.o: ckconu.c
wart: ckwart.o
cc -o wart ckwart.o
ckwart.o: ckwart.c
@//E*O*F ckermi.mak//
chmod u=rw,g=r,o=r ckermi.mak
echo Inspecting for damage in transit...
temp=/tmp/shar$$; dtemp=/tmp/.shar$$
trap "rm -f $temp $dtemp; exit" 0 1 2 3 15
cat > $temp <<\!!!
1159 8198 51955 ckermi.doc
59 367 2307 ckermi.h
28 66 537 ckermi.mak
1246 8631 54799 total
!!!
wc ckermi.doc ckermi.h ckermi.mak | sed 's=[^ ]*/==' | diff -b $temp - >$dtemp
if [ -s $dtemp ]
then echo "Ouch [diff of wc output]:" ; cat $dtemp
else echo "No problems found."
fi
exit 0
More information about the Comp.sources.unix
mailing list