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