ckcplm.txt

C-Kermit源码。是使用串口/Modem和网络通讯的程序

CKCPLM.TXT                                                            Feb 2000

			C-KERMIT PROGRAM LOGIC MANUAL

As of C-Kermit version:  7.0.197
This file last updated:  Tue Feb  8 16:30:55 2000
Author: Frank da Cruz, Columbia University
E-Mail: [e-mail]

  Copyright (C) 1985, 2000,
    Trustees of Columbia University in the City of New York.
    All rights reserved.  See the C-Kermit COPYING.TXT file or the
    copyright text in the ckcmai.c module for disclaimer and permissions.


INTRODUCTION

The Kermit Protocol is specified in the book "Kermit, A File Transfer
Protocol" by Frank da Cruz, Digital Press / Butterworth Heinemann, Newton, MA,
USA (1987), 379 pages, ISBN 0-932376-88-6.  It is assumed the reader is
familiar with the Kermit protocol specification.

This file attempts to describe the relationship among the modules and
functions of C-Kermit 5A and later.  Before reading this file, please read the
file CKAAAA.TXT for an overview of C-Kermit file naming conventions.

C-Kermit is designed to be portable to any kind of computer that has a C
compiler.  The source code is broken into many files that are grouped
according to their function.  There are several major groups: 1 (the protocol
kernel), 2 (the user interface), 3 (system-dependent primitives), 4 (network
support), and 5 (formatted screen support).


CONTENTS:

  FILES
  SOURCE CODE PORTABILITY GUIDE

  GROUP 0    Library functions
  GROUP 1    System-independent file transfer protocol
  GROUP 1.5  Character set translation
  GROUP 2    User Interface
  GROUP 3    File & communications i/o and other system dependencies
  GROUP 4    Network support
  GROUP 5    Formatted screen support

  APPENDIX I File Permissions

WARNING: C-Kermit 6.1 is probably the last version preserving this
organization and naming.  The next major release after 6.1 will apply some
lessons we have learned about modularity and separation, and allow easier
integration of the code with other applications and/or user interfaces.


FILES

C-Kermit source files begin with the two letters CK (lowercase on UNIX
systems, uppercase on most others).  The third character denotes something
about the function group and the expected level of portability.  See the file
CKAAAA.TXT for details of file naming conventions and organization.

One hint before proceeding: functions are scattered all over the ckc*.c
and ckuu*.c modules, where function size has begun to take precedence over
the desirability of grouping related functions together, the aim being to
keep any particular module from growing disproportionately large.  The easiest
way (in UNIX) to find out what source file a given function is defined in is
like this (where the desired function is foo()...):

  grep ^foo ck*.c

This works because the coding convention has been to make function names
always start on the left margin with their contents indented, for example:

static char *
foo(x,y) int x, y; {
    ...
}

Also please note the style for bracket placement.  This allows
bracket-matching text editors (such as EMACS) to help you make sure you know
which opening bracket a closing bracket matches, particularly when it is no
longer visible on the screen, and it also makes it easy to find the end of a
function (search for '}' on the right margin).

Of course EMACS tags work nicely with this format too:

  $ cd <kermit-source-directory>
  $ etags ck[cu]*.[ch]
  $ emacs
  Esc-X Visit-Tags-Table<CR><CR>

(but remember that the source file for ckcpro.c is ckcpro.w!)


SOURCE CODE PORTABILITY GUIDE

When writing code for the system-indendent C-Kermit modules, please stick to
the following coding conventions to ensure portability to the widest possible
variety of C preprocessors, compilers, and linkers, as well as certain network
and/or email transports:

. Tabs should be set every 8 spaces, as on a VT100.
. All lines must no more than 79 characters wide after tab expansion.
. Note the distinction between physical tabs (ASCII 9) and the indentation
  conventions, which are: 4 for block contents, 2 for most other stuff.
. Try to keep variable and function names unique within 6 characters,
  especially if they are used across modules, since 6 is the maximum for
  some linkers.  (Actually, I think the last system that had this limitation
  was turned off in the 1980s -- remember SIXBIT? -- no now maybe it's 8?)
. Keep preprocessor symbols unique within 8 characters.
. Don't put #include directives inside functions or { blocks }.
. Don't use the #if preprocessor construction, only use #ifdef, #ifndef, #undef
. Put tokens after #endif in comment brackets, e.g. #endif /* FOO */.
. Don't indent preprocessor statements - # must always be first char on line.
. Don't put whitespace after # in preprocessor statements.
. Don't use #pragma, even within #ifdefs - it makes some preprocessors give up.
. Same goes for #module, #if, etc - #ifdefs do NOT protect them.
. Don't use logical operators in preprocessor constructions.
. Avoid #ifdefs inside argument list to function calls.
. Always cast strlen() in expressions to int: "if ((int)strlen(foo) < x)...".
. Any variable whose value might exceed 16383 should be declared as long,
  or if that is not possible, then as unsigned.
. Unsigned long is not portable.
. Don't use initializers with automatic arrays or structs.
. Don't assume that struct assignment performs a copy.
. Don't put prototypes for static functions into header files that are used
  by modules that don't contain that function.
. Avoid the construction *++p -- the order of evaluation varies.
. Reportedly, some compilers even mess up with *(++p).
. Don't use triple assignments, like a = b = c = 0; (or quadruple, etc).
  Some compilers generate bad code for these, or crash, etc.
. Structure members may not have the same names as other identifiers.
. Avoid huge switch() statements with many cases.
. Don't have a switch() statement with no cases (e.g. because of #ifdefs).
. Don't put anything between "switch() {" and case: --   switch blocks are not
  like other blocks.
. Don't make character-string constants longer than about 250.
. Don't write into character-string constants even when you know you are not
  writing past the end because the compiler or linker might have put them into
  read-only and/or shared memory, and/or coalesced multiple equal constants
  so if you change one you change them all.
. Don't depend on '\r' being carriage return.
. Don't depend on '\n' being linefeed or for that matter any SINGLE character.
. Don't depend on '\r' and '\n' being different (e.g. in switch() statements).
. In other words, don't use \n or \r to stand for specific characters;
  use \012 and \015 instead.
. Don't code for "buzzword 1.0 compliance", unless "buzzword" is K&R and
  "1.0" is the first edition.
. Don't use or depend on anything_t (size_t, time_t, etc).
. Don't use or depend on internationalization ("i18n") features, wchar_t,
  locales, etc, in portable code; they are not portable.  Anyway, locales are
  not the right model for Kermit's multi-character-set support.
. Don't make any assumption about signal handler type.  It can be void, int,
  long, or anything else.  Always declare signal handlers as SIGTYP (see
  definition in ckcdeb.h and augment it if necessary) and always use
  SIGRETURN at exit points from signal handlers.
. Signals should always be re-armed to be used again (this barely scratches
  the surface -- the difference between BSD/V7 and System V and POSIX signal
  handling are numerous, and some platforms do not even support signals,
  alarms, or longjmps correctly or at all -- avoid all of this stuff if you
  can).
. Don't call malloc() & friends from a signal handler.
. memset(), memmove(), and memcpy() are not portable, don't use them without
  protecting them in ifdefs.  bzero() too, except we're guaranteed to have
  bzero() when using the sockets library.  See examples in the source.
. Don't assume that strncpy() stops on the first null byte -- some versions
  always copy the number of bytes given in arg 3.  Probably also true of
  other strnblah() functions.
. DID YOU KNOW.. that some versions of inet_blah() routines return IP addresses
  in network byte order, while others return them local machine byte order?
  So passing them to htons(), etc, is not always the right thing to do.
. Don't use ANSI-format function declarations without #ifdef CK_ANSIC,
  and always provide an #else for the non-ANSI case.
. Don't depend on any other ANSI preprocessor features like "pasting" -- they
  are often missing or nonoperational.
. Don't assume any C++ syntax or semantics.
. Don't declare a string as "char foo[]" in one module and "extern char * foo"
  in another, or vice-versa.
. With compiler makers falling all over themselves trying to outdo each other
  in ANSI strictness, it has become increasingly necessary to cast EVERYTHING.
. a[x], where x is an unsigned char, can produce a wild memory reference if x,
  when promoted to an int, becomes negative.  Cast it to (unsigned), even
  though it ALREADY IS unsigned.
. Be careful how you declare functions that have char or long arguments;
  for ANSI compilers you MUST use ANSI declarations to avoid promotion
  problems, but you can't use ANSI declarations with non-ANSI compilers.
  Thus declarations of such functions must be hideously entwined in #ifdefs.
  Example of the latter:

  int			       /*  Put character in server command buffer  */
  #ifdef CK_ANSIC
  putsrv(char c)
  #else
  putsrv(c) char c;
  #endif /* CK_ANSIC */
  /* putsrv */ {
      *srvptr++ = c;
      *srvptr = '\0';		/* Make sure buffer is null-terminated */
      return(0);
  }

. Be careful how you return characters from functions that return int values --
  "getc-like functions" -- in the ANSI world.  Unless you explicitly cast the
  return value to (unsigned), it is likely to be "promoted" to an int and have
  its sign extended.

. Here's a good one.  At least one compiler (the one on DEC OSF/1 1.3) treats
  /* and */ within string constants as comment begin and end.  No amount of
  #ifdefs will get around this one.  You simply can't put an unbalanced
  /* or */ in a string constant, e.g. "/usr/local/doc/*.*".

. Avoid putting multiple macro references on a single line, e.g.:

    putchar(BS); putchar(SP); putchar(BS)

  This will overflow the CPP output buffer of more than a few C preprocessors.

(many, many more...  This section needs massive filling in.)

C-Kermit needs constant adjustment to new OS and compiler releases.  Every
new release shuffles header files or their contents, or prototypes, or data
types, or levels of ANSI strictness, etc.  Every time you make an adjustment
to remove a new compilation error, BE VERY CAREFUL to #ifdef it on a symbol
unique to the new configuration so that the previous configuration (and all
other configurations on all other platforms) remain as before.

Assume nothing.  Don't assume header files are where they are supposed to be,
that they contain what you think they contain, that they define specific
symbols to have certain values -- or define them at all!  Don't assume system
header files protect themselves against multiple inclusion.  Don't assume that
particular system or library calls are available, or that the arguments are
what you think they are -- order, data type, passed by reference vs value,
etc.  Be very conservative when attempting to write portable code.  Avoid all
advanced features.  Stick with K&R First Edition, and even then you're on
shaky ground.

If you see something that does not make sense, don't assume it's a mistake --
it is probably there for a reason, and changing it or removing is very likely
to cause compilation, linking, or runtime failures sometime, somewhere.  Some
huge percentage of the code, especially in the system-dependent modules, is
workarounds for compiler, linker, or API bugs.

BUT... feel free to violate any or all of these rules in system-specific
modules for environments in which the rules are certain not to apply.  For
example, in VMS-specific code, it is OK to use #if.  But even then, allow for
different compilers or compiler versions used in that same environment,
e.g. VAX C vs DEC C vs GNU C.

THE "CHAR" VS "UNSIGNED CHAR" DILEMMA

This is one of the most aggravating and vexing things about C.  By default,
chars (and char *'s) are SIGNED.  But in the modern era, we need to process
characters that can have 8-bit values, such as ISO Latin-1, IBM CP 850, and
other 8-bit (or 16-bit, etc) character sets, and so this data MUST be treated
as unsigned.  BUT...  Some C compilers (such as those based on the Bell UNIX
V7 compiler) do not support "unsigned char" as a data type.  Therefore we have
the macro or typedef CHAR, which we use when we need chars to be unsigned, but
which, unfortunately, resolves itself to "char" on those compilers that don't
support "unsigned char".  AND SO...  We have to do a lot of fiddling at
runtime to avoid sign extension and so forth.  BUT THAT'S NOT ALL...  Now some
modern compilers (e.g. IBM, DEC, Microsoft) have switches that say "make all
chars be unsigned" (e.g. GNU cc "-funsigned-char").  We use these switches
when they are available.  Other compilers don't have these, and at the same
time, are becoming increasingly strict about type mismatches, and spew out
torrents of warnings when we use a CHAR where a char is expected, or vice
versa.  We fix these one by one using casts, and the code becomes increasingly
ugly.  But there remains a serious problem, namely that certain library and
kernel functions have arguments that are declared as signed chars (or pointers
to them), whereas our character data is unsigned.  Fine, we can can use casts
here too -- but who knows what happens inside these routines.

MODES OF OPERATION

When C-Kermit is on the far end of a connection, it is said to be in
remote mode.  When C-Kermit has made a connection to another computer, it
is in local mode.  (If C-Kermit is "in the middle" of a multihop connection,
it is still in local mode.)

On another axis, C-Kermit has three major modes of operation:

Command Mode
  Reading and writing from the job's controlling terminal or "console".
  In this mode, all i/o is handled by the Group 3 conxxx() (console i/o)
  routines.

Protocol Mode
  Reading and writing from the communicatons device.  In this mode, all i/o is
  handled by the Group 3 ttxxx() (terminal i/o) routines.

Connect Mode
  Reading from the keyboard with conxxx() routines and writing to the
  communications device with ttxxx() routines AND vice-versa.

When in local mode, the console and communications device are distinct.
During file transfer, Kermit may put up a file-transfer display on the console
and sample the console for interruption signals.

When in remote mode, the console and communications device are the same, and
therefore there can be no file-transfer display on the console or
interruptions from it (except for "in-band" interruptions such as ^C^C^C).