readme

使用Kermit协议传输文件的程序

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
  [e-mail]        Technical support

Also visit:

  http://www.columbia.edu/kermit/gkermit.html

for a more up-to-date version of this file, complete with download links.

(End of G-Kermit README)