|
…
|
||
|---|---|---|
| .. | ||
| ANNOUNCE | ||
| COPYING | ||
| README | ||
| gcmdline.c | ||
| gkermit.c | ||
| gkermit.h | ||
| gkermit.nr | ||
| gproto.c | ||
| gproto.w | ||
| gunixio.c | ||
| gwart.c | ||
| makefile | ||
README
G-Kermit -- GNU Kermit -*- text -*-
Version 1.00 : 25 December 1999
Author:
Frank da Cruz
The Kermit Project
Columbia University
612 West 115th Street
New York NY 10025-7799 USA
fdc@columbia.edu
CONTENTS...
1. OVERVIEW
2. INVOKING G-KERMIT
3. COMMAND-LINE OPTIONS
4. THE MECHANICS OF FILE TRANSFER
5. INTERRUPTING FILE TRANSFER
6. TEXT AND BINARY TRANSFER MODE
7. PATHNAMES
8. FILENAME CONVERSION
9. FILENAME COLLISIONS
10. KERMIT PROTOCOL DETAILS
11. PROBLEMS, BUGS, ERRORS
12. BUILDING G-KERMIT
13. INSTALLING G-KERMIT
14. DESIGN AND IMPLEMENTATION NOTES
1. OVERVIEW
G-Kermit is a Unix program for uploading and downloading files with the
Kermit protocol. G-Kermit is a product of Kermit Project at Columbia
University. It is free software under the GNU Public License. See the
COPYING file for details.
G-Kermit is:
. Fast
. Small
. Portable
. Easy to use
. Interoperable
. Low-maintenance
. Stable and reliable
Features include:
. Text and binary file transfer on both 7-bit and 8-bit connections
. Files can be transferred singly or in groups
. Automatic startup configuration via GKERMIT environment variable
. Configurability as an external protocol
Kermit protocol features include:
. Automatic peer recognition
. Streaming on reliable connections
. Selectable packet length, 40 to 9000 bytes (4000 default)
. Single shifts for 8-bit data on 7-bit connections
. Control-character prefixing for control-character transparency
. Control-character unprefixing for increased speed (incoming only)
. Compression of repeated bytes
. Per-file and batch cancellation
Features selectable on command line:
. Text or binary mode transfer
. Filename conversion on/off
. Filename collision backup versus overwrite
. Keep or discard incompletely received files
. Packet length
. Packet timeout
. Flow control
. Parity
. Streaming
. Messages
. Debugging
Features not included (see Section 14):
. Making connections
. Character-set translation
. Interactive commands and scripting
. File date-time stamps
2. INVOKING G-KERMIT
G-Kermit is always on the "far end" of a connection, on a Unix system that
you have made a connection to from a terminal emulator by dialup, network,
or direct serial. If you have a direct or dialup serial connection into
Unix, use the "stty -a" or "stty all" command to see if your Unix terminal
driver is conditioned for the appropriate kind of flow control; if it isn't,
very few applications (including gkermit) will work well, or at all. The
command for setting terminal flow control varies from platform to platform,
but it is usually something like this:
$ stty crtscts
(where "$ " is the shell prompt) for RTS/CTS hardware flow control, or:
$ stty ixon ixoff
for Xon/Xoff "software" flow control. When you have a network connection,
flow control is usually nothing to worry about, since the network protocol
(TCP or X.25) takes care of it automatically, but on certain platforms (such
as HP-UX) the TCP/IP Telnet or Rlogin server uses this for flow control
between itself and the underlying pseudoterminal in which your session runs,
so Xon/Xoff might be required for these sessions too.
The G-Kermit binary is called "gkermit". It should be stored someplace in
your Unix PATH, such as /usr/local/bin/gkermit or somewhere in the /opt tree
on System V R4. To run G-Kermit, just type "gkermit" followed by command-
line options that tell it what to do. If no options are given, G-Kermit
prints a usage message listing the available options:
G-Kermit CU-1.00, Columbia University, 1999-12-25: POSIX.
Usage: gkermit [ options ]
Options:
-r Receive files
-s fn Send files
-g fn Get files from server
-a fn As-name for single file
-i Image (binary) mode transfer
-T Text mode transfer
-P Path/filename conversion disabled
-w Write over existing files with same name
-K Keep incompletely received files
-p x Parity: x = o[dd],e[ven],m[ark],s[pace],n[one]
-e n Receive packet-length (40-9000)
-b n Timeout (sec, 0 = none)
-x Force Xon/Xoff (--x = Don't force Xon/Xoff)
-S Disable streaming
-X External protocol
-q Quiet (suppress messages)
-d [fn] Debug to ./debug.log [or specified file]
-h Help (this message)
More info: http://www.columbia.edu/kermit/ <kermit@columbia.edu>
If an option takes an argument, the argument is required; if an option does
not take an argument, no argument may be given (exceptions: -d may or may
not take an argument; -s can take 1 or more arguments).
The action options are -r, -s, and -g. Only one action option may be given.
If no action options are given, G-Kermit does nothing (except possibly
printing its usage message or creating a debug.log file). Here are some
examples (in which "$ " is the shell prompt):
$ gkermit -s hello.c <-- Sends the hello.c file.
$ gkermit -s hello.* <-- Sends all hello.* files.
$ gkermit -r <-- Waits for you to send a file to it.
$ gkermit -g hello.c <-- Gets the hello.c file from your computer.
$ gkermit -g \*.c <-- Gets all *.c files from your computer.
Options that do not take arguments can be "bundled" with other options.
An option that takes an argument must always be followed by a space and
then its argument(s). Examples:
$ gkermit -is hello.o <-- Sends hello.o in binary mode.
$ gkermit -dSr <-- Receives with debugging and no streaming.
G-Kermit's exit status is 0 if all operations succeeded and 1 if there were
any failures. If a group of files was transferred, the exit status is 1
if one or more files was not successfully transferred and 0 if all of them
were transferred successfully.
3. COMMAND-LINE OPTIONS
-r RECEIVE: This option tells G-Kermit to receive a file or files;
that is, to passively wait for you to send files from your
terminal emulator.
-s fn SEND: This tells G-Kermit to send the file or files specified by
fn, which can be a filename, a regular expression, or a list of
filenames and/or regular expressions (wildcards). Regular
expressions are interpreted and expanded by your shell into the
list of names of files that is given to G-Kermit. For example
"*.c" expands to a list of all files in the current directory
whose names end with ".c".
-g fn GET: This option tells G-Kermit to get a file (or files) from a
Kermit server. It is useful only when your terminal emulator
supports the Kermit autodownload feature AND it includes a Kermit
server mode. It is equivalent to "gkermit -r", escaping back,
telling your terminal emulator to send the given files, and then
reconnecting to Unix.
-a fn AS-NAME: When used with -s, this option tells G-Kermit to send
the file whose name is given as the first -s argument under the
name fn. For example, "gkermit -s game -a work" sends the file
called "game" under the name "work", so the receiver will think
its name is "work". When given with the -r or -g command, the
incoming file (or the first incoming file if there is more than
one) is stored under the name fn. In all cases, the given name
is used as-is; it is not converted.
-i IMAGE (binary) mode transfer. When used with -s, tells G-Kermit
to send in binary mode. When used with -r, tells G-Kermit to
receive in binary mode if the file sender does not specify the
transfer mode (text or binary). When used with -g, tells
G-Kermit to ask your terminal emulator's Kermit to send the given
file in binary mode. See Section 6 for details.
-T TEXT mode transfer (note uppercase T). When used with -s, tells
G-Kermit to send in text mode. When used with -r, tells G-Kermit
to receive in text mode if the file sender does not specify the
transfer mode (text or binary). When used with -g, tells G-Kermit
to ask your emulator's Kermit to send the given file in text mode.
See Section 6 for details.
-P PATH (filename) conversion disabled (note uppercase P).
Normally when sending files, G-Kermit converts filenames to a
form that should be acceptable to non-Unix platforms, primarily
changing lowercase letters to uppercase, ensuring there is no
more than one period, and replacing any "funny" characters by X
or underscore (explained in Section 8).
-w WRITEOVER. When receiving, and an incoming file has the same
name as an existing file, write over the existing file. By
default G-Kermit backs up the existing file by adding a suffix
to its name (see Section 9).
-K KEEP incompletely received files. Normally when receiving files,
and a file transfer is interrupted, G-Kermit discards the
partially received file so you won't think you have the whole
file. Include -K on the command line to tell G-Kermit to keep
partially received files, e.g. "gkermit -Kr".
-p x PARITY: Use the given kind of parity, where x can be 'n' for
None (which is the default, for use on 8-bit-clean connections);
's' for Space, 'e' for Even, 'o' for Odd, and 'm' for Mark. 's'
might be needed on certain Telnet connections; 'e', 'o', and 'm'
are only for serial connections; don't try them on TCP/IP
connections.
-e n PACKET LENGTH: Receive packet-length, where n can be any number
between 40 and 9000. The default length on most platforms is
4000. Use this option to specify a different length; usually
this would be necessary only if transfers fail using the default
length due to some kind of buffering problem in the host or along
the communication path. Example: "gkermit -e 240 -r".
-b n TIMEOUT (sec, 0 = none). Specify the number of seconds to wait
for a packet before timing out and retransmitting. By default,
G-Kermit uses whatever timeout interval your terminal emulator's
Kermit asks it to use. No need to change this unless the timeout
action causes problems.
-x XON/XOFF. Force Xon/Xoff flow control in the Unix terminal
driver. Try this if uploads fail without it. But don't use it
if you don't need to; on some platforms or connections it hurts
rather than helps.
--x Don't force Xon/Xoff; for use when G-Kermit was built with the
SETXONXOFF compile-time option (Section 12), to override the
automatic setting of Xon/Xoff in case it interferes with file
transfers.
-S STREAMING disabled. Streaming is a high-performance option to
be used on reliable connections, such as in Telnet or Rlogin
sessions. It is used if your terminal emulator's Kermit requests
it. Use the -S option (note: uppercase S) to suppress this
feature in case it causes trouble. Details in Section 10.
-X EXTERNAL PROTOCOL. Include this option when invoking G-Kermit
from another program that redirects G-Kermit's standard i/o,
e.g. over a connection to another computer. If you omit this
switch when using G-Kermit as an external protocol to another
communications program, G-Kermit is likely to perform illegal
operations and exit prematurely. If you include this switch
when G-Kermit is NOT an external protocol to another program,
file transfers will fail. G-Kermit has no way of determining
automatically whether it is being used as an external protocol.
-q QUIET. Suppresses messages.
-d DEBUG. Use this for troubleshooting. It creates a file called
debug.log in your current directory, to be used in conjunction
with the source code, or sent to the Kermit support address for
analysis. More about this in Section 11.
-d fn DEBUG to specified file (rather than default ./debug.log).
-h HELP: Displays the usage message shown above.
You may supply options to G-Kermit on the command line or through the
GKERMIT environment variable, which can contain any valid gkermit
command-line options. These are processed before the actual command-line
options and so can be overridden by them. Example for bash or ksh, which
you can put in your profile if you want to always keep incomplete files,
suppress streaming, suppress messages, and use Space parity:
export GKERMIT="-K -S -q -p s"
G-Kermit's options are compatible with C-Kermit's, with the following
exceptions:
-P (available only in C-Kermit 7.0 and later)
-K (currently not used in C-Kermit)
-b (used in C-Kermit for serial device speed)
-S (used in C-Kermit to force an interactive command prompt)
-x (used in C-Kermit to start server mode)
--x (currently not used in C-Kermit)
-X (currently not used in C-Kermit)
4. THE MECHANICS OF FILE TRANSFER
To transfer files with G-Kermit you must be connected through a terminal
emulator to the Unix system where G-Kermit is installed, meaning you are
online to Unix and have access to the shell prompt (or to some menu that has
an option to invoke G-Kermit), and your terminal emulator must support the
Kermit file transfer protocol. The connection can be serial (direct or
dialed) or network (Telnet, Rlogin, X.25, etc).
4.1. Sending Files
When you tell G-Kermit to SEND a file (or files), e.g. with:
$ gkermit -Ts oofa.txt
it pauses for a second and then sends its first packet. What happens next
depends on the capabilities of your terminal emulator:
. If your emulator supports Kermit "autodownloads" then it receives the
file automatically and puts you back in the terminal screen when done.
. Otherwise, you'll need to take whatever action is required by your
emulator to get its attention: a mouse action, a keystroke like Alt-x,
or a character sequence like Ctrl-\ or Ctrl-] followed by the letter
"c" (this is called "escaping back") and then tell it to receive the
file. When the transfer is complete, you might have to instruct your
emulator to go back to its terminal screen.
During file transfer, most terminal emulators put up some kind of running
display of the file transfer progress.
4.2. Receiving Files
When you tell G-Kermit to RECEIVE, this requires you to escape back to your
terminal emulator and instruct it to send the desired file(s). Autodownload
is not effective in this case. When the transfer is complete, you'll need
to instruct your emulator to return to its terminal screen.
4.3. Getting Files
If your terminal emulator supports Kermit autodownloads AND server mode, you
can use GET ("gkermit -g files...") rather than RECEIVE ("gkermit -r"), and
the rest happens automatically, as when G-Kermit is sending.
5. INTERRUPTING FILE TRANSFER
G-Kermit supports file and group interruption. The method for interrupting
a transfer depends on your terminal emulator. For example, while the
file-transfer display is active, you might type the letter 'x' to cancel the
current file and go on to the next one (if any), and the letter 'z' to
cancel the group. Or there might be buttons you can click with your mouse.
When G-Kermit is in packet mode and your terminal emulator is in its
terminal screen, you can also type three (3) Ctrl-C characters in a row to
make G-Kermit exit and restore the normal terminal modes.
6. TEXT AND BINARY TRANSFER MODE
When sending files in binary mode, G-Kermit sends every byte exactly as it
appears in the file. This mode is appropriate for program binaries,
graphics files, tar archives, compressed files, etc, and is G-Kermit's
default file-transfer mode when sending. When receiving files in binary
mode, G-Kermit simply copies each byte to disk. (Obviously the bytes are
encoded for transmission, but the encoding and decoding procedures give a
replica of the original file after transfer.)
When sending files in text mode, G-Kermit converts the record format to the
common one that is defined for the Kermit protocol, namely lines terminated
by carriage return and linefeed (CRLF); the receiver converts the CRLFs to
whatever line-end or record-format convention is used on its platform. When
receiving files in text mode, G-Kermit simply strips carriage returns,
leaving only a linefeed at the end of each line, which is the Unix
convention.
When receiving files, the sender's transfer mode (text or binary)
predominates if the sender gives this information to G-Kermit in a Kermit
File Attribute packet, which of course depends on whether your terminal
emulator's Kermit protocol has this feature. Otherwise, if you gave a -i or
-T option on the gkermit command line, the corresponding mode is used;
otherwise the default mode (binary) is used.
Furthermore, when either sending or receiving, G-Kermit and your terminal
emulator's Kermit can inform each other of their OS type (Unix in G-Kermit's
case). If your emulator supports this capability, which is called
"automatic peer recognition", and it tells G-Kermit that its platform is
also Unix, G-Kermit and the emulator's Kermit automatically switch into
binary mode, since no record-format conversion is necessary in this case.
Automatic peer recognition is disabled automatically if you include the -i
(image) or -T (text) option.
When sending, G-Kermit sends all files in the same mode, text or binary.
There is no automatic per-file mode switching. When receiving, however,
per-file switching occurs automatically based on the incoming Attribute
packets, if any (explained below), that accompany each file, so if the
file sender switches types between files, G-Kermit follows along.
7. PATHNAMES
When SENDING a file, G-Kermit obtains the filenames from the command line.
It depends on the shell to expand metacharacters (wildcards and tilde).
G-Kermit uses the full pathname given to find and open the file, but then
strips the pathname before sending the name to the receiver. For example:
$ gkermit -s /etc/hosts
results in an arriving file called "HOSTS" or "hosts" (the directory part,
"/etc/", is stripped; see next section about capitalization).
However, if a pathname is included in the -a option, the directory part
is not stripped:
$ gkermit -s /etc/hosts -a /tmp/hosts
This example sends the /etc/hosts file but tells the receiver that its name
is "/tmp/hosts". What the receiver does with the pathname is, of course, up
to the receiver, which might have various options for dealing with incoming
pathnames.
When RECEIVING a file, G-Kermit does NOT strip the pathname, since incoming
files normally do not include a pathname unless you told your terminal to
include them or gave an "as-name" including a path when sending to G-Kermit.
If the incoming filename includes a path, G-Kermit tries to store the file
in the specified place. If the path does not exist, the transfer fails.
The incoming filename can, of course, be superseded with the -a option.
8. FILENAME CONVERSION
When sending a file, G-Kermit normally converts outbound filenames to
common form: uppercase, no more than one period, and no funny characters.
So, for example, gkermit.tar.gz would be sent as GKERMIT_TAR.GZ.
When receiving a file, if the name is all uppercase, G-Kermit converts it
to all lowercase. If the name contains any lowercase letters, G-Kermit
leaves the name alone. Otherwise G-Kermit accepts filename characters as
they are, since Unix allows filenames to contain practically any characters.
If the automatic peer recognition feature is available in the terminal
emulator, and G-Kermit recognizes the emulator's platform as Unix, G-Kermit
automatically disables filename conversion and sends and accepts filenames
literally.
You can force literal filenames by including the -P option on the command
line.
9. FILENAME COLLISIONS
When G-Kermit receives a file whose name is the same as that of an existing
file, G-Kermit backs up the existing file by adding a unique suffix to its
name. The suffix is ".~n~", where n is a number between 1 and 999. This
the same kind of backup suffix used by GNU EMACS and C-Kermit (both of which
can be used to prune excess backup files). But since G-Kermit does not read
directories (see Implementation Notes below), it can not guarantee that the
number chosen will be higher than any other backup prefix number for the
same file. In fact, the first free number, starting from 1, is chosen. If
an incoming file already has a backup suffix, G-Kermit strips it before
adding a new one, rather than creating a file that has two backup suffixes.
To defeat the backup feature and have incoming files overwrite existing
files of the same name, include the -w (writeover) option on the command
line.
If G-Kermit has not been been given the -w option and it fails to create a
backup file, the transfer fails.
10. KERMIT PROTOCOL DETAILS
Block check
G-Kermit uses the 3-byte, 16-bit CRC by default. If the other Kermit
does not agree, both Kermits automatically drop down to the single-byte
6-bit checksum that is required of all Kermit implementations.
Attributes
When sending files, G-Kermit conveys the file transfer mode and file
size in bytes to the receiver in an Attribute (A) packet if the use of
A-packets was negotiated. This allows the receiver to switch to the
appropriate mode automatically, and to display the percent done, estimated
time left, and/or a thermometer bar if it has that capability. When
receiving, G-Kermit looks in the incoming A-packet, if any, for the
transfer mode (text or binary) and switches itself accordingly on a
per-file basis.
Handling of the Eighth Bit
G-Kermit normally treats the 8th bit of each byte as a normal data bit.
But if you have a 7-bit connection, transfers of 8-bit files fail unless
you tell one or both Kermits to use the appropriate kind of parity, in
which case Kermit uses single-shift escaping for 8-bit bytes. Generally,
telling either Kermit is sufficient; it tells the other. Use the -p
option to tell G-Kermit which parity to use. Locking shifts are not
included in G-Kermit.
Control-Character Encoding
G-Kermit escapes all control characters when sending (for example,
Ctrl-A becomes #A). When receiving, it accepts both escaped and bare
control characters, including NUL (0). However, unescaped control
characters always present a danger, so if uploads to G-Kermit fail, tell
your terminal emulator's Kermit to escape most or all control characters
(in C-Kermit and Kermit 95 the command is SET PREFIXING CAUTIOUS or SET
PREFIXING ALL).
Packet Length
All legal packet lengths, 40-9020, are supported although a lower
maximum might be imposed on platforms where it is known that bigger ones
don't work. When receiving, G-Kermit sends its receive packet length to
the sender, and the sender must not send packets any longer than this
length. The default length for most platforms is 4000 and it may be
overridden with the -e command-line option.
Sliding Windows
G-Kermit does not support sliding windows. Streaming is used instead.
If the other Kermit bids to use sliding windows, G-Kermit declines.
Streaming
If the terminal emulator's Kermit informs G-Kermit that it has a
reliable connection (such as TCP/IP or X.25), and the emulator's Kermit
supports streaming, then a special form of the Kermit protocol is used
in which data packets are not acknowledged; this allows the sender to
transmit a steady stream of (framed and checksummed) data to the
receiver without waiting for acknowledgements, allowing the fastest
possible transfers. Streaming overcomes such obstacles as long round
trip delays, unnecessary retransmissions on slow network connections,
and most especially the TCP/IP Nagle and Delayed ACK heuristics which
are deadly to a higher-level ACK/NAK protocol. When streaming is in use
on a particular connection, Kermit speeds are comparable to FTP. The
drawback of streaming is that transmission errors are fatal; that's why
streaming is only used on reliable connections, which, by definition,
guarantee there will be no transmission errors. However, watch out for
the relatively rare circumstance in which emulator thinks it has a
reliable connection when it doesn't -- for example a Telnet connection
to a terminal server, and a dialout from the terminal server to the
host. Use the -S option on the command line to defeat streaming in such
situations.
Using all defaults on a TCP/IP connection on 10BaseT (10Mbps) Ethernet from
a modern Kermit program like C-Kermit 7.0 or Kermit 95, typical transfer
rates are 150-500Kcps.
11. PROBLEMS, BUGS, ERRORS
If file transfers fail:
. Make sure your terminal emulator is not unprefixing control characters;
various control characters might cause trouble along the communication
path. When in doubt, instruct the file sender to prefix all control
characters.
. Make sure your Unix terminal is conditioned for the appropriate kind
of flow control.
. Use command-line options to back off on performance and transparency;
use -S to disable streaming, -e to select a shorter packet length, -p
to select space or other parity, -b to increase or disable the timeout,
and/or establish the corresponding settings on your emulator.
When receiving files in text mode, G-Kermit strips all carriage returns,
even if they aren't part of a CRLF pair.
If you have a TCP/IP connection (e.g. Telnet or Rlogin) to Unix from a
terminal emulator whose Kermit protocol does not support streaming,
downloads from G-Kermit are likely to be as much as 10 or even 100 times
slower than uploads if the TCP/IP stack engages in Nagle or Delayed ACK
heuristics; typically, when your terminal emulator's Kermit protocol sends
an acknowledgment, the TCP stack holds on to it for (say) 1/5 second before
sending it, because it is "too small" to send right away.
As noted in Section 9, the backup prefix is not guaranteed to be the highest
number. For example, if you have files oofa.txt, oofa.txt.~1~, and
oofa.txt.~3~ in your directory, and a new oofa.txt file arrives, the old
oofa.txt is backed up to oofa.txt.~2~, rather than oofa.txt.~4~ as you might
expect. This is because gkermit lacks directory reading capabilities, for
reasons noted in Section 14, and without this, finding the highest existing
backup number for a file is impractical.
If you send a file to G-Kermit with streaming active when the connection is
not truly reliable, all bets are off. A fatal error should occur promptly,
but if huge amounts of data are lost, G-Kermit might never recognize a single
data packet and therefore not diagnose a single error; yet your terminal
emulator keeps sending packets since no acknowledgments are expected; the
transfer eventually hangs at the end of file. Use -S on G-Kermit's command
line to disable streaming in situations where the terminal emulator requests
it in error.
You can use G-Kermit's debug log for troubleshooting; this is useful mainly
in conjunction with the source code. But even if you aren't a C programmer,
it should reveal any problem in enough detail to help pinpoint the cause of
the failure. "gkermit -d" (with no action options) writes a short debug.log
file that shows the build options and settings.
The debug log is also a packet log; to extract the packets from it, use:
grep ^PKT debug.log
Packets in the log are truncated to avoid wrap-around on your screen, and
they have the Ctrl-A packet-start converted to ^ and A to avoid triggering
a spurious autodownload when displaying the log on your screen.
In certain circumstances it is not desirable or possible to use -d to create
a log file called debug.log in the current directory; for example, if you
don't have write access to the current directory, or you already have a
debug.log file that you want to keep (or transfer). In this case, you can
include a filename argument after -d:
gkermit -d /tmp/testing.log -s *.c
(This is an exception to the rule that option arguments are not optional.)
If all else fails, you can contact the Kermit Project for technical support;
see:
http://www.columbia.edu/kermit/support
for instructions.
12. BUILDING G-KERMIT
G-Kermit is written to require the absolute bare minimum in system services
and C-language features and libraries, and therefore should be portable to
practically any Unix platform at all with any C compiler.
The source files are:
makefile The build procedure
gwart.c Source code for a mini-lex substitute
gproto.w G-Kermit protocol state machine to be preprocessed by gwart
gkermit.h G-Kermit header file
gkermit.c G-Kermit main module and routines
gcmdline.c G-Kermit command-line parser
gunixio.c Unix-specific i/o routines
A simple makefile is provided, which can be used with make or gmake. There
are three main targets in the makefile:
posix
Build for any POSIX.1 compliant platform (termios). This is the
default target, used if you type "make" (or "gmake") alone. This
target works for most modern Unixes, including GNU/Linux, FreeBSD,
OpenBSD, NetBSD, BSDI, HP-UX, Solaris, SunOS, Unixware, AIX, etc.
sysv
Build for almost any AT&T System V platform (termio). Examples
include AT&T Unix releases, e.g. for the AT&T 7300, HP-UX versions
prior to 7.00.
bsd
Build for any BSD (pre-4.4) or Unix V7 platform (sgtty). Examples
include NeXTSTEP 3.x, OSF/1, and 4.3BSD or earlier.
Note that the target names are all lowercase; "posix" is the default target
(the one used if you just type "make"). If the build fails with a message
like:
gunixio.c: 65: Can't find include file termios.h
*** Error code 1
then try "make sysv" or "make bsd". See the build list below for examples.
Some special build targets are also provided:
sysvx
Like sysv but uses getchar()/putchar() for packet i/o rather than
buffered nonblocking read()/write(); this is necessary for certain
very old System V platforms (see description of USE_GETCHAR below).
stty
When none of the other targets compiles successfully, try this one,
which runs the external stty program rather than trying to use
API calls to get/set terminal modes (system("stty raw -echo") and
system("stty -raw echo")).
Several maintenance/management targets are also included:
clean
Remove object and intermediate files.
install
Install gkermit (read the makefile before using this).
uninstall
Uninstall gkermit from wherever "make install" installed it.
The default compiler is cc. To override (e.g. to force the use of gcc on
computers that have both cc and gcc installed, or that don't have cc), use:
[g]make CC=gcc [<target>]
No other tools beyond make, the C compiler and linker, a short list of
invariant header files, and the standard C library are needed or used. The
resulting binary should be 100K or less on all hardware platforms (and 64K
or less on most; see list below).
You may also specify certain build options by including a KFLAGS clause on
the make command line, e.g.:
make "KFLAGS=-DSETXONXOFF -DEXTRADEBUG" sysv
By default, nonblocking buffered read() is used for packets; this technique
works on most platforms but other options -- USE_GETCHAR and DUMBIO -- are
provided when it doesn't work or when nonblocking i/o is not available.
The build options include:
__STDC__
Include this when the compiler requires ANSI prototyping but does
does not define __STDC__ itself. Conversely, you might need to
include -U__STDC__ if the compiler defines __STDC__ but does not
support minimum ANSI features.
ULONG=long
Include this if compilation fails with "unknown type: unsigned long".
CHAR=char
Include this if compilation fails with "unknown type: unsigned char".
SMALL
Define this when building on or for a "small" platform, for example
a 16-bit architecture.
USE_GETCHAR
Specifies that packet i/o should be done with (buffered) getchar()
and putchar() rather than the default method of nonblocking,
internally buffered read() and write(). Use this only when G-Kermit
does not build or run otherwise, since if the default i/o code is
not used, G-Kermit won't be able to do streaming.
DUMBIO
Specifies that packet i/o should be done with blocking single-byte
read() and write(). Use this only when G-Kermit doesn't build or
run, even with USE_GETCHAR.
MAXRP=nnn
Change the maximum receive-packet length to something other than the
default, which is 9020. You should change this only to make it smaller;
making it bigger is not supported by the Kermit protocol.
DEFRP=nnn
Change the default receive packet length to something other than the
default, which is 4000. Making it any bigger than this is not advised.
TINBUFSIZ=nnn
On builds that use nonblocking buffered read(), override the default
input buffer size of 4080.
SETXONXOFF
On some platforms, mainly those based on System V R4 and earlier, it was
found that receiving files was impossible on TCP/IP connections unless
the terminal driver was told to use Xon/Xoff flow control. If downloads
work but uploads consistently fail (or fail consistently whenever
streaming is used or the packet length is greater than a certain number
like 100, or 775), try adding this option. When gkermit is built with
this option, it is equivalent to the user always giving the -x option on
the command line. (Most versions of HP-UX need this; it is defined
automatically at compile time if __hpux is defined.)
SIG_V
The data type of signal handlers is void. This is set automatically
for System V and POSIX builds.
SIG_I
The data type of signal handlers is int. This is set automatically
for BSD builds.
NOGETENV
Add this to disable the feature in which G-Kermit gets options from
the GKERMIT environment variable.
NOSTREAMING
Add this to disable streaming.
EXTRADEBUG
This adds a lot (a LOT) of extra information to the debug log
regarding packet and character-level i/o.
FULLPACKETS
Show full packets in the debug log rather than truncating them.
Any compiler warnings should be harmless. Examples include:
"Passing arg 2 of `signal' from incompatible pointer"
(or "Argument incompatible with prototype"):
Because no two Unix platforms agree about signal handlers. Harmless
because the signal handler does not return a value that is used. We
don't want to open the door to platform-specific #ifdefs just to
silence this warning. However, you can include -DSIG_I or -DSIG_V
on the CC command line to override the default definitions.
"<blah> declared but never used":
Some function parameters are not used because they are just placeholders
or compatibility items, or even required by prototypes in system headers.
Others might be declared in system header files (like mknod, lstat, etc,
which are not used by G-Kermit).
"Do you mean equality?":
No, in "while (c = *s++)" the assignment really is intentional.
"Condition is always true":
Yes, "while (1)" is always true.
"Flow between cases":
Intentional.
"No flow into statement":
In gproto.c, because it is a case statement generated by machine,
not written by a human.
The coding conventions are aimed at maximum portability. For example:
. Only relatively short identifiers.
. No long character-string constants.
. Only #ifdef, #else, #endif, #define, and #undef preprocessor directives.
. Any code that uses ANSI features is enclosed in #ifdef __STDC__..#endif.
. No gmake-specific constructs in the makefile.
Here are some sample builds (December 1999):
Platform Size Target Notes
Apple Mac OS X 1.0 gcc: 48K posix (AKA Rhapsody 5.5)
AT&T 3B2/300 SVR2 cc: 49K sysv (4)
AT&T 6300 PLUS cc: 58K sysv (6)
AT&T 7300 UNIX PC cc: 40K sysv
AT&T 7300 UNIX PC gcc: 55K sysv (23K with shared lib)
BSDI 4.0.1 gcc: 34K posix
DEC 5000 MIPS Ultrix 4.3 cc: 99K posix
DEC Alpha Digital UNIX 3.2 cc: 98K bsd (AKA OSF/1) (1)
DEC Alpha Tru64 UNIX 4.0e cc: 82K bsd (1)
DEC PDP-11 2.11BSD cc: 40K bsd211 (7)
DG/UX 5.4R3.10 cc: 52K posix
DG/UX 5.4R4.11 gcc: 51K posix
DYNIX/ptx 4.4.2 cc: 43K posix
FreeBSD 2.2.7 gcc: 41K posix
FreeBSD 3.3 gcc: 34K posix
GNU/Linux RH 5.2 gcc: 35K posix (RH = Red Hat)
GNU/Linux RH 6.1 gcc: 44K posix
GNU/Linux SW 3.5 gcc: 34K posix (SW = Slackware)
GNU/Linux SW 4.0 gcc: 36K posix
GNU/Linux SW 7.0 gcc: 44K posix
HP-UX 5.21 cc: 55K sysv (2)
HP-UX 6.5 cc: 40K sysv (5)
HP-UX 7.05 cc: 50K posix
HP-UX 8.00 gcc: 33K posix
HP-UX 9.05 cc: 57K posix
HP-UX 10.01 cc: 57K posix
HP-UX 10.20 cc: 61K posix
IBM AIX 3.2 IBM cc: 62K posix
IBM AIX 4.1.1 IBM cc: 67K posix
IBM AIX 4.3.2 IBM cc: 69K posix
Motorola 88K SV/88 R4.3 42K posix
Motorola 68K SV/68 R3.6 56K sysv (4)
NetBSD 1.4.1 gcc: 41K posix
NeXTSTEP m68k 3.1 gcc: 77K bsd (3)
NeXTSTEP m68k 3.3 gcc: 78K bsd (3)
OpenBSD 2.5 gcc: 47K posix
QNX 4.25 cc: 33K posix
SCO XENIX 2.3.4 cc: 41K sysv (4)
SCO UNIX 3.2v4.2 cc: 73K posix
SCO UNIX 3.2v4.2 gcc: 61K posix
SCO ODT 3.0 cc: 97K posix
SCO OSR5.0.5 gcc: 42K posix
SCO Unixware 2.1.3 cc: 38K posix
SCO Unixware 7.0.1 cc: 37K posix
SGI IRIX 5.3 cc: 86K posix
SGI IRIX 6.5.4 cc: 91K posix
SINIX 5.42 MIPS cc: 57K posix
Solaris 2.4 cc: 50K posix
Solaris 2.5.1 cc: 51K posix
Solaris 2.6 cc: 52K posix
Solaris 7 cc: 52K posix
SunOS 4.1.3 cc: 57K posix
SunOS 4.1.3 gcc: 64K posix
Notes:
(1) "make posix" builds without complaint on OSF/1 (Digital UNIX (Tru64))
but it doesn't work -- i/o hangs or program dumps core. "make bsd"
works fine.
(2) POSIX APIs not available in this antique OS (circa 1983). Also due
to limited terminal input buffering capacity, streaming must be
disabled and relatively short packets must be used when receiving:
"gkermit -Se 250 -r". However, it can use streaming when sending.
(3) POSIX APIs not available.
(4) On System V R3 and earlier, EWOULDBLOCK is not defined, so we use EGAIN
instead. No special build procedures needed.
(5) Built with 'make -i "KFLAGS=-DDEFRP=512 -DUSE_GETCHAR" sysv'. It can
be built without -DUSE_GETCHAR but doesn't work.
(6) Use 'make "CC=cc -Ml" "KFLAGS=-DUSE_GETCHAR sysv'. It builds but
doesn't work, reason unknown, but probably because it was never designed
to be accessed remotely in the first place.
(7) This is a 16-bit architecture. A special makefile target is needed
because its make program does not expand the $(CC) value when invoking
second-level makes. Packet and buffer sizes are reduced to keep
static data within limits. Overlays are not needed.
13. INSTALLING G-KERMIT
The makefile creates a binary called "gkermit". Simply move this binary to
the desired directory, such as /usr/local/bin. It needs no special
permissions other than read, write, and execute for the desired users and
groups: no setuid, no setgid, or any other form of privilege. It should be
called "gkermit" and not "kermit", since "kermit" is the binary name for
C-Kermit, and the two are likely to be installed side by side on the same
computer; even when they are not, consistent naming is better for support
and sanity purposes. There is also a short man page:
gkermit.nr
You can view it with:
nroff -man gkermit.nr | more
Rename and store it appropriately. In addition, this file itself (README)
should be made available in a public documentation directory as:
gkermit.txt
The makefile includes a SAMPLE 'install' target that does all this. Please
read it before use to be sure the appropriate directories and permissions
are indicated. There is also an 'uninstall' target to undo an installation.
Obviously you need write access to the relevant directories before you can
install or uninstall G-Kermit.
14. DESIGN AND IMPLEMENTATION NOTES
A primary objective in developing G-Kermit is that it can be released and
used forever without constant updates to account for platform idiosyncracies
and changes. For this reason, certain features have been deliberately
omitted:
. File timestamps. The methods for dealing with internal time formats
are notoriously unportable and also a moving target, especially now
with the 32-bit internal time format rollover looming in 2038 and the
time_t data type changing out from under us. Furthermore, by excluding
any date-handling code, G-Kermit is automatically Y2K, 2038, and Y10K
compliant.
. Internal wildcard expansion, recursive directory traversal, etc. Even
after more than 30 years, there is still no standard and portable
service in Unix for this.
. Hardware flow control, millisecond sleeps, nondestructive input buffer
peeking, threads, select(), file permissions, etc etc.
Other features are omitted to keep the program small and simple, and to
avoid creeping featurism:
. Sliding windows. This technique is more complicated than streaming but
not as fast, and furthermore would increase the program size by a
factor of 5 or 10 due to buffering requirements.
. An interactive command parser and scripting language (because users
always want more and more commands and features).
. Character set conversion (because users always want more and more
character sets). Adding character set support would increase the
program size by a factor of 2 to 4, depending on the selection of sets.
. Making connections (because this requires huge amounts of tricky and
unstable high-maintenance platform- and device-specific code for serial
ports, modems, modem signals, network stacks, etc).
All of the above can be found in C-Kermit, which is therefore bigger and
more complicated, with more platform-specific code and #ifdef spaghetti.
C-Kermit requires constant updates and patches to keep pace with changes in
the underlying platforms, networking methods, and demands from its users for
more features.
The goal for G-Kermit, on the other hand, is simplicity and stability, so we
don't need thousands of #ifdefs like we have in C-Kermit, and we don't need
to tweak the code every time a new release of each Unix variety comes out.
G-Kermit is meant to be PORTABLE and LONG-LASTING so the stress is on a
MINIMUM of platform dependencies.
If you make changes, please try to avoid adding anything platform-dependent
or in any other way destabilizing. Bear in mind that the result of your
changes should still build and run successfully on at least all the
platforms where it was built originally. In any case, you are encouraged to
send any changes back to the Kermit Project to be considered for addition to
the master G-Kermit distribution.
15. FURTHER INFORMATION
The Kermit protocol is specified in "Kermit, A File Transfer Protocol" by
Frank da Cruz, Digital Press (1987). A correctness proof of the Kermit
protocol appears in "Specification and Validation Methods", edited by Egon
Boerger, Oxford University Press (1995). "Using C-Kermit" by Frank da Cruz
and Christine M. Gianone, Digital Press (1997, or later edition) explains
many of the terms and techniques referenced in this document in case you are
not familiar with them, and also includes tutorials on data communications,
extensive troubleshooting and performance tips, etc. Various other books on
Kermit are available from Digital Press. Online resources include:
http://www.columbia.edu/kermit/ The Kermit Project website
comp.protocols.kermit.misc The unmoderated Kermit newsgroup
kermit-support@columbia.edu Technical support
(End of G-Kermit README)