ckcplm.txt

KERMIT工具 这在办公室下载不了,很多人都没有载不到.

                         C-Kermit Program Logic Manual

     Frank da Cruz
     [1]The Kermit Project
     [2]Columbia University

   As of: C-Kermit 8.0.211, 10 April 2004
   This page last updated: Sat Apr 10 16:45:30 2004 (New York USA Time)

     IF YOU ARE READING A PLAIN-TEXT version of this document, note that
     this file is a plain-text dump of a Web page. You can visit the
     original (and possibly more up-to-date) Web page here:

  [3]http://www.columbia.edu/kermit/ckcplm.html

   [ [4]C-Kermit Home ] [ [5]Kermit Home ]
    ________________________________________________________________________

  CONTENTS

  1. [6]INTRODUCTION
  2. [7]FILES
  3. [8]SOURCE CODE PORTABILITY AND STYLE
  4. [9]MODULES
     4.A. [10]Group A: Library Routines
     4.B. [11]Group B: Kermit File Transfer
     4.C. [12]Group C: Character-Set Conversion
     4.D. [13]Group D: User Interface
     4.E. [14]Group E: Platform-Dependent I/O
     4.F. [15]Group F: Network Support
     4.G. [16]Group G: Formatted Screen Support
     4.H. [17]Group H: Pseudoterminal Support
     4.I. [18]Group I: Security
  I. [19]APPENDIX I: FILE PERMISSIONS
    ________________________________________________________________________

  1. 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 describes the relationship among the modules and functions
   of C-Kermit 5A and later, and other programming considerations.
   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, as shown in the [20]Contents.

   C-Kermit has seen constant development since 1985. Throughout its
   history, there has been a neverending tug-of-war among:

    a. Functionality: adding new features, fixing bugs, improving
       performance.
    b. Adding support for new platforms.
    c. "Buzzword 1.0 compliance".

   The latter category is the most frustrating, since it generally
   involves massive changes just to keep the software doing what it did
   before in some new setting: e.g. the K&R-to-ANSIC conversion (which
   had to be done, of course, without breaking K&R); Y2K (not a big deal
   in our case); the many and varied UNIX and other API "standards";
   IPv6.

   [ [21]Contents ] [ [22]C-Kermit ] [ [23]Kermit Home ]
    ________________________________________________________________________

  2. FILES

   C-Kermit source files begin with the two letters "ck", for example
   ckutio.c. Filenames are kept short (6.3) for maximum portability and
   (obviously I hope) do not contain spaces or more than one period. The
   third character in the name denotes something about the function group
   and the expected level of portability:

     a     General descriptive material and documentation (text)
     b     BOO file encoders and decoders (obsolete)
     c     All platforms with C compilers (*)
     d     Data General AOS/VS
     e     Reserved for "ckermit" files, like ckermit.ini, ckermit2.txt
     f     (reserved)
     g     (reserved)
     h     (reserved)
     i     Commodore Amiga (Intuition)
     j     (unused)
     k     (unused)
     l     Stratus VOS
     m     Macintosh with Mac OS 1-9
     n     Microsoft Windows NT/2000/XP
     o     OS/2 and/or Microsoft Windows 9x/ME/NT/2000/XP
     p     Plan 9 from Bell Labs
     q     (reserved)
     r     DEC PDP-11 with RSTS/E (never used, open for reassigment)
     s     Atari ST GEMDOS (last supported in version 5A(189))
     t     DEC PDP-11 with RT-11 (never used, open for reassigment)
     u     Unix-based operating systems (*)
     v     VMS and OpenVMS
     w     Wart (Lex-like preprocessor, platform independent)
     x     (reserved)
     y     (reserved)
     z     (reserved)
     0-3   (reserved)
     4     IBM AS/400
     5-8   (reserved)
     9     Microware OS-9
     _     Encryption modules

   (*) In fact there is little distinction between the ckc*.* and cku*.*
   categories. It would make more sense for all cku*.* modules to be
   ckc*.* ones, except ckufio.c, ckutio.c, ckucon.c, ckucns.c, and
   ckupty.c, which truly are specific to Unix. The rest (ckuus*.c,
   ckucmd.c, etc) are quite portable.

   One hint before proceeding: functions are scattered all over the
   ckc*.c and cku*.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 in
   what source file a given function is defined 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 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 the opening bracket is above the visible screen, and it also
   makes it easy to find the end of a function (search for '}' on the
   left margin).

   Of course EMACS tags work nicely with this format too:

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

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

   Also:

     * 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 (obviously this is not a portability issue, just
       style).

   [ [25]Contents ] [ [26]C-Kermit ] [ [27]Kermit Home ]
    ________________________________________________________________________

  3. SOURCE CODE PORTABILITY AND STYLE

   C-Kermit was designed in 1985 as a platform-independent replacement
   for the earlier Unix Kermit. c-Kermit's design was expected to promote
   portability, and judging from the number of platforms to which it has
   been adapted since then, the model is effective, if not ideal
   (obviously if we had it all to do over, we'd change a few things). To
   answer the oft-repeated question: "Why are there so many #ifdefs?",
   it's because:

     * Many of them are related to feature selection and program size,
       and so need to be there anyway.
     * Those that treat compiler, library, platform, header-file, and
       similar differences have built up over time as hundreds of people
       all over the world adapted C-Kermit to their particular
       environments and sent back their changes. There might be more
       politically-correct ways to achieve portability, but this one is
       natural and proven. The basic idea is to introduce changes that
       can be selected by defining a symbol, which, if not defined,
       leaves the program exactly as it was before the changes.
     * Although it might be possible to "clean up" the "#ifdef mess",
       nobody has access to all the hundreds of platforms served by the
       #ifdefs to check the results.

   And to answer the second-most-oft-repeated question: "Why don't you
   just use GNU autoconfig / automake / autowhatever instead of
   hard-coding all those #ifdefs?" Answers:

     * The GNU tools are not available on all the platforms where
       C-Kermit must be built and I wouldn't necessarily trust them if
       they were.
     * Each platform is a moving target, so the tools themselves would
       need to updated before Kermit could be updated.
     * It would only add another layer of complexity to an already
       complex process.
     * Conversion at this point would not be practical unless there was a
       way to test the results on all the hundreds of platforms where
       C-Kermit is supposed to build.

   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. The same holds true
   for many of the "system dependent" modules too; particularly the Unix
   ones, since they must be buildable by a wide variety of compilers and
   linkers, new and old.

   This list does not purport to be comprehensive, and although some
   items on it might seem far-fetched, they would not be listed unless I
   had encountered them somewhere, some time. I wish I had kept better
   records so I could cite specific platforms and compilers.

     * 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 old linkers (actually, this goes back to
       TOPS-10 and -20 and other old DEC OS's where C-Kermit never ran
       anyway; a more realistic maximum is probably somewhere between 8
       and 16). We know for certain that VAX C has a 31-character max
       because it complains -- others might not complain, but just
       silently truncate, thus folding two or more routines/variables
       into one.
     * Keep preprocessor symbols unique within 8 characters; that's the
       max for some preprocessors (sorry, I can't give a specific
       example, but in 1988 or thereabouts, I had to change character-set
       symbols like TC_LATIN1 and TC_LATIN2 to TC_1LATIN and TC_2LATIN
       because the digits were being truncated and ignored on a platform
       where I actually had to build C-Kermit 5A; unfortunately I didn't
       note which platform -- maybe some early Ultrix version?)
     * Don't create preprocessor symbols, or variable or function names,
       that start with underscore (_). These are usually reserved for
       internal use by the compiler and header files.
     * Don't put #include directives inside functions or { blocks }.
     * Don't use the #if or #elif preprocessor constructions, only use
       #ifdef, #ifndef, #define, #undef, and #endif.
     * 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 (I can't
       remember why this one is here, but probably needn't be; we do this
       all the time).
     * 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.
     * Avoid typedefs; they might be portable but they are very confusing
       and there's no way to test for their presence or absence at
       compile time. Use preprocessor symbols instead if possible; at
       least you can test their definitions.
     * Unsigned long is not portable; use a preprocessor symbol (Kermit
       uses ULONG for this).
     * Long long is not portable. If you really need it, be creative.
     * Similarly 1234LL is not portable, nor almost any other constant
       modifier other than L.
     * Unsigned char is not portable, use CHAR (a preprocessor symbol
       defined in the Kermit header files) and always take precautions
       against character signage (more about this [28]below).
     * Don't use initializers with automatic arrays or structs: it's not
       portable.
     * Don't use big automatic arrays or structs in functions that might
       be called recursively; some platforms have fixed-size stacks (e.g.
       Windows 9x: 256K) and recursive functions crash with stack
       overflow. Even when there is not a compiler limitation, this
       causes memory to be consumed without bound, and can end up filling
       swap space.
     * Don't assume that struct assignment performs a copy, or that it
       even exists.
     * Don't use sizeof to get the size of an array; someone might come
       along later and and change it from static to malloc'd. Always use
       a symbol to refer to the array's size.
     * Don't put prototypes for static functions into header files that
       are used by modules that don't contain that function; the link
       step can fail with unresolved references (e.g. on AOS/VS).
     * Avoid the construction *++p (the order of evaluation varies; it