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