Return to ckuker.mss CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / kermit

Annotation of 43BSD/contrib/kermit/ckuker.mss, revision 1.1

1.1     ! root        1: @comment[      -*-Text-*-      ]
        !             2: @Part(CKUNIX,root="KER:KUSER")
        !             3: @string(-ckversion="@q<4C(057)>")
        !             4: @define(exx=example,above 2,below 1)
        !             5: @Chapter<UNIX KERMIT>
        !             6: 
        !             7: @Begin<Description,Leftmargin +12,Indent -12,spread 0>
        !             8: @i(Program:)@\Frank da Cruz, Bill Catchings, Jeff Damens, Columbia
        !             9: University; Herm Fischer, Encino CA; contributions by
        !            10: many others.
        !            11: 
        !            12: @i(Language:)@\C
        !            13: 
        !            14: @i(Documentation:)@\Frank da Cruz, Herm Fischer
        !            15: 
        !            16: @i(Version:)@\@value(-ckversion)
        !            17: 
        !            18: @i(Date: )@\July 26, 1985
        !            19: @end<Description>
        !            20: 
        !            21: C-Kermit is a completely new implementation of Kermit, written modularly and
        !            22: transportably in C.  The protocol state transition table is written in
        !            23: @i'wart', a (non-@|proprietary) lex-@|like preprocessor for C.
        !            24: System-@|dependent primitive functions are isolated into separately compiled
        !            25: modules so that the program should be easily portable among Unix systems and
        !            26: also to non-@|Unix systems that have C compilers.  This document applies to
        !            27: Unix implementations of C-Kermit, and in most ways also to the VMS
        !            28: implementation.
        !            29: 
        !            30: @subheading<Unix Kermit Capabilities At A Glance:>
        !            31: @begin<format,leftmargin +2,above 1,below 1>
        !            32: @tabclear()@tabset(3.5inches,4.0inches)
        !            33: Local operation:@\Yes
        !            34: Remote operation:@\Yes
        !            35: Login scripts:@\Yes
        !            36: Transfer text files:@\Yes
        !            37: Transfer binary files:@\Yes
        !            38: Wildcard send:@\Yes
        !            39: File transfer interruption:@\Yes
        !            40: Filename collision avoidance:@\Yes
        !            41: Can time out:@\Yes
        !            42: 8th-bit prefixing:@\Yes
        !            43: Repeat count prefixing:@\Yes
        !            44: Alternate block checks:@\Yes
        !            45: Terminal emulation:@\Yes
        !            46: Communication settings:@\Yes
        !            47: Transmit BREAK:@\Yes
        !            48: Support for dialout modems:@\Yes
        !            49: IBM mainframe communication:@\Yes
        !            50: Transaction logging:@\Yes
        !            51: Session logging:@\Yes
        !            52: Debug logging:@\Yes
        !            53: Packet logging:@\Yes
        !            54: Act as server:@\Yes
        !            55: Talk to server:@\Yes
        !            56: Advanced server functions:@\Yes
        !            57: Local file management:@\Yes
        !            58: Command/Init files:@\Yes
        !            59: UUCP and multiuser line locking:@\Yes
        !            60: File attributes packets:@\No
        !            61: Command macros:@\No
        !            62: Raw file transmit:@\No
        !            63: @end<format>
        !            64: 
        !            65: @index(C-Kermit)@index(Unix Kermit)
        !            66: C-Kermit provides traditional Unix command line operation as well as
        !            67: interactive command prompting and execution.  The command line options
        !            68: provide access to a minimal subset of C-Kermit's capabilities; the
        !            69: interactive command set is far richer.
        !            70: 
        !            71: On systems with dialout modems, C-Kermit can use its command file and login
        !            72: script facilities to replicate the file transfer functionality of
        !            73: UUCP among heterogeneous operating systems, including the use of scheduled
        !            74: (e.g. late night) unattended operation.
        !            75: 
        !            76: @section(The Unix File System)
        !            77: 
        !            78: Consult your Unix manual for details about the file system under your version
        !            79: of Unix.  For the purposes of Kermit, several things are worth briefly noting.
        !            80: Unix files generally have lowercase names, possibly containing one or more dots
        !            81: or other special characters.  Unix directories are tree-@|structured.
        !            82: Directory levels are separated by slash (@qq[/]) characters.  For example,
        !            83: @example(/usr/foo/bar)
        !            84: denotes the file @q(bar) in the directory @q(/usr/foo).  Wildcard or
        !            85: "meta" characters allow groups of files to be specified.  @qq(*)
        !            86: matches any string; @qq(?) matches any single character.
        !            87: 
        !            88: When C-Kermit is invoked with file arguments specified on the Unix command
        !            89: line, the Unix shell (Bourne Shell, C-Shell, etc) expands the meta characters 
        !            90: itself, and in this case a wider variety is available.  For example,
        !            91: @example(kermit -s ~/ck[uvm]*.{upd,bwr}])
        !            92: is expanded by the Berkeley C-Shell into a list of all the files in the
        !            93: user's home directory (@q[~/]) that start with the characters "@q(ck)",
        !            94: followed by a single character @qq(u), @qq(v), or @qq(m), followed by zero
        !            95: or more characters, followed by a dot, followed by one of the strings
        !            96: @qq(upd) or @qq(bwr).  Internally, the C-Kermit program itself expands only
        !            97: the @qq(*) and @qq(?) meta characters.
        !            98: 
        !            99: Unix files are linear streams of 8-bit bytes.  Text files consist of 7-bit
        !           100: ASCII characters, with the high-@|order bit off (0), and lines separated by the
        !           101: Unix newline character, which is linefeed (LF, ASCII 10).  This distinguishes
        !           102: Unix text files from those on most other ASCII systems, in which lines are
        !           103: separated by a carriage-@|return linefeed sequence (CRLF, ASCII 13 followed by
        !           104: ASCII 10).  Binary files are likely to contain data in the high bits of the
        !           105: file bytes, and have no particular line or record structure.
        !           106: 
        !           107: When transferring files, C-Kermit will convert between upper and lower
        !           108: case filenames and between LF and CRLF line terminators automatically,
        !           109: unless told to do otherwise.  When binary files must be transferred, the
        !           110: program must be instructed not to perform LF/CRLF conversion (@q[-i] on the
        !           111: command line or "set file type binary" interactively; see below).
        !           112: 
        !           113: @section(File Transfer)
        !           114: 
        !           115: If C-Kermit is in local mode, the screen (stdout) is continously updated to
        !           116: show the progress of the file transer.  A dot is printed for every four data
        !           117: packets, other packets are shown by type:
        !           118: @begin(description,leftmargin +6, indent -2, spread 0)
        !           119: I@\Exchange Parameter Information
        !           120: 
        !           121: R@\Receive Initiate
        !           122: 
        !           123: S@\Send Initiate
        !           124: 
        !           125: F@\File Header
        !           126: 
        !           127: G@\Generic Server Command
        !           128: 
        !           129: C@\Remote Host Command
        !           130: 
        !           131: N@\Negative Acknowledgement (NAK)
        !           132: 
        !           133: E@\Fatal Error
        !           134: 
        !           135: T@\Indicates a timeout occurred
        !           136: 
        !           137: Q@\Indicates a damaged, undesired, or illegal packet was received
        !           138: 
        !           139: @q<%>@\Indicates a packet was retransmitted
        !           140: @end(description)
        !           141: You may type certain "interrupt" commands during file transfer:
        !           142: @begin(description,leftmargin +16,indent -12,spread 0)
        !           143: Control-F:@\Interrupt the current File, and go on to the next (if any).
        !           144: 
        !           145: Control-B:@\Interrupt the entire Batch of files, terminate the transaction.
        !           146: 
        !           147: Control-R:@\Resend the current packet
        !           148: 
        !           149: Control-A:@\Display a status report for the current transaction.
        !           150: @end(description)
        !           151: These interrupt characters differ from the ones used in other Kermit
        !           152: implementations to avoid conflict with commonly used Unix shell interrupt
        !           153: characters.  With Version 7, System III, and System V implementations of
        !           154: Unix, interrupt commands must be preceeded by the 'connect' escape character
        !           155: (e.g. normally-@q[\]).
        !           156: 
        !           157: @begin(quotation)
        !           158: @i(CAUTION:)@index(Warning)@index<File Warning>
        !           159:  If Control-F or Control-B is used to cancel an incoming file,
        !           160: and a file of the same name previously existed, @i(and) the "file warning"
        !           161: feature is not enabled, then the previous copy of the file will disappear.
        !           162: @end(quotation)
        !           163: 
        !           164: @i(EMERGENCY EXIT:)@index<Emergency Exit>
        !           165: When running Unix Kermit in remote mode, if you have started a protocol
        !           166: operation (sending or receiving a file, server command wait, etc), you will
        !           167: not be able to regain control of the terminal until the protocol operation
        !           168: has run its course (completed or timed out).  In particular, you cannot stop
        !           169: the protocol by typing the normal Unix interrupt characters, since the
        !           170: terminal has been put in "raw mode".  If you need to regain control quickly
        !           171: -- for instance, because the protocol is stuck -- you can type the following
        !           172: sequence of four characters directly to the Unix Kermit program ("connect"
        !           173: first if necessary):
        !           174: @display<Control-A Control-C Control-C Carriage-Return>
        !           175: This will cause the program to exit and restore the terminal to normal.
        !           176: 
        !           177: @section(Command Line Operation)
        !           178: 
        !           179: The C-Kermit command line syntax has been changed from that of earlier
        !           180: releases of Unix Kermit to conform to the @ux(Proposed Syntax Standards for
        !           181: Unix System Commands) put forth by Kathy Hemenway and Helene Armitage of
        !           182: AT&T Bell Laboratories in @i(Unix/World), Vol.1, No.3, 1984.  The rules that
        !           183: apply are:
        !           184: 
        !           185: @begin(itemize,spread 0)
        !           186: Command names must be between 2 and 9 characters ("kermit" is 6).
        !           187: 
        !           188: Command names must include lower case letters and digits only.
        !           189: 
        !           190: An option name is a single character.
        !           191: 
        !           192: Options are delimited by '@q(-)'.
        !           193: 
        !           194: Options with no arguments may be grouped (bundled) behind one delimiter.
        !           195: 
        !           196: Option-arguments cannot be optional.
        !           197: 
        !           198: Arguments immediately follow options, separated by whitespace.
        !           199: 
        !           200: The order of options does not matter.
        !           201: 
        !           202: '@q(-)' preceded and followed by whitespace means standard input.
        !           203: @end(itemize)
        !           204: A group of bundled options may end with an option that has an argument.
        !           205: 
        !           206: The following notation is used in command descriptions:
        !           207: @begin(description,leftmargin +8,indent -8)
        !           208: @i(fn)@\A Unix file specification, possibly containing the "wildcard"
        !           209: characters `@q[*]' or `@q[?]' (`@q[*]' matches all character strings, `@q[?]'
        !           210: matches any single character).
        !           211: 
        !           212: @i(fn1)@\A Unix file specification which may not contain `@q[*]' or `@q[?]'.
        !           213: 
        !           214: @i(rfn)@\A remote file specification in the remote system's own syntax, which
        !           215: may denote a single file or a group of files.
        !           216: 
        !           217: @i(rfn1)@\A remote file specification which should denote only a single file.
        !           218: 
        !           219: @i(n)@\A decimal number between 0 and 94.
        !           220: 
        !           221: @i(c)@\A decimal number between 0 and 127 representing the value of an
        !           222: ASCII character.
        !           223: 
        !           224: @i(cc)@\A decimal number between 0 and 31, or else exactly 127,
        !           225: representing the value of an ASCII control character.
        !           226: 
        !           227: @q([ ])@\Any field in square braces is optional.
        !           228: 
        !           229: @q({x,y,z})@\Alternatives are listed in curly braces.
        !           230: @end(description)
        !           231: 
        !           232: C-Kermit command line options may specify either actions or settings.  If
        !           233: C-Kermit is invoked with a command line that specifies no actions, then it
        !           234: will issue a prompt and begin interactive dialog.
        !           235: Action options specify either protocol transactions or terminal connection.
        !           236: 
        !           237: @begin<description,leftmargin +8,indent -8>
        !           238: @q(-s )@i(fn)@\Send the specified file or files.  If @i(fn) contains
        !           239: wildcard (meta) characters, the Unix shell expands it into a list.  If @i(fn)
        !           240: is '@q[-]' then kermit sends from standard input, which must
        !           241: come from a file:
        !           242: @example(kermit -s - < foo.bar)
        !           243: or a parallel process:
        !           244: @example(ls -l | kermit -s -)
        !           245: You cannot use this mechanism to send
        !           246: terminal typein.  If you want to send a file whose name is @qq(-)
        !           247: you can precede it with a path name, as in
        !           248: @example(kermit -s ./-)
        !           249: 
        !           250: @q(-r)@\Receive a file or files.  Wait passively for files to arrive.
        !           251: 
        !           252: @q(-k)@\Receive (passively) a file or files, sending them to standard
        !           253: output.  This option can be used in several ways:
        !           254: @begin(description,leftmargin +4,indent -4)
        !           255: @q(kermit -k)@\Displays the incoming files on your screen; to be used only
        !           256: in "local mode" (see below).
        !           257: 
        !           258: @q(kermit -k > )@i(fn1)@\Sends the incoming file or files to the named file,
        !           259: @i(fn1).  If more than one file arrives, all are concatenated together
        !           260: into the single file @i(fn1).
        !           261: 
        !           262: @q(kermit -k | command)@\Pipes the incoming data (single or multiple
        !           263: files) to the indicated command, as in
        !           264: @example'kermit -k | sort > sorted.stuff'
        !           265: @end(description)
        !           266: 
        !           267: @q(-a )@i(fn1)@\If you have specified a file transfer option, you may specify
        !           268: an alternate name for a single file with the @q(-a) option.  For example,
        !           269: @example'kermit -s foo -a bar'
        !           270: sends the file @q(foo) telling the receiver that its name is @q(bar).
        !           271: If more than one file arrives or is sent, only the first file is
        !           272: affected by the @q(-a) option:
        !           273: @example'kermit -ra baz'
        !           274: stores the first incoming file under the name @q(baz).
        !           275: 
        !           276: @q(-x)@\Begin server operation.  May be used in either local or remote mode.
        !           277: @end(description)
        !           278: 
        !           279: Before proceeding, a few words about remote and local operation are
        !           280: necessary.  C-Kermit is "local" if it is running on PC or workstation that
        !           281: you are using directly, or if it is running on a multiuser system and
        !           282: transferring files over an external communication line -- not your job's
        !           283: controlling terminal or console.  C-Kermit is remote if it is running on a
        !           284: multiuser system and transferring files over its own controlling terminal's
        !           285: communication line, connected to your PC or workstation.
        !           286: 
        !           287: If you are running C-Kermit on a PC, it is in local mode by default,
        !           288: with the "back port" designated for file transfer and terminal connection.
        !           289: If you are running C-Kermit on a multiuser (timesharing) system, it is
        !           290: in remote mode unless you explicitly point it at an external line for
        !           291: file transfer or terminal connection.  The following command sets
        !           292: C-Kermit's "mode":
        !           293: 
        !           294: @begin(description,leftmargin +8,indent -8)
        !           295: @q(-l )@i(dev)@\Line  -- Specify a terminal line to use for file
        !           296: transfer and terminal connection, as in
        !           297: @example'kermit -l /dev/ttyi5'
        !           298: @end(description)
        !           299: 
        !           300: When an external line is being used, you might also need some additional
        !           301: options for successful communication with the remote system:
        !           302: 
        !           303: @begin(description,leftmargin +8,indent -8)
        !           304: @q(-b )@i(n)@\Baud  -- Specify the baud rate for the line given in the
        !           305: @q(-l) option, as in
        !           306: @example'kermit -l /dev/ttyi5 -b 9600'
        !           307: This option should always be included with the @q(-l) option, since the
        !           308: speed of an external line is not necessarily what you expect.
        !           309: 
        !           310: @q(-p )@i(x)@\Parity -- e,o,m,s,n (even, odd, mark, space, or none).  If parity
        !           311: is other than none, then the 8th-bit prefixing mechanism will be
        !           312: used for transferring 8-bit binary data, provided the opposite
        !           313: Kermit agrees.  The default parity is none.
        !           314: 
        !           315: @q(-t)@\Specifies half duplex, line turnaround with XON as the handshake
        !           316: character.
        !           317: @end(description)
        !           318: 
        !           319: The following commands may be used only with a C-Kermit which is local --
        !           320: either by default or else because the -l option has been specified.
        !           321: 
        !           322: @begin(description,leftmargin +8,indent -8)
        !           323: @q(-g )@i(rfn)@\Actively request a remote server to send the named file
        !           324: or files; @i(rfn) is a file specification in the remote host's own syntax.  If
        !           325: @i(fn) happens to contain any special shell characters, like '@q(*)',
        !           326: these must be quoted, as in
        !           327: @example'kermit -g x\*.\?'
        !           328: 
        !           329: @q(-f)@\Send a 'finish' command to a remote server.
        !           330: 
        !           331: @q(-c)@\Establish a terminal connection over the specified or default
        !           332: communication line, before any protocol transaction takes place.
        !           333: Get back to the local system by typing the escape character
        !           334: (normally Control-Backslash) followed by the letter 'c'.
        !           335: 
        !           336: @q(-n)@\Like @q(-c), but @i(after) a protocol transaction takes place;
        !           337: @q(-c) and @q(-n) may both be used in the same command.  The use of @q(-n)
        !           338: and @q(-c) is illustrated below.
        !           339: @end(description)
        !           340: On a timesharing system, the @q(-l) and @q(-b) options will also have to
        !           341: be included with the @q(-r), @q(-k), or @q(-s) options if the other
        !           342: Kermit is on a remote system.
        !           343: 
        !           344: Several other command-line options are provided:
        !           345: @begin(description,leftmargin +8,indent -8)
        !           346: @q(-i)@\Specifies that files should be sent or received exactly "as is"
        !           347: with no conversions.  This option is necessary for transmitting
        !           348: binary files.  It may also be used to slightly boost efficiency
        !           349: in Unix-to-Unix transfers of text files by eliminating CRLF/newline
        !           350: conversion.
        !           351: 
        !           352: @q(-w)@\Write-Protect -- Avoid filename collisions for incoming files.
        !           353: 
        !           354: @q(-q)@\Quiet -- Suppress screen update during file transfer, for instance
        !           355: to allow a file transfer to proceed in the background.
        !           356: 
        !           357: @q(-d)@\Debug -- Record debugging information in the file @q(debug.log) in 
        !           358: the current directory.  Use this option if you believe the program
        !           359: is misbehaving, and show the resulting log to your local
        !           360: kermit maintainer.
        !           361: 
        !           362: @q(-h)@\Help -- Display a brief synopsis of the command line options.
        !           363: @end(description)
        !           364: The command line may contain no more than one protocol action option.
        !           365: 
        !           366: Files are sent with their own names, except that lowercase letters are raised
        !           367: to upper, pathnames are stripped off, certain special characters like (`@q[~]')
        !           368: and (`@q[#]') are changed to `@q(X)', and if the file name begins with a
        !           369: period, an `@q(X)' is inserted before it.  Incoming files are stored under
        !           370: their own names except that uppercase letters are lowered, and, if @q(-w) was
        !           371: specified, a "generation number" is appended to the name if it has the same
        !           372: name as an existing file which would otherwise be overwritten.  If the @q(-a)
        !           373: option is included, then the same rules apply to its argument.  The file
        !           374: transfer display shows any transformations performed upon filenames.
        !           375: 
        !           376: During transmission, files are encoded as follows:
        !           377: @begin(itemize)
        !           378: Control characters are converted to prefixed printables.
        !           379: 
        !           380: Sequences of repeated characters are collapsed via repeat counts, if
        !           381: the other Kermit is also capable of repeated-@|character compression.
        !           382: 
        !           383: If parity is being used on the communication line, data characters with 
        !           384: the 8th (parity) bit on are specially prefixed, provided the other Kermit
        !           385: is capable of 8th-bit prefixing; if not, 8-bit binary files cannot be
        !           386: successfully transferred.
        !           387: 
        !           388: Conversion is done between Unix newlines and carriage-@|return-@|linefeed 
        !           389: sequences unless the @q(-i) option was specified.
        !           390: @end(itemize)
        !           391: 
        !           392: @subheading(Command Line Examples:)
        !           393: 
        !           394: @exx(kermit -l /dev/ttyi5 -b 1200 -cn -r)
        !           395: This command connects you to the system on the other end of @q(ttyi5) at
        !           396: 1200 baud, where you presumably log in and run Kermit with a 'send'
        !           397: command.  After you escape back, C-Kermit waits for a file (or files) to
        !           398: arrive.  When the file transfer is completed, you are again connected to
        !           399: the remote system so that you can logout.
        !           400: 
        !           401: @exx(kermit -l /dev/ttyi4 -b 1800 -cntp m -r -a foo)
        !           402: This command is like the preceding one, except the remote system in this
        !           403: case uses half duplex communication with mark parity.  The first file
        !           404: that arrives is stored under the name @q(foo).
        !           405: 
        !           406: @exx(kermit -l /dev/ttyi6 -b 9600 -c | tek)
        !           407: This example uses Kermit to connect your terminal to the system at the
        !           408: other end of @q(ttyi6).  The C-Kermit terminal connection does not
        !           409: provide any particular terminal emulation, so C-Kermit's standard i/o is
        !           410: piped through a (hypothetical) program called tek, which performs (say)
        !           411: Tektronix emulation.
        !           412: 
        !           413: @exx(kermit -l /dev/ttyi6 -b 9600 -nf)
        !           414: This command would be used to shut down a remote server and then connect
        !           415: to the remote system, in order to log out or to make further use of it.
        !           416: The @q(-n) option is invoked @i(after) @q(-f) (@q[-c] would have been invoked
        !           417: before).
        !           418: 
        !           419: @exx(kermit -l /dev/ttyi6 -b 9600 -qg foo.\* &)
        !           420: This command causes C-Kermit to be invoked in the background, getting a group
        !           421: of files from a remote server (note the quoting of the `@q[*]' character).  No
        !           422: display occurs on the screen, and the keyboard is not sampled for
        !           423: interruption commands.  This allows other work to be done while file
        !           424: transfers proceed in the background.
        !           425: 
        !           426: @exx(kermit -l /dev/ttyi6 -b 9600 -g foo.\* > foo.log < /dev/null &)
        !           427: This command is like the previous one, except the file transfer display has
        !           428: been redirected to the file @q(foo.log).  Standard input is also redirected, to
        !           429: prevent C-Kermit from sampling it for interruption commands.
        !           430: 
        !           431: @exx(kermit -iwx)
        !           432: This command starts up C-Kermit as a server.  Files are transmitted with
        !           433: no newline/@|carriage-@|return-@|linefeed conversion; the @q(-i) option is
        !           434: necessary for binary file transfer and useful for Unix-@|to-@|Unix transfers.
        !           435: Incoming files that have the same names as existing files are given new, unique
        !           436: names.
        !           437: 
        !           438: @exx(kermit -l /dev/ttyi6 -b 9600)
        !           439: This command sets the communication line and speed.  Since no action is
        !           440: specified, C-Kermit issues a prompt and enters an interactive dialog with
        !           441: you.  Any settings given on the command line remain in force during the
        !           442: dialog, unless explicitly changed.
        !           443: 
        !           444: @exx(kermit)
        !           445: This command starts up Kermit interactively with all default settings.
        !           446: 
        !           447: The next example shows how Unix Kermit might be used to send an entire
        !           448: directory tree from one Unix system to another, using the tar program as
        !           449: Kermit's standard input and output.  On the orginating system, in this case the
        !           450: remote, type (for instance):@label(-uxtar)
        !           451: 
        !           452: @exx(tar cf - /usr/fdc | kermit -is -)
        !           453: This causes tar to send the directory @q(/usr/fdc) (and all its files and all
        !           454: its subdirectories and all their files...) to standard output instead of to a
        !           455: tape; kermit receives this as standard input and sends it as a binary file.
        !           456: On the receiving system, in this case the local one, type (for instance):
        !           457: 
        !           458: @exx(kermit -il /dev/ttyi5 -b 9600 -k | tar xf -)
        !           459: Kermit receives the tar archive, and sends it via standard output to its own
        !           460: copy of tar, which extracts from it a replica of the original directory tree.
        !           461: 
        !           462: A final example shows how a Unix compression utility might be used to speed
        !           463: up Kermit file transfers:
        !           464: @begin(example)
        !           465: compress file | kermit -is -     (@i(sender))
        !           466: kermit -ik | uncompress          (@i(receiver))
        !           467: @end(example)  
        !           468: 
        !           469: @subheading(Exit Status Codes:)
        !           470: 
        !           471: Unix Kermit returns an exit status of zero, except when a fatal error is
        !           472: encountered, where the exit status is set to one.  With background
        !           473: operation (e.g., `@q(&)' at end of invoking command line) driven by scripted
        !           474: interactive commands (redirected standard input and/or take files),
        !           475: any failed interactive command (such as failed dial or script attempt)
        !           476: causes the fatal error exit.
        !           477: 
        !           478: 
        !           479: @section(Interactive Operation)
        !           480: 
        !           481: C-Kermit's interactive command prompt is "@q(C-Kermit>)".  In response to this
        !           482: prompt, you may type any valid command.  C-Kermit executes the command and
        !           483: then prompts you for another command.  The process continues until you
        !           484: instruct the program to terminate.
        !           485: 
        !           486: Commands begin with a keyword, normally an English verb, such as "send".
        !           487: You may omit trailing characters from any keyword, so long as you specify
        !           488: sufficient characters to distinguish it from any other keyword valid in that
        !           489: field.  Certain commonly-@|used keywords (such as "send", "receive", "connect")
        !           490: have special non-@|unique abbreviations ("s" for "send", "r" for "receive",
        !           491: "c" for "connect").
        !           492: 
        !           493: Certain characters have special functions during typein of interactive
        !           494: commands:
        !           495: @Begin(Description,leftmargin +8,indent -4)
        !           496: @q(?)@\Question mark, typed at any point in a command, will produce a
        !           497: message explaining what is possible or expected at that point.  Depending on
        !           498: the context, the message may be a brief phrase, a menu of keywords, or a list
        !           499: of files.
        !           500: 
        !           501: @q(ESC)@\(The Escape or Altmode key) -- Request completion of the current
        !           502: keyword or filename, or insertion of a default value.  The result will be a
        !           503: beep if the requested operation fails.
        !           504: 
        !           505: @q(DEL)@\(The Delete or Rubout key) -- Delete the previous character from the
        !           506: command.  You may also use BS (Backspace, Control-H) for this function.
        !           507: 
        !           508: @q(^W)@\(Control-W) -- Erase the rightmost word from the command line.
        !           509: 
        !           510: @q(^U)@\(Control-U) -- Erase the entire command.
        !           511: 
        !           512: @q(^R)@\(Control-R) -- Redisplay the current command.
        !           513: 
        !           514: @q(SP)@\(Space) -- Delimits fields (keywords, filenames, numbers) within
        !           515: a command.  HT (Horizontal Tab) may also be used for this purpose.
        !           516: 
        !           517: @q(CR)@\(Carriage Return) -- Enters the command for execution.  LF (Linefeed)
        !           518: or FF (formfeed) may also be used for this purpose.
        !           519: 
        !           520: @q(\)@\(Backslash) -- Enter any of the above characters into the command,
        !           521: literally.  To enter a backslash, type two backslashes in a row (@q[\\]).
        !           522: A backslash at the end of a command line causes the next line to be treated
        !           523: as a continuation line; this is useful for readability in command files,
        !           524: especially in the 'script' command.
        !           525: @End(Description)
        !           526: You may type the editing characters (@q[DEL], @q[^W], etc) repeatedly, to
        !           527: delete all the way back to the prompt.  No action will be performed until the
        !           528: command is entered by typing carriage return, linefeed, or formfeed.  If you
        !           529: make any mistakes, you will receive an informative error message and a new
        !           530: prompt -- make liberal use of `@q[?]' and ESC to feel your way through the
        !           531: commands.  One important command is "help" -- you should use it the first time
        !           532: you run C-Kermit.
        !           533: 
        !           534: A command line beginning with a percent sign @qq(%) is ignored.  Such
        !           535: lines may be used to include illustrative commentary in Kermit command dialogs.
        !           536: 
        !           537: Interactive C-Kermit accepts commands from files as well as from the
        !           538: keyboard.  When you enter interactive dialog, C-Kermit looks for the file
        !           539: @q(.kermrc) in your home or current directory (first it looks in the home
        !           540: directory, then in the current one) and executes any commands it finds there.
        !           541: These commands must be in interactive format, not Unix command-@|line format.
        !           542: A "take" command is also provided for use at any time during an interactive
        !           543: session.  Command files may be nested to any reasonable depth.
        !           544: 
        !           545: Here is a brief list of C-Kermit interactive commands:
        !           546: @begin(format,spread 0)
        !           547: @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
        !           548: @>!@\  Execute a Unix shell command, or start a shell.
        !           549: @>bye@\  Terminate and log out a remote Kermit server.
        !           550: @>close@\  Close a log file.
        !           551: @>connect@\  Establish a terminal connection to a remote system.
        !           552: @>cwd@\  Change Working Directory.
        !           553: @>dial@\  Dial a telephone number.
        !           554: @>directory@\  Display a directory listing.
        !           555: @>echo@\  Display arguments literally.
        !           556: @>exit@\  Exit from the program, closing any open files.
        !           557: @>finish@\  Instruct a remote Kermit server to exit, but not log out.
        !           558: @>get@\  Get files from a remote Kermit server.
        !           559: @>help@\  Display a help message for a given command.
        !           560: @>log@\  Open a log file -- debugging, packet, session, transaction.
        !           561: @>quit@\  Same as 'exit'.
        !           562: @>receive@\  Passively wait for files to arrive.
        !           563: @>remote@\  Issue file management commands to a remote Kermit server.
        !           564: @>script@\  Execute a login script with a remote system.
        !           565: @>send@\  Send files.
        !           566: @>server@\  Begin server operation.
        !           567: @>set@\  Set various parameters.
        !           568: @>show@\  Display values of 'set' parameters.
        !           569: @>space@\  Display current disk space usage.
        !           570: @>statistics@\  Display statistics about most recent transaction.
        !           571: @>take@\  Execute commands from a file.
        !           572: @end(format)
        !           573: 
        !           574: The 'set' parameters are:
        !           575: @begin(format,spread 0)
        !           576: @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
        !           577: @>block-check@\  Level of packet error detection.
        !           578: @>delay@\  How long to wait before sending first packet.
        !           579: @>duplex@\  Specify which side echoes during 'connect'.
        !           580: @>escape-character@\  Prefix for "escape commands" during 'connect'.
        !           581: @>file@\  Set various file parameters.
        !           582: @>flow-control@\  Communication line full-duplex flow control.
        !           583: @>handshake@\  Communication line half-duplex turnaround character.
        !           584: @>incomplete@\  Disposition for incompletely received files.
        !           585: @>line@\  Communication line device name.
        !           586: @>modem-dialer@\  Type of modem-dialer on communication line.
        !           587: @>parity@\  Communication line character parity.
        !           588: @>prompt@\  The C-Kermit program's interactive command prompt.
        !           589: @>receive@\  Parameters for inbound packets.
        !           590: @>send@\  Parameters for outbound packets.
        !           591: @>speed@\  Communication line speed.
        !           592: @end(format)
        !           593: 
        !           594: The 'remote' commands are:
        !           595: @begin(format,spread 0)
        !           596: @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
        !           597: @>cwd@\  Change remote working directory.
        !           598: @>delete@\  Delete remote files.
        !           599: @>directory@\  Display a listing of remote file names.
        !           600: @>help@\  Request help from a remote server.
        !           601: @>host@\  Issue a command to the remote host in its own command language.
        !           602: @>space@\  Display current disk space usage on remote system.
        !           603: @>type@\  Display a remote file on your screen.
        !           604: @>who@\  Display who's logged in, or get information about a user.
        !           605: @end(format)
        !           606: 
        !           607: Most of these commands are described adequately in the Kermit User Guide.
        !           608: Special aspects of certain Unix Kermit commands are described below.
        !           609: 
        !           610: @heading<The 'send' command>
        !           611: 
        !           612: Syntax:  @q<send >@i(fn)@q<@ @ - >@i<or>@q< -@ @ >@q<send >@i(fn1)@q< >@i<rfn1>
        !           613: 
        !           614: Send the file or files denoted by @i(fn) to the other Kermit, which should be
        !           615: running as a server, or which should be given the 'receive' command.  Each file
        !           616: is sent under its own name (as described above, or as specified by the 'set
        !           617: file names' command).  If the second form of the 'send' command is used, i.e.
        !           618: with @i(fn1) denoting a single Unix file, @i(rfn1) may be specified as a name
        !           619: to send it under.  The 'send' command may be abbreviated to 's', even though
        !           620: 's' is not a unique abbreviation for a top-level C-Kermit command.
        !           621: 
        !           622: The wildcard (meta) characters `@q[*]' and `@q[?]' are accepted in @i(fn).  If
        !           623: `@q[?]' is to be included, it must be prefixed by `@q[\]' to override its
        !           624: normal function of providing help.  `@q[*]' matches any string, `@q[?]' matches
        !           625: any single character.  Other notations for file groups, like `@q([a-z]og)', are
        !           626: not available in interactive commands (though of course they are available on
        !           627: the command line).  When @i(fn) contains `@q[*]' or `@q[?]' characters, there
        !           628: is a limit to the number of files that can be matched, which varies from system
        !           629: to system.  If you get the message "Too many files match" then you'll have to
        !           630: make a more judicious selection.  If @i(fn) was of the form
        !           631: @example(usr/longname/anotherlongname/*)
        !           632: then C-Kermit's string space will fill up rapidly -- try doing a cwd (see
        !           633: below) to the path in question and reissuing the command.
        !           634: 
        !           635: @i<Note> -- C-Kermit sends only from the current or specified directory.
        !           636: It does not traverse directory trees.  If the source directory contains
        !           637: subdirectories, they will be skipped.  Conversely, C-Kermit does not create
        !           638: directories when receiving files.  If you have a need to do this, you can
        !           639: pipe tar through C-Kermit, as shown in the example on page @pageref(-uxtar),
        !           640: or under System III/V Unix you can use cpio.
        !           641: 
        !           642: @i<Another Note> -- C-Kermit does not skip over "invisible" files that match
        !           643: the file specification; Unix systems usually treat files whose names start
        !           644: with a dot (like @q(.login), @q(.cshrc), and @q(.kermrc)) as invisible.
        !           645: Similarly for "temporary" files whose names start with "@q(#)".
        !           646: 
        !           647: @heading<The 'receive' command>
        !           648: 
        !           649: Syntax:  @q<receive@ @ - >@i<or>@q< -@ @ receive >@i<fn1>
        !           650: 
        !           651: Passively wait for files to arrive from the other Kermit, which must be given
        !           652: the 'send' command -- the 'receive' command does not work in conjunction with a
        !           653: server (use 'get' for that).  If @i(fn1) is specified, store the first incoming
        !           654: file under that name.  The 'receive' command may be abbreviated to 'r'.
        !           655: 
        !           656: 
        !           657: @heading<The 'get' command:>
        !           658: 
        !           659: Syntax:@q<  get >@i<rfn>
        !           660: @begin(example)
        !           661:     @i<or>: get
        !           662:             @i(rfn)
        !           663:             @i(fn1)
        !           664: @end(example)
        !           665: Request a remote Kermit server to send the named file or files.  Since a
        !           666: remote file specification (or list) might contain spaces, which normally
        !           667: delimit fields of a C-Kermit command, an alternate form of the command is
        !           668: provided to allow the inbound file to be given a new name: type 'get' alone
        !           669: on a line, and you will be prompted separately for the remote and local
        !           670: file specifications, for example
        !           671: @Begin(Example)
        !           672: C-Kermit>@ux(get)
        !           673:  Remote file specification: @ux(profile exec)
        !           674:  Local name to store it under: @ux(profile.exec)
        !           675: @End(Example)
        !           676: As with 'receive', if more than one file arrives as a result of the 'get'
        !           677: command, only the first will be stored under the alternate name given by
        !           678: @i(fn1); the remaining files will be stored under their own names if possible.
        !           679: If a `@q[?]' is to be included in the remote file specification, you must
        !           680: prefix it with `@q[\]' to suppress its normal function of providing help.
        !           681: 
        !           682: If you have started a multiline 'get' command, you may escape from its
        !           683: lower-@|level prompts by typing a carriage return in response to the prompt,
        !           684: e.g.
        !           685: @Begin(Example)
        !           686: C-Kermit>@ux(get)
        !           687:  Remote file specification: @ux(foo)
        !           688:  Local name to store it under: @i<(Type a carriage return here)>
        !           689: (cancelled)
        !           690: C-Kermit>
        !           691: @End(Example)
        !           692: 
        !           693: @heading(The 'server' command:)
        !           694: 
        !           695: The 'server' command places C-Kermit in "server mode" on the currently selected
        !           696: communication line.  All further commands must arrive as valid Kermit packets
        !           697: from the Kermit on the other end of the line.  The Unix Kermit server can
        !           698: respond to the following commands:
        !           699: @begin(format,spread 0,above 1,below 1)
        !           700: @tabclear()@tabset(2.25inches)
        !           701: @u<Command>@\@ux<Server Response>
        !           702:   get@\  Sends files
        !           703:   send@\  Receives files
        !           704:   bye@\  Attempts to log itself out
        !           705:   finish@\  Exits to level from which it was invoked
        !           706:   remote directory@\  Sends directory lising
        !           707:   remote delete@\  Removes files
        !           708:   remote cwd@\  Changes working directory
        !           709:   remote type@\  Sends files to your screen
        !           710:   remote space@\  Reports about its disk usage
        !           711:   remote who@\  Shows who's logged in
        !           712:   remote host@\  Executes a Unix shell command
        !           713:   remote help@\  Lists these capabilities
        !           714: @end(format)
        !           715: Note that the Unix Kermit server cannot always respond to a BYE command.
        !           716: It will attempt to do so using "@q<kill()>", but this will not work
        !           717: on all systems or under all conditions.
        !           718: 
        !           719: If the Kermit server is directed at an external line (i.e. it is in
        !           720: "local mode") then the console may be used for other work if you have
        !           721: 'set file display off'; normally the program expects the
        !           722: console to be used to observe file transfers and enter status queries or
        !           723: interruption commands.  The way to get C-Kermit into background operation from
        !           724: interactive command level varies from system to system (e.g. on Berkeley Unix
        !           725: you would halt the program with @q(^Z) and then use the C-Shell 'bg' command to
        !           726: continue it in the background).  The more common method
        !           727: is to invoke the program with the desired command line arguments, including
        !           728: "@q(-q)", and with a terminating "@q(&)".
        !           729: 
        !           730: When the Unix Kermit server is given a 'remote host' command, it executes it
        !           731: using the shell invoked upon login, e.g. the Bourne shell or the Berkeley
        !           732: C-Shell.
        !           733: 
        !           734: @Heading(The 'remote', 'bye', and 'finish' commands:)
        !           735: 
        !           736: C-Kermit may itself request services from a remote Kermit server.  In
        !           737: addition to 'send' and 'get', the following commands may also be sent from
        !           738: C-Kermit to a Kermit server:
        !           739: 
        !           740: @begin(description,leftmargin +8,indent -4)
        !           741: remote cwd [@i(directory)]@\If the optional remote directory specification is
        !           742: included, you will be prompted on a separate line for a password, which will
        !           743: not echo as you type it.
        !           744: @end(description)
        !           745: @begin(description,leftmargin +28, indent -24,spread 0,above 1)
        !           746: remote delete rfn@\delete remote file or files.
        !           747: 
        !           748: remote directory [@i(rfn)]@\directory listing of remote files.
        !           749: 
        !           750: remote host @i(command)@\command in remote host's own command language.
        !           751: 
        !           752: remote space@\disk usage report from remote host.
        !           753: 
        !           754: remote type [@i(rfn)]@\display remote file or files on the screen.
        !           755: 
        !           756: remote who [@i(user)]@\display information about who's logged in.
        !           757: 
        !           758: remote help@\display remote server's capabilities.
        !           759: @end(description)
        !           760: @begin(description,leftmargin +8,indent -4)
        !           761: bye @i(and) finish:@\When connected to a remote Kermit server, these commands
        !           762: cause the remote server to terminate; 'finish' returns it to Kermit or system
        !           763: command level (depending on the implementation or how the program was invoked);
        !           764: 'bye' also requests it to log itself out.
        !           765: @end(description)
        !           766: @heading(The 'log' and 'close' commands:)
        !           767: 
        !           768: Syntax: @q<log {debugging, packets, session, transactions} >[ @i(fn1) ]
        !           769: 
        !           770: C-Kermit's progress may be logged in various ways.  The 'log' command
        !           771: opens a log, the 'close' command closes it.  In addition, all open logs
        !           772: are closed by the 'exit' and 'quit' commands.  A name may be specified for
        !           773: a log file; if the name is omitted, the file is created with a default
        !           774: name as shown below.
        !           775: 
        !           776: @begin(description,leftmargin +4,indent -4)
        !           777: log debugging@\This produces a voluminous log of the internal workings of
        !           778: C-Kermit, of use to Kermit developers or maintainers in tracking down suspected
        !           779: bugs in the C-Kermit program.  Use of this feature dramatically slows down the
        !           780: Kermit protocol.  Default name: @q(debug.log).
        !           781: 
        !           782: log packets@\This produces a record of all the packets that go in and out of
        !           783: the communication port.  This log is of use to Kermit maintainers who are
        !           784: tracking down protocol problems in either C-Kermit or any Kermit that
        !           785: C-Kermit is connected to.  Default name:  @q(packet.log).
        !           786: 
        !           787: log session@\This log will contain a copy of everything you see on your screen
        !           788: during the 'connect' command, except for local messages or interaction with
        !           789: local escape commands.  Default name:  @q(session.log).
        !           790: 
        !           791: log transactions@\The transaction log is a record of all the files that were
        !           792: sent or received while transaction logging was in effect.  It includes time
        !           793: stamps and statistics, filename transformations, and records of any
        !           794: errors that may have occurred.  The transaction log allows you to have
        !           795: long unattended file transfer sessions without fear of missing some
        !           796: vital screen message.  Default name:  @q(transact.log).
        !           797: @end(description)
        !           798: The 'close' command explicitly closes a log, e.g. 'close debug'.
        !           799: 
        !           800: @i<Note:>  Debug and Transaction logs are a compile-time option; C-Kermit may
        !           801: be compiled without these logs, in which case it will run faster, it will
        !           802: take up less space on the disk, and the commands relating to them will not
        !           803: be present.
        !           804: 
        !           805: @Heading(Local File Management Commands:)
        !           806: 
        !           807: Unix Kermit allows some degree of local file management from interactive
        !           808: command level:
        !           809: @begin(description,leftmargin +4,indent -4)
        !           810: directory [@i(fn)]@\
        !           811: Displays a listing of the names, modes, sizes, and dates of files
        !           812: matching @i(fn) (which defaults to `@q[*]').  Equivalent to `@q(ls -l)'.
        !           813: 
        !           814: cwd [directory-name]@\
        !           815: Changes Kermit's working directory to the one given, or to the
        !           816: default directory if the directory name is omitted.  This command affects only
        !           817: the Kermit process and any processes it may subsequently create.
        !           818: 
        !           819: space@\
        !           820: Display information about disk space and/or quota in the current
        !           821: directory and device.
        !           822: 
        !           823: @q(! )[@i(command)]@\
        !           824: The command is executed by the Unix shell.  If no command is specified, then an
        !           825: interactive shell is started; exiting from the shell, e.g. by typing Control-D,
        !           826: will return you to C-Kermit command level.  C-Kermit attempts to use your
        !           827: preferred, customary shell.  Use the `@q(!)' command to provide file management
        !           828: or other functions not explicitly provided by C-Kermit commands.  The `@q(!)'
        !           829: command has certain peculiarities:
        !           830: @begin(itemize,spread 0)       
        !           831: At least one space must separate the '!' from the shell command.
        !           832: 
        !           833: A 'cd' command executed in this manner will have no effect -- use the
        !           834: C-Kermit 'cwd' command instead. 
        !           835: @end(itemize)
        !           836: @end(description)
        !           837: 
        !           838: @heading(The 'set' and 'show' Commands:)
        !           839: 
        !           840: Since Kermit is designed to allow diverse systems to communicate, it is
        !           841: often necessary to issue special instructions to allow the program to adapt
        !           842: to peculiarities of the another system or the communication path.  These
        !           843: instructions are accomplished by the 'set' command.  The 'show' command may
        !           844: be used to display current settings.  Here is a brief synopsis of settings
        !           845: available in the current release of C-Kermit:
        !           846: 
        !           847: @begin(description,leftmargin +4,indent -4)
        !           848: block-check {1, 2, 3}@\ Determines the level of per-packet error detection.
        !           849: "1" is a single-@|character 6-bit checksum, folded to include the values of all
        !           850: bits from each character.  "2" is a 2-character, 12-bit checksum.  "3" is a
        !           851: 3-character, 16-bit cyclic redundancy check (CRC).  The higher the block check,
        !           852: the better the error detection and correction and the higher the resulting
        !           853: overhead.  Type 1 is most commonly used; it is supported by all Kermit
        !           854: implementations, and it has proven adequate in most circumstances.  Types 2 or
        !           855: 3 would be used to advantage when transferring 8-bit binary files over noisy
        !           856: lines.
        !           857: 
        !           858: delay @i(n)@\How many seconds to wait before sending the first packet after a
        !           859: 'send' command.  Used in remote mode to give you time to escape back to your
        !           860: local Kermit and issue a 'receive' command.  Normally 5 seconds.
        !           861: 
        !           862: duplex {full, half}@\For use during 'connect'.  Specifies which side is doing
        !           863: the echoing; 'full' means the other side, 'half' means C-Kermit must echo
        !           864: typein itself.
        !           865: 
        !           866: escape-character @i(cc)@\For use during 'connect' to get C-Kermit's attention.
        !           867: The escape character acts as a prefix to an 'escape command', for instance to
        !           868: close the connection and return to C-Kermit or Unix command level.
        !           869: The normal escape character is Control-Backslash (28).
        !           870: The escape character is also used in System III/V implementations
        !           871: to prefix interrupt commands during file transfers.
        !           872: 
        !           873: file {display, names, type, warning}@\
        !           874: Establish various file-related parameters:
        !           875: @begin(description,leftmargin +4,indent -4)
        !           876: display {on, off}@\Normally 'on'; when in local mode, display progress of file
        !           877: transfers on the screen (stdout), and listen to the keyboard (stdin)
        !           878: for interruptions.  If off (-q on command line) none of this is
        !           879: done, and the file transfer may proceed in the background oblivious
        !           880: to any other work concurrently done at the console terminal.
        !           881: 
        !           882: names {converted, literal}@\
        !           883: Normally converted, which mean that outbound filenames have path
        !           884: specifications stripped, lowercase letters raised to upper,
        !           885: tildes and extra periods changed to X's, and an X inserted in
        !           886: front of any name that starts with period.  Incoming files have
        !           887: uppercase letters lowered.  Literal means that none of these
        !           888: conversions are done; therefore, any directory path appearing in a
        !           889: received file specification must exist and be write-accessible.
        !           890: When literal naming is being used, the sender should not use path
        !           891: names in the file specification unless the same path exists on the
        !           892: target system and is writable.
        !           893: 
        !           894: type {binary, text}@\Normally text, which means that conversion is done between
        !           895: Unix newline characters and the carriage-@|return/@|linefeed sequences
        !           896: required by the canonical Kermit file transmission format, and in
        !           897: common use on non-@|Unix systems.  Binary means to transmit file
        !           898: contents without conversion.  Binary (`@q(-i)' in command line notation)
        !           899: is necessary for binary files, and desirable in all Unix-@|to-@|Unix
        !           900: transactions to cut down on overhead.
        !           901: 
        !           902: warning {on, off}@\Normally off, which means that incoming files will silently
        !           903: overwrite existing files of the same name.  When on (`@q(-w)' on command line)
        !           904: Kermit will check if an arriving file would overwrite an existing file; if so,
        !           905: it will construct a new name for the arriving file, of the form @q(foo~)@i(n),
        !           906: where foo is the name they share and @i(n) is a "generation number"; if @i(foo)
        !           907: exists, then the new file will be called @q(foo~1).  If @q(foo) and @q(foo~1)
        !           908: exist, the new file will be @q(foo~2), and so on.  If the new name would be
        !           909: longer than the maximum length for a filename, then characters would be deleted
        !           910: from the end first, for instance, @q(thelongestname) on a system with a limit
        !           911: of 14 characters would become @q(thelongestn~1).
        !           912: @begin(quotation)
        !           913: @i(CAUTION:)  If Control-F or Control-B is used to cancel an incoming file,
        !           914: and a file of the same name previously existed, @i(and) the "file warning"
        !           915: feature is not enabled, then the previous copy of the file will disappear.
        !           916: @end(quotation)
        !           917: @end(description)
        !           918: 
        !           919: flow-control {none, xon/xoff}@\Normally xon/xoff for full duplex flow control.
        !           920: Should be set to 'none' if the other system cannot do xon/xoff flow control, or
        !           921: if you have issued a 'set handshake' command.  If set to xon/xoff, then
        !           922: handshake should be set to none.  This setting applies during both terminal
        !           923: connection and file transfer.
        !           924: 
        !           925: incomplete {discard, keep}@\Disposition for incompletely received files.
        !           926: If an incoming file is interrupted or an error occurs during transfer,
        !           927: the part that was received so far is normally discarded.  If you "set
        !           928: incomplete keep" then such file fragments will be kept.
        !           929: 
        !           930: handshake {xon, xoff, cr, lf, bell, esc, none}@\Normally none.  Otherwise,
        !           931: half-duplex communication line turnaround handshaking is done, which means Unix
        !           932: Kermit will not reply to a packet until it has received the indicated handshake
        !           933: character or has timed out waiting for it; the handshake setting applies only
        !           934: during file transfer.  If you set handshake to other than none, then flow
        !           935: should be set to none.
        !           936: 
        !           937: line [device-name]@\
        !           938: The device name for the communication line to be used for file transfer and
        !           939: terminal connection, e.g. @q(/dev/ttyi3).  If you specify a device name,
        !           940: Kermit will be in local mode, and you should remember to issue any other
        !           941: necessary 'set' commands, such as 'set speed'.  If you omit the device name,
        !           942: Kermit will revert to its default mode of operation.  If you specify
        !           943: @q(/dev/tty), Kermit will enter remote mode (useful when logged in through
        !           944: the "back port" of a system normally used as a local-mode workstation).  When
        !           945: Unix Kermit enters local mode, it attempts to synchronize with other programs
        !           946: (like uucp) that use external communication lines so as to prevent two
        !           947: programs using the same line at once; before attempting to lock the specified
        !           948: line, it will close and unlock any external line that was previously in use.
        !           949: The method used for locking is the "uucp lock file", explained in more detail
        !           950: later.
        !           951: 
        !           952: modem-dialer {direct, hayes, racalvadic, ventel, ...}@\ The type of modem
        !           953: dialer on the communication line.  "Direct" indicates either there is no
        !           954: dialout modem, or that if the line requires carrier detection to open, then
        !           955: 'set line' will hang waiting for an incoming call.  "Hayes", "Ventel", and the
        !           956: others indicate that 'set line' (or the -l argument) will prepare for a
        !           957: subsequent 'dial' command for the given dialer.  Support for new dialers is
        !           958: added from time to time, so type 'set modem ?' for a list of those supported
        !           959: in your copy of Kermit.  See the description of the 'dial' command
        !           960: 
        !           961: parity {even, odd, mark, space, none}@\Specify character parity for use in
        !           962: packets and terminal connection, normally none.  If other than none, C-Kermit
        !           963: will seek to use the 8th-bit prefixing mechanism for transferring 8-bit binary
        !           964: data, which can be used successfully only if the other Kermit agrees; if not,
        !           965: 8-bit binary data cannot be successfully transferred.
        !           966: 
        !           967: prompt [string]@\The given string will be substituted for "@q(C-Kermit)>" as
        !           968: this program's prompt.  If the string is omitted, the prompt will revert to
        !           969: "@q(C-Kermit>)".  If the string is enclosed in doublequotes, the quotes will
        !           970: be stripped and any leading and trailing blanks will be retained.
        !           971: 
        !           972: send @i<parameter>@\
        !           973: Establish parameters to use when sending packets.  These will be in effect
        !           974: only for the initial packet sent, since the other Kermit may override these
        !           975: parameters during the protocol parameter exchange (unless noted below).
        !           976: @begin(description,leftmargin +4,indent -4)
        !           977: end-of-packet @i(cc)@\Specifies the control character needed by the other
        !           978: Kermit to recognize the end of a packet.  C-Kermit sends this character at the
        !           979: end of each packet.  Normally 13 (carriage return), which most Kermit
        !           980: implementations require.  Other Kermits require no terminator at all, still
        !           981: others may require a different terminator, like linefeed (10).
        !           982: 
        !           983: packet-length @i(n)@\Specify the maximum packet length to send.  Normally 90.
        !           984: Shorter packet lengths can be useful on noisy lines, or with systems or front
        !           985: ends or networks that have small buffers.  The shorter the packet, the higher
        !           986: the overhead, but the lower the chance of a packet being corrupted by noise,
        !           987: and the less time to retransmit corrupted packets.  This command overrides
        !           988: the value requested by the other Kermit during protocol initiation.
        !           989: 
        !           990: pad-character @i(cc)@\Designate a character to send before each packet.
        !           991: Normally, none is sent.  Outbound padding is sometimes necessary for
        !           992: communicating with slow half duplex systems that provide no other means of
        !           993: line turnaround control.  It can also be used to send special characters
        !           994: to communications equipment that needs to be put in "transparent" or
        !           995: "no echo" mode, when this can be accomplished in by feeding it a certain
        !           996: control character.
        !           997: 
        !           998: padding @i(n)@\How many pad characters to send, normally 0.
        !           999: 
        !          1000: start-of-packet @i(cc)@\The normal Kermit packet prefix is Control-A (1); this
        !          1001: command changes the prefix C-Kermit puts on outbound packets.  The only
        !          1002: reasons this should ever be changed would be: Some piece of equipment somewhere
        !          1003: between the two Kermit programs will not pass through a Control-A; or, some
        !          1004: piece of of equipment similarly placed is echoing its input.  In the latter
        !          1005: case, the recipient of such an echo can change the packet prefix for outbound
        !          1006: packets to be different from that of arriving packets, so that the echoed
        !          1007: packets will be ignored.  The opposite Kermit must also be told to change the
        !          1008: prefix for its inbound packets.
        !          1009: 
        !          1010: timeout @i(n)@\Specifies the number of seconds you want the other Kermit
        !          1011: to wait for a packet before timing it out and requesting retransmission.
        !          1012: @end(description)
        !          1013: 
        !          1014: receive @i<parameter>@\
        !          1015: Establish parameters to request the other Kermit to use when sending packets.
        !          1016: @begin(description,leftmargin +4,indent -4)
        !          1017: end-of-packet @i(cc)@\Requests the other Kermit to terminate its packets with
        !          1018: the specified character.
        !          1019: 
        !          1020: packet-length @i(n)@\Specify the maximum packet length to that you want the
        !          1021: other Kermit to send.  Normally 90.
        !          1022: 
        !          1023: pad-character @i(cc)@\C-Kermit normally does not need to have incoming packets
        !          1024: preceded with pad characters.  This command allows C-Kermit to request the
        !          1025: other Kermit to use @i(cc) as a pad character.  Default @i(cc) is NUL, ASCII 0.
        !          1026: 
        !          1027: padding @i(n)@\How many pad characters to ask for, normally 0.
        !          1028: 
        !          1029: start-of-packet @i(cc)@\Change the prefix C-Kermit looks for on inbound
        !          1030: packets to correspond with what the other Kermit is sending.
        !          1031: 
        !          1032: timeout @i(n)@\Normally, each Kermit partner sets its packet timeout interval
        !          1033: based on what the opposite Kermit requests.  This command allows you to
        !          1034: override the normal procedure and specify a timeout interval for Unix Kermit to
        !          1035: use when waiting for packets from the other Kermit.  If you specify 0, then no
        !          1036: timeouts will occur, and Unix Kermit will wait forever for expected packets to
        !          1037: arrive.
        !          1038: @end(description)
        !          1039: 
        !          1040: speed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600}@\The baud rate for
        !          1041: the external communication line.  This command cannot be used to change the
        !          1042: speed of your own console terminal.  Many Unix systems are set up in such a way
        !          1043: that you must give this command after a 'set line' command before you can use
        !          1044: the line.  'set baud' is a synomym for 'set speed'.
        !          1045: @end(description)
        !          1046: 
        !          1047: @heading(The 'show' Command:)
        !          1048: 
        !          1049: Syntax: @q<show {parameters, versions}>
        !          1050: 
        !          1051: The "show" command with the default argument of "parameters" displays
        !          1052: the values of all the 'set' parameters described above.  If you type
        !          1053: "show versions", then C-Kermit will display the version numbers and
        !          1054: dates of all its internal modules.  You should use the "show versions"
        !          1055: command to ascertain the vintage of your Kermit program before reporting
        !          1056: problems to Kermit maintainers.
        !          1057: 
        !          1058: @heading(The 'statistics' Command:)
        !          1059: 
        !          1060: The statistics command displays information about the most recent Kermit
        !          1061: protocol transaction, including file and communication line i/o, timing
        !          1062: and efficiency, as well as what encoding options were in effect (such as
        !          1063: 8th-bit prefixing, repeat-@|count compression).
        !          1064: 
        !          1065: @heading(The 'take' and 'echo' Commands:)
        !          1066: 
        !          1067: Syntax: @q<take >@i<fn1>@*
        !          1068: @ @ @ @ @ @q<echo >@i<[text to be echoed]>
        !          1069: 
        !          1070: The 'take' command instructs C-Kermit to execute commands from the named
        !          1071: file.  The file may contain any interactive C-Kermit commands, including
        !          1072: 'take'; command files may be nested to any reasonable depth.  The 'echo'
        !          1073: command may be used within command files to issue greetings, announce
        !          1074: progress, ring the terminal bell, etc.
        !          1075: 
        !          1076: The 'echo' command should not be confused with the Unix 'echo' command, which
        !          1077: can be used to show how meta characters would be expanded.  The Kermit echo
        !          1078: command simply displays its text argument (almost) literally at the terminal;
        !          1079: the argument may contain octal escapes of the form @qq(\ooo),
        !          1080: where @q(o) is an octal digit (0-7), and there may be 1, 2, or 3 such digits,
        !          1081: whose value specify an ASCII character, such as @qq(\007) (or @qq(\07) or
        !          1082: just @qq(\7)) for beep, @qq(\012) for newline, etc.  Of course, each
        !          1083: backslash must be must be entered twice in order for it to be passed along
        !          1084: to the echo command by the Kermit command parser.
        !          1085: 
        !          1086: Take-command files are in exactly the same syntax as interactive commands.
        !          1087: Note that this implies that if you want to include special characters like
        !          1088: question mark or backslash that you would have to quote with backslash when
        !          1089: typing interactive commands, you must quote these characters the same way
        !          1090: in command files.  Long lines may be continued by ending them with a single
        !          1091: backslash.
        !          1092: 
        !          1093: Command files may be used in lieu of command macros, which have not been
        !          1094: implemented in this version of C-Kermit.  For instance, if you commonly
        !          1095: connect to a system called 'B' that is connected to ttyh7 at 4800 baud,
        !          1096: you could create a file called @q(b) containing the commands
        !          1097: @begin(example)
        !          1098: % C-Kermit command file to connect to System B thru /dev/ttyh7
        !          1099: set line /dev/ttyh7
        !          1100: set speed 4800
        !          1101: % Beep and give message
        !          1102: echo \\007Connecting to System B...
        !          1103: connect
        !          1104: @end(example)
        !          1105: and then simply type 'take b' (or 't b' since no other commands begin with
        !          1106: the letter 't') whenever you wish to connect to system B.  Note the
        !          1107: comment lines and the beep inserted into the 'echo' command.
        !          1108: 
        !          1109: @index<IBM>
        !          1110: For connecting to IBM mainframes, a number of 'set' commands are required;
        !          1111: these, too, are conveniently collected into a 'take' file like this one:
        !          1112: @begin(example)
        !          1113: % Sample C-Kermit command file to set up current line
        !          1114: % for IBM mainframe communication
        !          1115: %
        !          1116: set parity mark
        !          1117: set handshake xon
        !          1118: set flow-control none
        !          1119: set duplex half
        !          1120: @end(example)
        !          1121: 
        !          1122: Note that no single command is available to wipe out all of these settings
        !          1123: and return C-Kermit to its default startup state; to do that, you can either
        !          1124: restart the program, or else make a command file that executes the necessary
        !          1125: 'set' commands:
        !          1126: @begin(example)
        !          1127: % Sample C-Kermit command file to restore normal settings
        !          1128: %
        !          1129: set parity none
        !          1130: set handshake none
        !          1131: set flow-control xon/xoff
        !          1132: set duplex full
        !          1133: @end(example)
        !          1134: 
        !          1135: An implicit 'take' command is executed upon your @q(.kermrc) file upon
        !          1136: C-Kermit's initial entry into interactive dialog.  The @q(.kermrc) file should
        !          1137: contain 'set' or other commands you want to be in effect at all times.
        !          1138: For instance, you might want override the default action when incoming files
        !          1139: have the same names as existing files -- in that case, put the command
        !          1140: @example(set file warning on)
        !          1141: in your @q(.kermrc) file.  On some non-Unix systems that run C-Kermit, this
        !          1142: file might have a different name, such as @q<kermit.ini>.
        !          1143: @begin(quotation)
        !          1144: @i(NOTE:) The initialization file is currently @i(not) processed if Kermit is
        !          1145: invoked with an action command from the command line.  The same effect can be
        !          1146: achieved, however, by defining an alias or shell procedure that starts up
        !          1147: Kermit with the desired command line options.
        !          1148: @end(quotation)
        !          1149: 
        !          1150: Commands executed from take files are not echoed at the terminal.  If you
        !          1151: want to see the commands as well as their output, you could feed the
        !          1152: command file to C-Kermit via redirected stdin, as in
        !          1153: @example('kermit < cmdfile')
        !          1154: Errors encountered during execution of take files (such as failure to complete
        !          1155: dial or script operations) cause termination of the current take file, popping
        !          1156: to the level that invoked it (take file, interactive level, or the shell).
        !          1157: When kermit is executed in the background, errors during execution of a take
        !          1158: file are fatal.
        !          1159: 
        !          1160: @heading(The 'connect' Command:)
        !          1161: 
        !          1162: The connect command links your terminal to another computer as if it were
        !          1163: a local terminal to that computer, through the device specified in the most
        !          1164: recent 'set line' command, or through the default device if your system
        !          1165: is a PC or workstation.  All characters you type at your keyboard
        !          1166: are sent out the communication line, all characters arriving at the
        !          1167: communication port are displayed on your screen.  Current settings of speed,
        !          1168: parity, duplex, and flow-@|control are honored.  If you have issued a 'log
        !          1169: session' command, everything you see on your screen will also be recorded
        !          1170: to your session log.  This provides a way to "capture" files from systems
        !          1171: that don't have Kermit programs available.
        !          1172: 
        !          1173: To get back to your own system, you must type the escape character, which is
        !          1174: Control-@|Backslash (@q[^\]) unless you have changed it with the 'set escape'
        !          1175: command, followed by a single-@|character command, such as 'c' for "close
        !          1176: connection".  Single-@|character commands include:
        !          1177: @begin(description,leftmargin +8,indent -6,spread 0.4)
        !          1178: c@\Close the connection
        !          1179: 
        !          1180: b@\Send a BREAK signal
        !          1181: 
        !          1182: 0@\(zero) send a null
        !          1183: 
        !          1184: s@\Give a status report about the connection
        !          1185: 
        !          1186: h@\Hangup the phone
        !          1187: 
        !          1188: @q[^\]@\Send Control-Backslash itself (whatever you have defined the
        !          1189: escape character to be, typed twice in a row sends one copy of it).
        !          1190: @end(description)
        !          1191: Uppercase and control equivalents for these letters are also accepted.  A
        !          1192: space typed after the escape character is ignored.  Any other character will
        !          1193: produce a beep.
        !          1194: 
        !          1195: The connect command simply displays incoming characters on the screen.  It is
        !          1196: assumed any screen control sequences sent by the host will be handled by
        !          1197: the firmware in your terminal or PC.  If terminal emulation is desired,
        !          1198: then the connect command can invoked from the Unix command line (@q(-c) or
        !          1199: @q(-n)), piped through a terminal emulation filter, e.g.
        !          1200: @example(kermit -l /dev/acu -b 1200 -c | tek)
        !          1201: 'c' is an acceptable non-unique abbreviation for 'connect'.
        !          1202: 
        !          1203: @heading(The 'dial' command:)
        !          1204: 
        !          1205: Syntax: @q(dial )@i(telephone-number-string)
        !          1206: 
        !          1207: @index<Modems>@index<Dialout Modems>
        !          1208: This command controls dialout modems; you should have already issued a "set
        !          1209: line" and "set speed" command to identify the terminal device, and a "set
        !          1210: modem" command to identify the type of modem to be used for dialing.  In the
        !          1211: "dial" command, you supply the phone number and the Kermit program feeds it to
        !          1212: the modem in the appropriate format and then interprets dialer return codes and
        !          1213: modem signals to inform you whether the call was completed.  The
        !          1214: telephone-@|number-@|string may contain imbedded modem-@|dialer commands, such
        !          1215: as comma for Hayes pause, or `@q(&)' for Ventel dialtone wait and `@q(%)' for
        !          1216: Ventel pause (consult your modem manual for details).
        !          1217: 
        !          1218: At the time of this writing, support is included for the following modems:
        !          1219: @begin(itemize,spread 0)
        !          1220: Cermetek Info-Mate 212A
        !          1221: 
        !          1222: DEC DF03-AC
        !          1223: 
        !          1224: DEC DF100 Series
        !          1225: 
        !          1226: DEC DF200 Series
        !          1227: 
        !          1228: General DataComm 212A/ED
        !          1229: 
        !          1230: Hayes Smartmodem 1200 and compatibles
        !          1231: 
        !          1232: Penril
        !          1233: 
        !          1234: Racal Vadic
        !          1235: 
        !          1236: US Robotics 212A
        !          1237: 
        !          1238: Ventel
        !          1239: @end(itemize)
        !          1240: Support for new modems is added to the program from time to time; you
        !          1241: can check the current list by typing "@q<set modem ?>".
        !          1242: 
        !          1243: The device used for dialing out is the one selected in the most recent "set
        !          1244: line" command (or on a workstation, the default line if no "set line" command
        !          1245: was given).  The "dial" command calls locks the path (see the section on line
        !          1246: locking below) and establishes a call on an exclusive basis.  If it is desired
        !          1247: to dial a call and then return to the shell (such as to do kermit activities
        !          1248: depending on standard in/out redirection), it is necessary to place the dialed
        !          1249: call under one device name (say, "@q</dev/cua0>") and then escape to the shell
        !          1250: @i<within Kermit> on a linked device which is separate from the dialed line
        !          1251: (say, "@q</dev/cul0>").  This is the same technique used by uucp (to allow
        !          1252: locks to be placed separately for dialing and conversing).
        !          1253: 
        !          1254: Because modem dialers have strict requirements to override the carrier-@|detect
        !          1255: signal most Unix implementations expect, the sequence for dialing is more rigid
        !          1256: than most other C-Kermit procedures.
        !          1257: 
        !          1258: Example one:
        !          1259: @begin(example)
        !          1260: @ux<kermit -l /dev/cul0 -b 1200>
        !          1261: C-Kermit>@ux<set modem-dialer hayes>   @i(hint: abbreviate) set m h
        !          1262: C-Kermit>@ux<dial 9,5551212>
        !          1263: Connected!
        !          1264: C-Kermit>@ux<connect>                  @i(hint: abbreviate) c
        !          1265: @i(logon, request remote server, etc.)
        !          1266: C-Kermit> ...
        !          1267: C-Kermit>@ux<quit>                     @i(hint: abbreviate) q
        !          1268: @end(example)
        !          1269: this disconnects modem, and unlocks line.
        !          1270: 
        !          1271: Example two:
        !          1272: @begin(example)
        !          1273: @u(kermit)
        !          1274: C-Kermit>@ux(set modem-dialer ventel)
        !          1275: C-Kermit>@ux(set line /dev/cul0)
        !          1276: C-Kermit>@ux(dial 9&5551212%)
        !          1277: Connected!
        !          1278: C-Kermit> ...
        !          1279: @end(example)
        !          1280: Example three:
        !          1281: @begin(example)
        !          1282: kermit
        !          1283: C-Kermit>@ux(take my-dial-procedure)
        !          1284: Connected!
        !          1285: 
        !          1286: @i(file my-dial-procedure):
        !          1287: set modem hayes
        !          1288: set line /dev/tty99
        !          1289: dial 5551212
        !          1290: connect
        !          1291: @end(example)
        !          1292: For Hayes @index<Hayes Modem> dialers, two important switch settings are #1 and
        !          1293: #6.  #1 should be up so that the DTR is only asserted when the line is 'open'.
        !          1294: #6 should be up so carrier-@|detect functions properly.  Switches #2 (English
        !          1295: versus digit result codes) and #4 (Hayes echoes modem commands) may be in
        !          1296: either position.
        !          1297: 
        !          1298: For any dialers in general, this Kermit program requires that the modem provide
        !          1299: the "carrier detect" signal when a call is in progress, and remove that signal
        !          1300: when the call completes or the line drops.  If a switch setting is available to
        !          1301: force carrier detect, it should not be in that setting.  Secondly, this Kermit
        !          1302: program requires that the modem track the computer's "data terminal ready"
        !          1303: signal (DTR).  If a switch setting is available to simulate DTR asserted within
        !          1304: the modem, then it should not be in that setting.  Otherwise the modem will be
        !          1305: unable to hang up at the end of a call or when interrupts are received by
        !          1306: Kermit.
        !          1307: 
        !          1308: If you want to interrupt a dial command in progress (for instance, because
        !          1309: you just realize that you gave it the wrong number), type a Control-C to
        !          1310: get back to command level.
        !          1311: 
        !          1312: @heading(The 'script' Command:)
        !          1313: 
        !          1314: Syntax: @q(script )@i(expect send [expect send] . . .)
        !          1315: 
        !          1316: "expect" has the syntax: @i(expect[-send-expect[-send-expect[...]]])
        !          1317: 
        !          1318: This command facilitates logging into a remote system and/or invoking
        !          1319: programs or other facilities after login on a remote system.
        !          1320: 
        !          1321: This login script facility operates in a manner similar to that commonly
        !          1322: used by the Unix uucp System's "@q(L.sys)" file entries.  A login script 
        !          1323: is a sequence of the form:
        !          1324: @example(@i<expect send [expect send] . . .>)
        !          1325: where @i(expect) is a prompt or message to be issued by the remote site, and
        !          1326: @i(send) is the string (names, numbers, etc) to return.  The send may also be
        !          1327: the keyword EOT, to send Control-D, or BREAK, to send a break signal.  Letters
        !          1328: in send may be prefixed by `@q[~]' to send special characters.  These are:
        !          1329: @begin(description,leftmargin +8,indent -4,spread 0)
        !          1330: @q(~b)@\backspace
        !          1331: 
        !          1332: @q(~s)@\space
        !          1333: 
        !          1334: @q(~q)@\`@q[?]'(trapped by Kermit's command interpreter)
        !          1335: 
        !          1336: @q(~n)@\linefeed
        !          1337: 
        !          1338: @q(~r)@\carriage return
        !          1339: 
        !          1340: @q(~t)@\tab
        !          1341: 
        !          1342: @q(~')@\single quote
        !          1343: 
        !          1344: @q(~~)@\tilde
        !          1345: 
        !          1346: @q(~")@\double quote
        !          1347: 
        !          1348: @q(~x)@\XON (Control-Q)
        !          1349: 
        !          1350: @q(~c)@\don't append a carriage return
        !          1351: 
        !          1352: @q(~)@i(o[o[o]])@ @ an octal character
        !          1353: 
        !          1354: @q(~d)@\delay approx 1/3 second during send
        !          1355: 
        !          1356: @q(~w)@i([d[d]])@ @ wait specified interval during expect, then time out
        !          1357: @end(description)
        !          1358: As with some uucp systems, sent strings are followed by @q(~r) unless they have
        !          1359: a @q(~c).
        !          1360: 
        !          1361: Only the last 7 characters in each expect are matched.  A null @i(expect),
        !          1362: e.g. @q(~0) or two adjacent dashes, causes a short delay before proceeding
        !          1363: to the next send sequence.  A null expect always succeeds.
        !          1364: 
        !          1365: As with uucp, if the expect string does not arrive, the script attempt
        !          1366: fails.  If you expect that a sequence might not arrive, as with uucp, 
        !          1367: conditional sequences may be expressed in the form:
        !          1368: @example(@i<-send-expect[-send-expect[...]]>)
        !          1369: where dashed sequences are followed as long as previous expects fail.
        !          1370: Timeouts for expects can be specified using @q(~w); @q(~w) with no
        !          1371: arguments waits 15 seconds.
        !          1372: 
        !          1373: @i(Expect/send) transactions can be easily be debugged by logging
        !          1374: transactions.  This records all exchanges, both expected and actual.
        !          1375: 
        !          1376: Note that `@q[\]' characters in login scripts, as in any other C-Kermit
        !          1377: interactive commands, must be doubled up.  A line may be ended with a
        !          1378: single `@q[\]' for continuation.
        !          1379: 
        !          1380: Example one:
        !          1381: 
        !          1382: Using a modem, dial a UNIX host site.  Expect "login" (...gin), and if it
        !          1383: doesn't come, simply send a null string with a @q(~r).  (Some Unixes
        !          1384: require either an EOT or a BREAK instead of the null sequence, depending
        !          1385: on the particular site's "logger" program.)  After providing user id
        !          1386: and password, respond "x" to a question-mark prompt, expect the Bourne
        !          1387: shell "@q($)" prompt (and send return if it doesn't arrive).  Then cd to
        !          1388: directory kermit, and run the program called "wermit", entering the
        !          1389: interactive connect state after wermit is loaded.
        !          1390: @begin(example)
        !          1391: set modem-dialer ventel
        !          1392: set line /dev/tty77
        !          1393: set baud 1200
        !          1394: dial 9&5551212
        !          1395: script gin:--gin:--gin: smith ssword: mysecret ~q x $--$ \
        !          1396:  cd~skermit $ wermit
        !          1397: connect
        !          1398: @end(example)
        !          1399: 
        !          1400: Example two:
        !          1401: 
        !          1402: @index(TELENET)
        !          1403: Using a modem, dial the Telenet network.  This network expects three
        !          1404: returns with slight delays between them.  These are sent following
        !          1405: null expects.  The single return is here sent as a null string, with
        !          1406: a return appended by default.  Four returns are sent to be safe before
        !          1407: looking for the prompt.  Then the Telenet id and password are entered.
        !          1408: Then telenet is instructed to connect to a host site (c 12345).  The
        !          1409: host has a data switch, and to "which system" it responds "myhost".
        !          1410: This is followed by a TOPS-20 logon, and a request to load Kermit,
        !          1411: set even parity, and enter the server mode.  Files
        !          1412: are then exchanged.  The commands are in a take file; note the continuation
        !          1413: of the 'script' command onto several lines using the `@q[\]' terminator.
        !          1414: @begin(example)
        !          1415: set modem-dialer hayes
        !          1416: set line /dev/cul0
        !          1417: set baud 1200
        !          1418: dial 9,5551212
        !          1419: set parity even
        !          1420: script ~0 ~0 ~0 ~0 ~0 ~0 ~0 ~0 @@--@@--@@ id~saa001122 = 002211 @@ \
        !          1421:     c~s12345 ystem-c~s12345-ystem myhost @@ joe~ssecret @@ kermit \
        !          1422:     > set~sparity~seven > server
        !          1423: send some.stuff
        !          1424: get some.otherstuff
        !          1425: bye
        !          1426: quit
        !          1427: @end(example)
        !          1428: Since these commands may be executed totally in the background, they
        !          1429: can also be scheduled.  A typical shell script, which might be scheduled
        !          1430: by cron, would be as follows (csh used for this example):
        !          1431: 
        !          1432: @begin(example)
        !          1433: #
        !          1434: #keep trying to dial and log onto remote host and exchange files
        !          1435: #wait 10 minutes before retrying if dial or script fail.
        !          1436: # 
        !          1437: cd someplace
        !          1438: while ( 1 )
        !          1439:         kermit < /tonight.cmd >> nightly.log &
        !          1440:         if ( ! $status ) break
        !          1441:         sleep 600
        !          1442: end
        !          1443: @end(example)
        !          1444: File @q(tonight.cmd) might have two takes in it, for example, one to take
        !          1445: a file with the set modem, set line, set baud, dial, and script, and
        !          1446: a second take of a file with send/get commands for the remote server.
        !          1447: The last lines of @q(tonight.cmd) should be a bye and a quit.
        !          1448: 
        !          1449: @heading(The 'help' Command:)
        !          1450: 
        !          1451: @begin(example,leftmargin 0)
        !          1452: @r(Syntax:) help
        !          1453: @ @ @ @i(or): help @i(keyword)
        !          1454: @ @ @ @i(or): help {set, remote} @i(keyword)
        !          1455: @end(example)
        !          1456: 
        !          1457: Brief help messages or menus are always available at interactive command
        !          1458: level by typing a question mark at any point.  A slightly more verbose form
        !          1459: of help is available through the 'help' command.  The 'help' command with
        !          1460: no arguments prints a brief summary of how to enter commands and how to
        !          1461: get further help.  'help' may be followed by one of the top-level C-Kermit
        !          1462: command keywords, such as 'send', to request information about a command.
        !          1463: Commands such as 'set' and 'remote' have a further level of help.  Thus you
        !          1464: may type 'help', 'help set', or 'help set parity'; each will provide a
        !          1465: successively more detailed level of help.
        !          1466: 
        !          1467: 
        !          1468: @heading(The 'exit' and 'quit' Commands:)
        !          1469: 
        !          1470: These two commands are identical.  Both of them do the following:
        !          1471: 
        !          1472: @begin(itemize,spread 0)
        !          1473: Attempt to insure that the terminal is returned to normal.
        !          1474: 
        !          1475: Relinquish access to any communication line assigned via 'set line'.
        !          1476: 
        !          1477: Relinquish any uucp and multiuser locks on the communications line.
        !          1478: 
        !          1479: Hang up the modem, if the communications line supports data terminal ready.
        !          1480: 
        !          1481: Close any open log files.
        !          1482: @end(itemize)
        !          1483: After exit from C-Kermit, your default directory will be the same as when
        !          1484: you started the program.  The 'exit' command is issued implicitly whenever
        !          1485: C-Kermit halts normally, e.g. after a command line invocation, or after certain
        !          1486: kinds of interruptions.
        !          1487: 
        !          1488: @section(UUCP Lock Files)
        !          1489: 
        !          1490: Unix has no standard way of obtaining exclusive access to an external
        !          1491: communication line.  When you issue the 'set line' command to Unix Kermit, Unix
        !          1492: would normally grant you access to the line even if some other process is
        !          1493: making use of it.  The method adopted by most Unix systems to handle this
        !          1494: situation is the "UUCP lock file".  UUCP, the Unix-@|to-@|Unix Copy program,
        !          1495: creates a file in its directory (usually @q(/usr/spool/uucp), on some systems
        !          1496: @q</etc/locks>) with a name like @q(LCK..)@i(name), where @i(name) is the
        !          1497: device name, for instance @q(tty07).
        !          1498: 
        !          1499: Unix Kermit uses UUCP lock files in order to avoid conflicts with UUCP,
        !          1500: tip, or other programs that follow this convention.  Whenever you attempt
        !          1501: to access an external line using the 'set line' command or `@q(-l)' on the
        !          1502: command line, Kermit looks
        !          1503: in the UUCP directory for a lock file corresponding to that device.  For
        !          1504: instance, if you 'set line /dev/ttyi6' then Kermit looks for the file
        !          1505: @example(/usr/spool/uucp/LCK..ttyi6)
        !          1506: If it finds this file, it gives you an error message and a directory
        !          1507: listing of the file so that you can see who is using it, e.g.
        !          1508: @begin(example)
        !          1509: -r--r--r--  1 fdc        4 May  7 13:02 /usr/spool/uucp/LCK..ttyi6
        !          1510: @end(example)
        !          1511: In this case, you would look up user fdc to find out how soon the line
        !          1512: will become free.
        !          1513: 
        !          1514: This convention requires that the uucp directory be publicly readable
        !          1515: and writable.  If it is not, the program will issue an appropriate warning
        !          1516: message, but will allow you to proceed at your own risk (and the risk of
        !          1517: anyone else who might also be using the same line).
        !          1518: 
        !          1519: If no lock file is found, Unix Kermit will attempt create one, thus preventing
        !          1520: anyone who subsequently tries to run Kermit, UUCP, tip, or similar programs on
        !          1521: the same line from gaining access until you release the line.  If Kermit could
        !          1522: not create the lock file (for instance because the uucp directory is
        !          1523: write-@|protected), then you will receive a warning message but will be allowed
        !          1524: to proceed at your -- and everyone else's -- risk.  When Kermit terminates
        !          1525: normally, your lock file is removed.
        !          1526: 
        !          1527: Even when the lock directory is writable and readable, the locking mechanism
        !          1528: depends upon all users using the same name for the same device.  If a device
        !          1529: has more than one path associated with it, then a lock can be circumvented by
        !          1530: using an alias.
        !          1531: 
        !          1532: When a lock-@|creating program abruptly terminates, e.g. because it crashes or
        !          1533: is killed via shell command, the lock file remains in the uucp directory,
        !          1534: spuriously indicating that the line is in use.  If the lock file is owned by
        !          1535: yourself, you may remove it.  Otherwise, you'll have to get the owner or the
        !          1536: system manager to remove it, or else wait for a system task to do so; uucp
        !          1537: supports a function (uuclean) which removes these files after a predetermined
        !          1538: age -- uucp sites tend to run this function periodically via crontab.
        !          1539: 
        !          1540: Locking is not needed, or used, if communications occur over the user's
        !          1541: login terminal line (normally @q[/dev/tty]).
        !          1542: 
        !          1543: It may be seen that line locking is fraught with peril.  It is included in Unix
        !          1544: Kermit only because other Unix communication programs rely on it.  While it
        !          1545: is naturally desirable to assure exclusive access to a line, it is also
        !          1546: undesirable to refuse access to a vacant line only because of a spurious lock
        !          1547: file, or because the uucp directory is not appropriately protected.
        !          1548: 
        !          1549: @section(C-Kermit under Berkeley or System III/V Unix:)
        !          1550: 
        !          1551: C-Kermit may be interrupted at command level or during file transfer by typing
        !          1552: Control-C.  The program will perform its normal exit function, restoring the
        !          1553: terminal and releasing any lock.  If a protocol transaction was in progress, an
        !          1554: error packet will be sent to the opposite Kermit so that it can terminate
        !          1555: cleanly.
        !          1556: 
        !          1557: C-Kermit may be invoked in the background ("@q(&)" on shell commmand line).
        !          1558: If a background process is "killed", the user will have to manually
        !          1559: remove any lock file and may need to restore the modem.  This is because 
        !          1560: the kill signal (@q<kill(@i[x],9)>) cannot be trapped by Kermit.
        !          1561: 
        !          1562: During execution of a system command ('directory', 'cwd', or `@q(!)'), C-Kermit
        !          1563: can often be returned to command level by typing a single Control-C.  (With
        !          1564: System III/V, the usual interrupt function (often the DEL key) is replaced by
        !          1565: Control-C.) 
        !          1566: 
        !          1567: Under Berkeley Unix only: C-Kermit may also be interrupted by @q(^Z) to put the
        !          1568: process in the background.  In this case the terminal is not restored.  You
        !          1569: will have to type Control-J followed by "reset" followed by another Control-J
        !          1570: to get your terminal back to normal.
        !          1571: 
        !          1572: Control-C, Control-Z, and Control-@q(\) lose their normal functions during
        !          1573: terminal connection and also during file transfer when the controlling tty
        !          1574: line is being used for packet i/o.
        !          1575: 
        !          1576: If you are running C-Kermit in "quiet mode" in the foreground, then
        !          1577: interrupting the program with a console interrupt like Control-C will not
        !          1578: restore the terminal to normal conversational operation.  This is because
        !          1579: the system call to enable console interrupt traps will cause the program to
        !          1580: block if it's running in the background, and the primary reason for quiet
        !          1581: mode is to allow the program to run in the background without blocking, so
        !          1582: that you can do other work in the foreground.
        !          1583: 
        !          1584: If C-Kermit is run in the background ("&" on shell commmand line), then
        !          1585: the interrupt signal (Control-C) (and System III/V quit signal) are
        !          1586: ignored.  This prevents an interrupt signal intended for a foreground
        !          1587: job (say a compilation) from being trapped by a background Kermit session.
        !          1588: 
        !          1589: 
        !          1590: @section(C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1)
        !          1591: 
        !          1592: The DEC Professional 300 series are PDP-11/23 based personal computers.  Venix
        !          1593: Version 1 is a Unix v7 derivative.  It should not be confused with Venix
        !          1594: Version 2, which is based on ATT System V; these comments apply to Venix
        !          1595: Version 1 only.  C-Kermit runs in local mode on the Pro-3@i(xx) when invoked
        !          1596: from the console; the default device is @q(/dev/com1.dout).  When connected to
        !          1597: a remote system (using C-Kermit's 'connect' command), Pro/Venix itself (not
        !          1598: Kermit) provides VT52 terminal emulation.  Terminal operation at high speeds
        !          1599: (like 9600 baud) requires xon/xoff flow control, which unfortunately interferes
        !          1600: with applications such as the EMACS that use Control-Q and Control-S as
        !          1601: commands.
        !          1602: 
        !          1603: When logging in to a Pro-3xx (or any workstation) through the "back port",
        !          1604: it may be necessary to give the command "set line /dev/tty" in order to get
        !          1605: C-Kermit to function correctly in remote mode (on a system in which it 
        !          1606: normally expects to be operating in local mode).
        !          1607: 
        !          1608: @section(C-Kermit under VAX/VMS)
        !          1609: 
        !          1610: Version 4C of C-Kermit can be built using VAX-11 C to run under VMS.  Most
        !          1611: of the descriptions in this manual hold true, but it should be noted that
        !          1612: as of this writing the VMS support is not thoroughly tested, and no explicit
        !          1613: support exists for the various types of VMS files and their attributes.
        !          1614: 
        !          1615: The C-Kermit init file for VMS is called @q<KERMIT.INI>.
        !          1616: 
        !          1617: 
        !          1618: @section(C-Kermit on the Macintosh)
        !          1619: 
        !          1620: The "protocol kernel" of C-Kermit is also used by Columbia's Macintosh Kermit.
        !          1621: The user and system interface is entirely different, and is covered in a
        !          1622: separate document.
        !          1623: 
        !          1624: @section(C-Kermit Restrictions and Known Bugs)
        !          1625: 
        !          1626: @begin(enumerate)
        !          1627: @ux(Editing characters):
        !          1628: The program's interactive command interrupt, delete, and kill characters are
        !          1629: Control-C, Delete (or Backspace), and Control-U, respectively.  There is
        !          1630: currently no way to change them to suit your taste or match those used by
        !          1631: your shell, in case those are different.
        !          1632: 
        !          1633: @ux(High baud rates):
        !          1634: There's no way to specify baud rates higher than 9600 baud.  Most Unix
        !          1635: systems don't supply symbols for them (unless you use EXTA, EXTB), and even
        !          1636: when they do, the program has no way of knowing whether a specific port's
        !          1637: serial i/o controller supports those rates.
        !          1638: 
        !          1639: @ux(Modem controls):
        !          1640: If a connection is made over a communication line (rather than on the
        !          1641: controlling terminal line), and that line has modem controls, (e.g. data
        !          1642: terminal ready and carrier detection implementation), returning to the shell
        !          1643: level will disconnect the conversation.  In that case, one should use
        !          1644: interactive mode commands, and avoid use of piped shell-@|level operation
        !          1645: (also see 'set modem-dialer' and 'dial' commands.)
        !          1646: 
        !          1647: @ux(Login Scripts):  The present login scripts implementation follows
        !          1648: the Unix conventions of uucp's "@q(L.sys)" file, rather than the normal
        !          1649: Kermit "INPUT/@|OUTPUT" style, so there's no way to arbitrarily mingle
        !          1650: script output with Kermit commands (e.g. changing parity or duplex in
        !          1651: the middle of a script).
        !          1652: 
        !          1653: @begin(multiple)
        !          1654: @ux(Dial-out vs dial-in communications lines):
        !          1655: C-Kermit requires a dial-out or dedicated line for the "set line" or "-l"
        !          1656: options.  Most systems have some lines dedicated to dial-in, which they enable
        !          1657: "loggers" on, and some lines available for dial-out.  Where a line
        !          1658: must be shared between dial-in and dial-out, several options are
        !          1659: available (though they are, strictly speaking, outside the pervue of
        !          1660: C-Kermit).
        !          1661: 
        !          1662: A simple shell program can be used to change directionality of the line if
        !          1663: your Unix has the enable(8) and disable(8) commands.  In that case, the shell
        !          1664: program could "grep" a "who" to see if anybody is logged onto the desired
        !          1665: line; if not, it could "disable" the line.  The shell program will need to be
        !          1666: set-uID'ed to root.  The shell program can be called from kermit prior to a
        !          1667: dial command, e.g., "@q(! mydisable.shellprog)".  Prior to the final "quit"
        !          1668: from C-Kermit, another shell program could be executed to "enable" the line
        !          1669: again.  This program also needs to be set-uID'ed to root.
        !          1670: 
        !          1671: If your Unix lacks the enable(8) and disable(8) commands, another common
        !          1672: technique works if your system supports the @q(/etc/ttys) file.  A shell
        !          1673: program could call up an awk program to find the line in the file and set the
        !          1674: enable byte to 0 (to directly disable the line).  Likewise, it can be
        !          1675: reenabled by a counterpart at the end.  It may be necessary to pause for 60
        !          1676: seconds after modifying that file before the logger sees it and actually
        !          1677: disables the line.
        !          1678: @end(multiple)
        !          1679: 
        !          1680: @begin(multiple)
        !          1681: @ux(Using C-Kermit on Local Area Networks):
        !          1682: C-Kermit can successfully operate at speeds up to 9600 baud over LANs,
        !          1683: provided the network buffers are big enough to accommodate Kermit packets
        !          1684: (which are almost always less than 100 characters long).
        !          1685: 
        !          1686: When computers are connected to LAN's through asynchronous terminal
        !          1687: interfaces, then the connection should be configured to do XON/XOFF flow
        !          1688: control between the network interface and the computer, rather than passing
        !          1689: these signals through transparently.  This can help prevent Kermit from
        !          1690: overrunning the LAN's buffers if they are small (or if the LAN is congested),
        !          1691: and will can also prevent the LAN from overrunning a slow Kermit's buffers.
        !          1692: 
        !          1693: If the network hardware cannot accept 100 characters at a time, and flow
        !          1694: control cannot be done between the network and the computer, then Kermit's
        !          1695: "set send/receive packet-length" command can be used to shorten the packets.
        !          1696: @end(multiple)
        !          1697: 
        !          1698: @ux(Resetting terminal after abnormal termination or kill): When C-Kermit
        !          1699: terminates abnormally (say, for example, by a kill
        !          1700: command issued by the operator) the user may need to reset the terminal state.
        !          1701: If commands do not seem to be accepted at the shell prompt, try
        !          1702: Control-J "stty sane" Control-J (use "reset" on Berkeley Unix).
        !          1703: That should take the terminal out of "raw mode" if it was stuck there.
        !          1704: 
        !          1705: @ux(Remote host commands may time-out on lengthy activity):
        !          1706: Using "remote host" to instruct the C-Kermit server to invoke Unix
        !          1707: functions (like "make") that might take a long time to produce output can cause
        !          1708: timeout conditions.
        !          1709: 
        !          1710: @ux(XOFF deadlocks):
        !          1711: When connecting back to C-Kermit after a transaction, or after finishing
        !          1712: the server, it may be necessary to type a Control-Q to clear up an XOFF
        !          1713: deadlock.  There's not much the program can do about this...
        !          1714: 
        !          1715: @ux(PC/IX Login Scripts -- Unfound Bug):
        !          1716: Though login scripts appear to work properly on most processors, in the
        !          1717: case of the PC/XT with PC/IX, it appears that longer scripts
        !          1718: need to be broken up into shorter scripts (invoked sequentially from
        !          1719: the take file).  This is because the portion of the script handler
        !          1720: which checks if an operation timed out seems to leave the processor
        !          1721: in a strange state (i.e. hung).
        !          1722: @end(enumerate)
        !          1723: 
        !          1724: @section(How to Build C-Kermit for a Unix System)
        !          1725: 
        !          1726: The C-Kermit files, as distributed from Columbia, all begin with the prefix
        !          1727: "ck".  You should make a directory for these files and then cd to it.  A
        !          1728: makefile is provided to build C-Kermit for various Unix systems (there are
        !          1729: separate makefiles for VMS and the Macintosh).  As distributed, the makefile
        !          1730: has the name "@q(ckuker.mak)".  You should rename it to "@q(makefile)" and then
        !          1731: type "make xxx", where xxx is the symbol for your system, for instance "make
        !          1732: bsd" to make C-Kermit for 4.x BSD Unix.  The result will be a program called
        !          1733: "wermit".  You should test this to make sure it works; if it does, then you can
        !          1734: rename it to "kermit" and install it for general use.  See the makefile for a
        !          1735: list of the systems supported and the corresponding "make" arguments.
        !          1736: 
        !          1737: @section(Adapting C-Kermit to Other Systems)
        !          1738: 
        !          1739: C-Kermit is designed for portability.  The level of portability is indicated
        !          1740: in parentheses after the module name: "C" means any system that has a C
        !          1741: compiler that conforms to the description in "The C Programming Language" by
        !          1742: Kernighan & Ritchie (Prentice-Hall, 1978).  "Cf" is like "C", but also
        !          1743: requires "standard" features like printf and fprintf, argument passing via
        !          1744: argv/argc, and so on, as described in Kernighan & Ritchie.  "Unix" means the
        !          1745: module should be useful under any Unix implementation; it requires features
        !          1746: such as fork() and pipes.  Anything else means that the module is particular
        !          1747: to the indicated system.  C-Kermit file names are of the form:
        !          1748: 
        !          1749: @q[ck<@i(system)><@i(what)>.<@i(type)>]
        !          1750: 
        !          1751: where the part before the dot is no more than 6 characters long, the part
        !          1752: after the dot no more than 3 characters long, and:
        !          1753: 
        !          1754: @q[<@i(type)>] is the file type:
        !          1755: @begin(description,leftmargin +8,indent -6,spread 0)
        !          1756: c:@\C language source
        !          1757: 
        !          1758: h:@\Header file for C language source
        !          1759: 
        !          1760: w:@\Wart preprocessor source, converted by Wart (or Lex) to a C program
        !          1761: 
        !          1762: nr:@\Nroff/Troff text formatter source
        !          1763: 
        !          1764: mss:@\Scribe text formatter source
        !          1765: 
        !          1766: doc:@\Documentation
        !          1767: 
        !          1768: hlp:@\Help text
        !          1769: 
        !          1770: bld:@\Instructions for building the program
        !          1771: 
        !          1772: bwr:@\A "beware" file - list of known bugs
        !          1773: 
        !          1774: upd:@\Program update log
        !          1775: 
        !          1776: mak:@\Makefile
        !          1777: @end(description)
        !          1778: 
        !          1779: @q[<@i(system)>] is a single character to tell what system the file applies to:
        !          1780: @begin(description,leftmargin +8,indent -6,spread 0)
        !          1781: a:@\Descriptive material, documentation
        !          1782: 
        !          1783: c:@\All systems with C compilers
        !          1784: 
        !          1785: d:@\MS-DOS
        !          1786: 
        !          1787: m:@\Macintosh
        !          1788: 
        !          1789: u:@\Unix
        !          1790: 
        !          1791: v:@\VAX/VMS
        !          1792: 
        !          1793: w:@\Wart
        !          1794: @end(description)
        !          1795: 
        !          1796: @q[<@i(what)>] is mnemonic (up to 3 characters) for what's in the file:
        !          1797: @begin(description,leftmargin +8,indent -6,spread 0)
        !          1798: aaa:@\A "read-me" file, like this one
        !          1799: 
        !          1800: cmd:@\Command parsing
        !          1801: 
        !          1802: con:@\Connect command
        !          1803: 
        !          1804: deb:@\Debug/Transaction Log formats, Typedefs
        !          1805: 
        !          1806: dia:@\Modem/Dialer control
        !          1807: 
        !          1808: fio:@\System-depdendent File I/O
        !          1809: 
        !          1810: fns:@\Protocol support functions
        !          1811: 
        !          1812: fn2:@\More protocol support functions
        !          1813: 
        !          1814: ker:@\General C-Kermit definitions, information, documentation
        !          1815: 
        !          1816: mai:@\Main program
        !          1817: 
        !          1818: pro:@\Protocol
        !          1819: 
        !          1820: scr:@\Script command
        !          1821: 
        !          1822: tio:@\System-dependent terminal i/o & control and interrupt handing
        !          1823: 
        !          1824: usr:@\User interface
        !          1825: 
        !          1826: us2:@\More user interface
        !          1827: 
        !          1828: us3:@\Still more user interface
        !          1829: @end(description)
        !          1830: 
        !          1831: Examples:
        !          1832: 
        !          1833: @begin(description,spread 0)
        !          1834: @q(ckufio.c)@\File i/o for Unix
        !          1835: 
        !          1836: @q(ckmtio.c)@\Terminal i/o for Macintosh
        !          1837: 
        !          1838: @q(ckuker.mss)@\Scribe source for for Kermit User Guide chapter
        !          1839: 
        !          1840: @q(ckuker.nr)@\Nroff source file for Unix C-Kermit man page
        !          1841: @end(description)
        !          1842: 
        !          1843: The following material discusses each of the C-Kermit modules briefly.
        !          1844: @begin(description,leftmargin +4, indent -4)
        !          1845: @q<ckcmai.c, ckcker.h, ckcdeb.h (Cf)>:@\This is the main program.  It contains
        !          1846: declarations for global variables and 
        !          1847: a small amount of code to initialize some variables and invoke the command
        !          1848: parser.  In its distributed form, it assumes that command line arguments are
        !          1849: passed to it via argc and argv.  Since this portion of code is only several
        !          1850: lines long, it should be easy to replace for systems that have different
        !          1851: styles of user interaction.  The header files define symbols and macros used
        !          1852: by the various modules of C-Kermit.  @q(ckcdeb.h) is the only header file
        !          1853: that is included by all the C-Kermit modules, so it contains not only the
        !          1854: debug format definitions, but also any compiler-@|dependent typedefs.
        !          1855: 
        !          1856: @q<ckwart.c (Cf), ckcpro.w (C)>:@\The ckcpro module embodies the Kermit
        !          1857: protocol state table and the code to accomplish state switching.  It is written
        !          1858: in "wart", a language which may be regarded as a subset of the Unix "lex"
        !          1859: lexical analyzer generator.  Wart implements enough of lex to allow the ckprot
        !          1860: module to function.  Lex itself was not used because it is proprietary.
        !          1861: The protocol module @q(ckcpro.w) is read by wart, and a
        !          1862: system-@|independent C program is produced.  The syntax of a Wart program is
        !          1863: illustrated by @q(ckcpro.w), and is described in @q(ckwart.doc).
        !          1864: 
        !          1865: @q<ckcfns.c (C)>:@\The module contains all the Kermit protocol support
        !          1866: functions -- packet formation, encoding, decoding, block check calculation,
        !          1867: filename and data conversion, protocol parameter negotiation, and high-@|level
        !          1868: interaction with the communication line and file system.  To accommodate small
        !          1869: systems, this module has been split into two -- @q(ckcfns.c) and @q(ckcfn2.c).
        !          1870: 
        !          1871: @q(ckutio.c):@\This module contains the system-@|dependent primitives for
        !          1872: communication line i/o, timers, and interrupts for the various versions of
        !          1873: Unix.  Certain important variables are defined in this module, which determine
        !          1874: whether C-Kermit is by default remote or local, what the default communication
        !          1875: device is, and so forth.  The tio module maintains its own private database of
        !          1876: file descriptors and modes for the console terminal and the file transfer
        !          1877: communication line so that other modules (like ckcfns or the terminal connect
        !          1878: module) need not be concerned with them.  The variations among Unix
        !          1879: implementations with respect to terminal control and timers are accommodated
        !          1880: via conditional compilation.
        !          1881: 
        !          1882: @q(ckufio.c):@\This module contains system-dependent primitives for file i/o,
        !          1883: wildcard (meta character) expansion, file existence and access checking, and
        !          1884: system command execution for the various versions of Unix.  It maintains an
        !          1885: internal database of i/o "channels" (file pointers in this case) for the files
        !          1886: C-Kermit cares about -- the input file (the file which is being sent), the
        !          1887: output file (the file being received), the various logs, the screen, and so
        !          1888: forth.  This module varies little among Unix implementations except for the
        !          1889: wildcard expansion code; the directory structure of 4.2bsd Unix is different
        !          1890: from that of other Unix systems.  Again, variation among Unix systems is
        !          1891: selected using conditional compilation.
        !          1892: 
        !          1893: @begin(multiple)
        !          1894: @q(ckuusr.h, ckuusr.c, ckuus2.c, ckuus3.c) (Unix):@\This is the "user
        !          1895: interface" for C-Kermit.  It includes the command parser,
        !          1896: the screen output functions, and console input functions.  The command
        !          1897: parser comes in two pieces -- the traditional Unix command line decoder
        !          1898: (which is quite small and compact), and the interactive keyword parser
        !          1899: (which is rather large).  This module is fully replacable; its interface to
        !          1900: the other modules is very simple, and is explained at the beginning of the
        !          1901: source file.  The ckuusr module also includes code to execute any commands
        !          1902: directly which don't require the Kermit protocol -- local file management,
        !          1903: etc.  The module is rated "Unix" because it makes occasional use of the
        !          1904: @q[system()] function.
        !          1905: 
        !          1906: Note that while @q(ckuusr) is logically one module, it has been split up into
        !          1907: three C source files, plus a header file for the symbols they share in common.
        !          1908: This is to accommodate small systems that cannot handle big modules.
        !          1909: @q(ckuusr.c) has the command line and top-@|level interactive command parser;
        !          1910: @q(ckuus2.c) has the help command and strings; @q(ckuus3) has the set
        !          1911: and remote commands along with the logging, screen, and "interrupt" functions.
        !          1912: @end(multiple)
        !          1913: 
        !          1914: @q(ckucmd.c, ckucmd.h) (Cf):@\This is an interactive command parsing package
        !          1915: developed for C-Kermit.  It is written portably enough to be usable on any
        !          1916: system that has a C compiler that supports functions like printf.  The file
        !          1917: name parsing functions depend upon primitives defined in the fio module; if
        !          1918: these primitives cannot be supplied for a certain system, then the filename
        !          1919: parsing functions can be deleted, and the package will still be useful for
        !          1920: parsing keywords, numbers, arbitrary text strings, and so forth.  The style of
        !          1921: interaction is the same as that found on the DECSYSTEM-20.
        !          1922: 
        !          1923: @q(ckucon.c) (Unix):@\This is the connect module.  As supplied, it should
        !          1924: operate in any Unix environment, or any C-based environment that provides the
        !          1925: fork() function.  The module requires access to global variables that specify
        !          1926: line speed, parity, duplex, flow control, etc, and invokes functions from the
        !          1927: tio module to accomplish the desired settings and input/output, and functions
        !          1928: from the fio module to perform session logging.  No terminal emulation is
        !          1929: performed, but since standard i/o is used for the console, this may be piped
        !          1930: through a terminal emulation filter.  The ckucon function may be entirely
        !          1931: replaced, so long as the global settings are honored by its replacement.  PC
        !          1932: implementations of C-Kermit may require the ck?con module to do screen control,
        !          1933: escape sequence interpretation, etc, and may also wish to write special code to
        !          1934: get the best possible performance.
        !          1935: 
        !          1936: @q(ckudia.c) (Unix):@\This is the dialer module.  As supplied, it handles
        !          1937: Hayes, Ventel, Penril, Racal-Vadic, and several other modems.
        !          1938: 
        !          1939: @q(ckuscr.c) (Unix):@\This is the login script module.  As supplied, it handles
        !          1940: uucp-@|style scripts. 
        !          1941: @end(description)
        !          1942: 
        !          1943: Moving C-Kermit to a new system entails:
        !          1944: @begin(enumerate)
        !          1945: Creating a new @q<ck?tio> module in C, assembler, or whatever language is
        !          1946: most appropriate for system programming on the new system.  If the system
        !          1947: is Unix-like, then support may be added within the @q<ckutio.c> module itself
        !          1948: using conditional compilation.
        !          1949: 
        !          1950: Creating a new @q<ck?fio> module, as above.
        !          1951: 
        !          1952: If the system is not Unix-like, then a new @q<ckuusr> module may be required,
        !          1953: as well as a different invocation of it from @q<ckcmai>.
        !          1954: 
        !          1955: If the distributed connect module doesn't work or performs poorly, then
        !          1956: it may be replaced.  For instance, interrupt-@|driven i/o may be required,
        !          1957: especially if the system doesn't have forks.
        !          1958: @end(enumerate)
        !          1959: Those who favor a different style of user/program interaction from that
        !          1960: provided in @q(ckuusr.c) may replace the entire module, for instance with one
        !          1961: that provides a mouse/@|window/@|icon environment, a menu/@|function-@|key
        !          1962: environment, etc.
        !          1963: 
        !          1964: A few guidelines should be followed to maintain portability:
        !          1965: @begin(itemize)
        !          1966: Keep variable and function names to 6 characters or less.  Don't use
        !          1967: identifiers that are distinguished from one another only by alphabetic
        !          1968: case.
        !          1969: 
        !          1970: Keep modules small.  For instance, on a PDP-11 it is necessary to keep
        !          1971: the code segment of each module below 8K in order to allow the segment
        !          1972: mapping to occur which is necessary to run programs larger than 64K on a
        !          1973: non-@|I-and-D-@|space machine.
        !          1974: 
        !          1975: Keep strings short; many compilers have restrictive maximum lengths; 128
        !          1976: is the smallest maximum string constant length we've encountered so far.
        !          1977: 
        !          1978: Keep (f,s)printf formats short.  If these exceed some compiler dependent
        !          1979: maximum (say, 128) memory will be overwritten and the program will probably
        !          1980: core dump.
        !          1981: 
        !          1982: Do not introduce system dependencies into @q(ckcpro.w) or @q(ckcfn*.c).
        !          1983: 
        !          1984: If a variable is a character, declare as CHAR, not int, to prevent the
        !          1985: various sign extension and byte swapping foulups that occur when characters
        !          1986: are placed in integer variables.
        !          1987: 
        !          1988: Remember that different systems may use different length words for different
        !          1989: things.  Don't assume an integer can be used as a pointer, etc.
        !          1990: 
        !          1991: Don't declare static functions; these can wreak havoc with systems that do
        !          1992: segment mapping.
        !          1993: 
        !          1994: In conditional compilations expressions, use @q(#ifdef) and @q(#ifndef) and
        !          1995: not @q(#if), which is not supported by some compilers.  Also, don't use any
        !          1996: operators in these expressions; many compilers will fail to understand
        !          1997: expressions like @w<@q(#ifdef FOO | BAR)>.
        !          1998: 
        !          1999: Don't define multiline macros.
        !          2000: @End(Itemize)
        !          2001: In general, remember that this program will have to be compilable by old
        !          2002: compilers and runnable on small systems.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.