2 [1]The Columbia Crown The Kermit Project | Columbia University
3 612 West 115th Street, New York NY 10025 USA o [2]kermit@columbia.edu
5 [3]Home [4]Kermit 95 [5]C-Kermit [6]Scripts [7]Current [8]New [9]FAQ
8 C-Kermit Program Logic Manual
11 [11]The Kermit Project
13 As of: C-Kermit 9.0.300, 30 June 2011
14 Last update: Fri Jul 1 15:47:34 2011
16 IF YOU ARE READING A PLAIN-TEXT version of this document, note that
17 this file is a plain-text dump of a Web page. You can visit the
18 original (and possibly more up-to-date) Web page here:
20 [12]http://www.columbia.edu/kermit/ckcplm.html
26 3. [15]SOURCE CODE PORTABILITY AND STYLE
28 4.A. [17]Group A: Library Routines
29 4.B. [18]Group B: Kermit File Transfer
30 4.C. [19]Group C: Character-Set Conversion
31 4.D. [20]Group D: User Interface
32 4.E. [21]Group E: Platform-Dependent I/O
33 4.F. [22]Group F: Network Support
34 4.G. [23]Group G: Formatted Screen Support
35 4.H. [24]Group H: Pseudoterminal Support
36 4.I. [25]Group I: Security
37 I. [26]APPENDIX I: FILE PERMISSIONS
41 The Kermit Protocol is specified in the book [27]Kermit, A File
42 Transfer Protocol by Frank da Cruz, Digital Press / Butterworth
43 Heinemann, Newton, MA, USA (1987), 379 pages, ISBN 0-932376-88-6. It is
44 assumed the reader is familiar with the Kermit protocol specification.
46 This file describes the relationship among the modules and functions of
47 C-Kermit 5A and later, and other programming considerations. C-Kermit
48 is designed to be portable to any kind of computer that has a C
49 compiler. The source code is broken into many files that are grouped
50 according to their function, as shown in the [28]Contents.
52 C-Kermit has seen constant development since 1985. Throughout its
53 history, there has been a neverending tug-of-war among:
55 a. Functionality: adding new features, fixing bugs, improving
57 b. Adding support for new platforms or communication methods.
58 c. "Buzzword 1.0 compliance".
60 The latter category is the most frustrating, since it generally
61 involves massive changes just to keep the software doing what it did
62 before in some new setting: e.g. the K&R-to-ANSIC conversion (which had
63 to be done, of course, without breaking K&R); Y2K (not a big deal in
64 our case); the many and varied UNIX and other API "standards" with
67 Upon first glance at the source code, you will probably be appalled.
68 Many will be tempted to clean it up and modernize it. But as soon as
69 you do, you are sure to break something. Remember that above all else,
70 the C-Kermit code is portable to every Unix platform that ever existed,
71 going back Unix V7 (1979)*, and to several other completely different
72 and unrelated operating-system families such as DEC/HP VMS, DG AOS/VS,
73 and Stratus VOS, as well as to some Unix offshoots like OS-9 and Plan 9
74 (from Outer Space). Every release of Kermit has been checked on every
75 platform available -- the older the better! -- to make sure it still
76 builds and runs. Even today (2011), there are modern Unix systems that
77 have non-ANSI C compilers, foremost among them HP-UX (where an ANSI
78 optimizing C compiler is available, but only as an expensive add-on).
79 In a way, portability is the most important feature of C-Kermit and
80 every effort should be made to preserve it through future releases.
82 Voluminous edit histories are available going back to May 1985. The
83 first versions of C-Kermit were done on our [29]DEC VAX-11/750 with
84 Ultrix 1.0 and 2.0 (as well as departmental 750s with 4.2BSD**), DEC
85 Pro-380 workstations (desktop PDP-11s) running 2.9BSD, which was
86 [30]ported to the 380 by us. Later (1988 or so) on a big VAX 8650 with
87 Ultrix, which became an 8700 (these no doubt weighed several tons), and
88 finally a succession of non-DEC equipment: an Encore Multimax, 25 years
89 worth of Suns, and now Linux on [31]HP Blades. We also had our own VMS
90 development systems for some years. All this plus a generous assortment
91 of departmental and offsite guest accounts on a multitude of platforms.
92 Anyway, the edit histories:
94 [32]ckc04e.txt C-Kermit 4.2(030) May 1985 to 4E(072) Jan 1989.
95 [33]ckc04f.txt C-Kermit 4F(077) Arp 1989 to 4F(095) Aug 1989.
96 [34]ckc168.txt Updates to C-Kermit 5A(168) for VMS Nov 1991
97 [35]ckc178.txt C-Kermit 5A(100) Jul 1989 to 5A(178) Jan 1992
98 [36]ckc188.txt C-Kermit 5A(188) development, 1992
99 [37]ckc189.txt C-Kermit 5A(189) development, 1993
100 [38]ckc192.txt C-Kermit 6.0(192) development, 1998
101 [39]ckc197.txt C-Kermit 7.0(197) development, 2000
102 [40]ckc200.txt C-Kermit 8.0.200 development, 2001
103 [41]ckc211.txt C-Kermit 8.0.201 through 8.0.209 2001-2004
104 [42]ckc300.txt C-Kermit 9.0.300 June 2011
106 _________________________________
107 * C-Kermit 6.0 was the last one to be built on V7, as I recall. The
108 code should still be good for V7 but it probably has outgrown the
109 16-bit address space. In any case there is still a V7 makefile target
110 and a V7 path through the forest of #ifdefs in the code if anybody is
111 running V7 on an emulator and would like to try building C-Kermit.
112 There is no support for V6 but that is only because no V6 system was
113 ever found for development. Notice that some other 16-bit Unixes are
114 supported in the code, including 2.9BSD and Tandy Xenix 3.0, but have
115 not been tried since C-Kermit 6.0
117 ** C-Kermit 9.0.300 was built successfully on 4.2BSD about 25 years
120 [ [43]Contents ] [ [44]C-Kermit ] [ [45]Kermit Home ]
124 C-Kermit source files begin with the two letters "ck", for example
125 ckutio.c. Filenames are kept short (6.3) for maximum portability and
126 (obviously I hope) do not contain spaces or more than one period. The
127 third character in the name denotes something about the function group
128 and the expected level of portability:
130 a General descriptive material and documentation (text)
131 b BOO file encoders and decoders (obsolete)
132 c All platforms with C compilers (*)
133 d Data General AOS/VS
134 e Reserved for "ckermit" files, like ckermit.ini, ckermit2.txt
138 i Commodore Amiga (Intuition)
142 m Macintosh with Mac OS 1-9
144 o OS/2 and Microsoft Windows 9x/ME/NT/2000/XP/Vista/etc
145 p Plan 9 from Bell Labs
147 r DEC PDP-11 with RSTS/E (never used, open for reassignment)
148 s Atari ST GEMDOS (last supported in version 5A(189))
149 t DEC PDP-11 with RT-11 (never used, open for reassignment)
150 u Unix-based operating systems (*)
152 w Wart (Lex-like preprocessor, platform independent)
160 _ (underscore) Encryption modules
162 (*) In fact there is little distinction between the ckc*.* and cku*.*
163 categories. It would make more sense for all cku*.* modules to be
164 ckc*.* ones, except ckufio.c, ckutio.c, ckucon.c, ckucns.c, and
165 ckupty.c, which truly are specific to Unix. The rest (ckuus*.c,
166 ckucmd.c, etc) are quite portable.
168 One hint before proceeding: functions are scattered all over the ckc*.c
169 and cku*.c modules, where function size has begun to take precedence
170 over the desirability of grouping related functions together, the aim
171 being to keep any particular module from growing disproportionately
172 large. The easiest way (in UNIX) to find out in what source file a
173 given function is defined is like this (where the desired function is
178 This works because the coding convention has been to make function
179 names always start on the left margin with their contents indented, for
187 Also note the style for bracket placement. This allows bracket-matching
188 text editors (such as EMACS) to help you make sure you know which
189 opening bracket a closing bracket matches, particularly when the
190 opening bracket is above the visible screen, and it also makes it easy
191 to find the end of a function (search for '}' on the left margin).
193 Of course EMACS tags work nicely with this format too:
195 $ cd kermit-source-directory
198 Esc-X Visit-Tags-Table<CR><CR>
200 (but remember that the source file for ckcpro.c is [46]ckcpro.w!)
204 * Tabs should be set every 8 spaces, as on a VT100.
205 * All lines must no more than 79 characters wide after tab expansion.
206 * Note the distinction between physical tabs (ASCII 9) and the
207 indentation conventions, which are: 4 for block contents, 2 for
208 most other stuff (obviously this is not a portability issue, just
211 [ [47]Contents ] [ [48]C-Kermit ] [ [49]Kermit Home ]
213 3. SOURCE CODE PORTABILITY AND STYLE
215 C-Kermit was designed in 1985 as a platform-independent replacement for
216 the earlier Unix Kermit. C-Kermit's design was expected to promote
217 portability, and judging from the number of platforms to which it has
218 been adapted since then, the model is effective, if not ideal
219 (obviously if we had it all to do over, we'd change a few things). To
220 answer the oft-repeated question: "Why are there so many #ifdefs?",
223 * Many of them are related to feature selection and program size, and
224 so need to be there anyway.
225 * Those that treat compiler, library, platform, header-file, and
226 similar differences have built up over time as hundreds of people
227 all over the world adapted C-Kermit to their particular
228 environments and sent back their changes. There might be more
229 politically-correct ways to achieve portability, but this one is
230 natural and proven. The basic idea is to introduce changes that can
231 be selected by defining a symbol, which, if not defined, leaves the
232 program exactly as it was before the changes.
233 * Although it might be possible to "clean up" the "#ifdef mess",
234 nobody has accesss to all the hundreds of platforms served by the
235 #ifdefs to check the results.
237 And to answer the second-most-oft-repeated question: "Why don't you
238 just use GNU autoconfig / automake / autowhatever instead of
239 hard-coding all those #ifdefs?" Answers:
241 * The GNU tools are not available on all the platforms where C-Kermit
242 must be built and I wouldn't necessarily trust them if they were.
243 * Each platform is a moving target, so the tools themselves would
244 need to updated before Kermit could be updated.
245 * It would only add another layer of complexity to an already complex
247 * Conversion at this point would not be practical unless there was a
248 way to test the results on all the hundreds of platforms where
249 C-Kermit is supposed to build.
251 When writing code for the system-independent C-Kermit modules, please
252 stick to the following coding conventions to ensure portability to the
253 widest possible variety of C preprocessors, compilers, and linkers, as
254 well as certain network and/or email transports. The same holds true
255 for many of the "system dependent" modules too; particularly the Unix
256 ones, since they must be buildable by a wide variety of compilers and
257 linkers, new and old.
259 This list does not purport to be comprehensive, and although some items
260 on it might seem far-fetched, they would not be listed unless I had
261 encountered them somewhere, some time. I wish I had kept better records
262 so I could cite specific platforms and compilers.
264 * Try to keep variable and function names unique within 6 characters,
265 especially if they are used across modules, since 6 is the maximum
266 for some old linkers (actually, this goes back to TOPS-10 and -20
267 and other old DEC OS's where C-Kermit never ran anyway; a more
268 realistic maximum is probably somewhere between 8 and 16). We know
269 for certain that VAX C has a 31-character max because it complains
270 -- others might not complain, but just silently truncate, thus
271 folding two or more routines/variables into one.
272 * Keep preprocessor symbols unique within 8 characters; that's the
273 max for some preprocessors (sorry, I can't give a specific example,
274 but in 1988 or thereabouts, I had to change character-set symbols
275 like TC_LATIN1 and TC_LATIN2 to TC_1LATIN and TC_2LATIN because the
276 digits were being truncated and ignored on a platform where I
277 actually had to build C-Kermit 5A; unfortunately I didn't note
278 which platform -- maybe some early Ultrix version?)
279 * Don't create preprocessor symbols, or variable or function names,
280 that start with underscore (_). These are usually reserved for
281 internal use by the compiler and header files.
282 * Don't put #include directives inside functions or { blocks }.
283 * Don't use the #if or #elif preprocessor constructions, only use
284 #ifdef, #ifndef, #define, #undef, and #endif.
285 * Put tokens after #endif in comment brackets, e.g. #endif /* FOO */.
286 * Don't indent preprocessor statements - # must always be first char
288 * Don't put whitespace after # in preprocessor statements.
289 * Don't use #pragma, even within #ifdefs -- it makes some
290 preprocessors give up.
291 * Same goes for #module, #if, etc - #ifdefs do NOT protect them.
292 * Don't use logical operators in preprocessor constructions.
293 * Avoid #ifdefs inside argument list to function calls (I can't
294 remember why this one is here, but probably needn't be; we do this
296 * Always cast strlen() in expressions to int:
297 if ((int)strlen(foo) < x)...
298 * Avoid typedefs; they might be portable but they are very confusing
299 and there's no way to test for their presence or absence at compile
300 time. Use preprocessor symbols instead if possible; at least you
301 can test their definitions.
302 * Unsigned long is not portable; use a preprocessor symbol (Kermit
303 uses ULONG for this).
304 * Long long is not portable. If you really need it, be creative.
305 * Similarly 1234LL is not portable, nor almost any other constant
306 modifier other than L.
307 * Unsigned char is not portable, use CHAR (a preprocessor symbol
308 defined in the Kermit header files) and always take precautions
309 against character signage (more about this [50]below).
310 * Don't use initializers with automatic arrays or structs: it's not
312 * Don't use big automatic arrays or structs in functions that might
313 be called recursively; some platforms have fixed-size stacks (e.g.
314 Windows 9x: 256K) and recursive functions crash with stack
315 overflow. Even when there is not a compiler limitation, this causes
316 memory to be consumed without bound, and can end up filling swap
318 * Don't assume that struct assignment performs a copy, or that it
320 * Don't use sizeof to get the size of an array; someone might come
321 along later and and change it from static to malloc'd. Always use a
322 symbol to refer to the array's size.
323 * Don't put prototypes for static functions into header files that
324 are used by modules that don't contain that function; the link step
325 can fail with unresolved references (e.g. on AOS/VS).
326 * Avoid the construction *++p (the order of evaluation varies; it
327 shouldn't but at least one compiler had a bug that made me include
329 * Don't use triple assignments, like a = b = c = 0; (or quadruple,
330 etc). Some compilers generate bad code for these, or crash, etc
331 (some version of DEC C as I recall).
332 * Some compilers don't allow structure members to have the same names
333 as other identifiers. Try to give structure members unique names.
334 * Don't assume anything about order of evaluation in boolean
335 expressions, or that they will stop early if a required condition
337 if (i > 0 && p[i-1] == blah)
339 can still dump core if i == 0 (hopefully this is not true of any
340 modern compiler, but I would not have said this if it did not
341 actually happen somewhere).
342 * Don't have a switch() statement with no cases (e.g. because of
343 #ifdefs); this is a fatal error in some compilers.
344 * Don't put lots of code in a switch case; move it out to a separate
345 function; some compilers run out of memory when presented with a
346 huge switch() statement -- it's not the number of cases that
347 matters; it's the overall amount of code.
348 * Some compilers might also limit the number of switch() cases, e.g.
350 * Don't put anything between "switch() {" and "case:" -- switch
351 blocks are not like other blocks.
352 * Don't jump into or out of switches.
353 * Don't make character-string constants longer than about 250 bytes.
354 Longer strings should be broken up into arrays of strings.
355 * Don't write into character-string constants (obviously). Even when
356 you know you are not writing past the end; the compiler or linker
357 might have put them into read-only and/or shared memory, and/or
358 coalesced multiple equal constants so if you change one you change
360 * Don't depend on '\r' being carriage return.
361 * Don't depend on '\n' being linefeed or for that matter any SINGLE
363 * Don't depend on '\r' and '\n' being different (e.g. as separate
365 * In other words, don't use \n or \r to stand for specific
366 characters; use \012 and \015 instead.
367 * Don't code for "buzzword 1.0 compliance", unless "buzzword" is K&R
368 and "1.0" is the first edition.
369 * Don't use or depend on anything_t (size_t, pid_t, etc), except
370 time_t, without #ifdef protection (time_t is the only one I've
371 found that is accepted everywhere). This is a tough one because the
372 same function might require (say) a size_t arg on one platform,
373 whereas size_t is unheard of on another; or worse, it might require
374 a totally different data type, like int or long or some other
375 typedef'd thing. It has often proved necessary to define a symbol
376 to stand for the type of a particular argument to a particular
377 library or system function to get around this problem.
378 * Don't use or depend on internationalization ("i18n") features,
379 wchar_t, locales, etc, in portable code; they are not portable.
380 Anyway, locales are not the right model for Kermit's
381 multi-character-set support. Kermit does all character-set
382 conversion itself and does not use any external libraries or
384 * In particular, don't use any library functions that deal with wide
385 characters or Unicode in any form. These are not only nonportable,
386 but a constantly shifting target (e.g. the ones in glibc).
387 * Don't make any assumption about signal handler type. It can be
388 void, int, long, or anything else. Always declare signal handlers
389 as SIGTYP (see definition in ckcdeb.h and augment it if necessary)
390 and always use SIGRETURN at exit points from signal handlers.
391 * Signals should always be re-armed to be used again (this barely
392 scratches the surface -- the differences between BSD/V7 and System
393 V and POSIX signal handling are numerous, and some platforms do not
394 even support signals, alarms, or longjmps correctly or at all --
395 avoid all of this if you can).
396 * On the other hand, don't assume that signals are disarmed after
397 being raised. In some platforms you have to re-arm them, in others
399 * Don't call malloc() and friends from a signal handler; don't do
400 anything but setting integer global variables in a signal handler.
401 * malloc() does not initialize allocated memory -- it never said it
402 did. Don't expect it to be all 0's.
403 * Did You Know: malloc() can succeed and the program can still dump
404 core later when it attempts to use the malloc'd memory? (This
405 happens when allocation is deferred until use and swap space is
407 * memset(), memmove(), and memcpy() are not portable, don't use them
408 without protecting them in ifdefs (we have USE_MEMCPY for this).
409 bzero()/bcopy() too, except we're guaranteed to have
410 bzero()/bcopy() when using the sockets library (not really). See
411 examples in the source.
412 * Don't assume that strncpy() stops on the first null byte -- most
413 versions always copy the number of bytes given in arg 3, padding
414 out with 0's and overwriting whatever was there before. Use
415 C-Kermit ckstrncpy() if you want predictable non-padding behavior,
416 guaranteed NUL-termination, and a useful return code.
417 * DID YOU KNOW.. that some versions of inet_blah() routines return IP
418 addresses in network byte order, while others return them local
419 machine byte order? So passing them to ntohs() or whatever is not
420 always the right thing to do.
421 * Don't use ANSI-format function declarations without #ifdef
422 CK_ANSIC, and always provide an #else for the non-ANSI case.
423 * Use the Kermit _PROTOTYP() macro for declaring function prototypes;
424 it works in both the ANSI and non-ANSI cases.
425 * Don't depend on any other ANSI preprocessor features like "pasting"
426 -- they are often missing or nonoperational.
427 * Don't assume any C++ syntax or semantics.
428 * Don't use // as a comment introducer. C is not C++.
429 * Don't declare a string as "char foo[]" in one module and "extern
430 char * foo" in another, or vice-versa: this causes core dumps.
431 * With compiler makers falling all over themselves trying to outdo
432 each other in ANSI strictness, it has become increasingly necessary
433 to cast EVERYTHING. Especially char vs unsigned char. We need to
434 use unsigned chars if we want to deal with 8-bit character sets,
435 but most character- and string-oriented APIs want (signed) char
436 arguments, so explicit casts are necessary. It would be nice if
437 every compiler had a -funsigned-char option (as gcc does), but they
439 * a[x], where x is an unsigned char, can produce a wild memory
440 reference if x, when promoted to an int, becomes negative. Cast it
441 to (unsigned), even though it ALREADY IS unsigned.
442 * Be careful how you declare functions that have char or long
443 arguments; for ANSI compilers you MUST use ANSI declarations to
444 avoid promotion problems, but you can't use ANSI declarations with
445 non-ANSI compilers. Thus declarations of such functions must be
446 hideously entwined in #ifdefs. Example:
447 int /* Put character in server command buffer */
452 #endif /* CK_ANSIC */
455 *srvptr = '\0'; /* Make sure buffer is null-terminated */
459 * Be careful how you return characters from functions that return int
460 values -- "getc-like functions" -- in the ANSI world. Unless you
461 explicitly cast the return value to (unsigned), it is likely to be
462 "promoted" to an int and have its sign extended.
463 * At least one compiler (the one on DEC OSF/1 1.3) treats "/*" and
464 "*/" within string constants as comment begin and end. No amount of
465 #ifdefs will get around this one. You simply can't put these
466 sequences in a string constant, e.g. "/usr/local/doc/*.*".
467 * Avoid putting multiple macro references on a single line, e.g.:
468 putchar(BS); putchar(SP); putchar(BS)
470 This overflows the CPP output buffer of more than a few C preprocessors
471 (this happened, for example, with SunOS 4.1 cc, which evidently has a
472 1K macro expansion buffer).
474 C-Kermit needs constant adjustment to new OS and compiler releases.
475 Every new OS release shuffles header files or their contents, or
476 prototypes, or data types, or levels of ANSI strictness, etc. Every
477 time you make an adjustment to remove a new compilation error, BE VERY
478 CAREFUL to #ifdef it on a symbol unique to the new configuration so
479 that the previous configuration (and all other configurations on all
480 other platforms) remain as before.
482 Assume nothing. Don't assume header files are where they are supposed
483 to be, that they contain what you think they contain, that they define
484 specific symbols to have certain values -- or define them at all! Don't
485 assume system header files protect themselves against multiple
486 inclusion. Don't assume that particular system or library calls are
487 available, or that the arguments are what you think they are -- order,
488 data type, passed by reference vs value, etc. Be conservative when
489 attempting to write portable code. Avoid all advanced features.
491 If you see something that does not make sense, don't assume it's a
492 mistake -- it might be there for a reason, and changing it or removing
493 is likely to cause compilation, linking, or runtime failures sometime,
494 somewhere. Some huge percentage of the code, especially in the
495 platform-dependent modules, is workarounds for compiler, linker, or API
498 But finally... feel free to violate any or all of these rules in
499 platform-specific modules for environments in which the rules are
500 certain not to apply. For example, in VMS-specific code, it is OK to
501 use #if, because VAX C, DEC C, and VMS GCC all support it.
503 [ [51]Contents ] [ [52]C-Kermit ] [ [53]Kermit Home ]
507 The C language and standard C library are notoriously inadequate and
508 unsafe. Strings are arrays of characters, usually referenced through
509 pointers. There is no native string datatype. Buffers are fixed size,
510 and C provides no runtime bounds checking, thus allowing overwriting of
511 other data or even program code. With the popularization of the
512 Internet, the "buffer exploit" has become a preferred method for
513 hackers to hijack privileged programs; long data strings are fed to a
514 program in hopes that it uses unsafe C library calls such as strcpy()
515 or sprintf() to copy strings into automatic arrays, thus overwriting
516 the call stack, and therefore the routine's return address. When such a
517 hole is discovered, a "string" can be constructed that contains machine
518 code to hijack the program's privileges and penetrate the system.
520 This problem is partially addressed by the strn...() routines, which
521 should always be used in preference to their str...() equivalents
522 (except when the copy operation has already been prechecked, or there
523 is a good reason for not using them, e.g. the sometimes undesirable
524 side effect of strncpy() zeroing the remainder of the buffer). The most
525 gaping whole, however, is sprintf(), which performs no length checking
526 on its destination buffer, and is not easy to replace. Although
527 snprintf() routines are starting to appear, they are not yet
528 widespread, and certainly not universal, nor are they especially
529 portable, or even full-featured.
531 For these reasons, we have started to build up our own little library
532 of C Library replacements, ckclib.[ch]. These are safe and highly
533 portable primitives for memory management and string manipulation, such
537 Like strncpy but returns a useful value, doesn't zero buffer.
546 Returns character as string
549 Used with ck?to?() as a safe sprintf() replacement for up to 4
553 Like ckmakmsg() but accepts up to 12 items
555 More about library functions in [54]Section 4.A.
557 [ [55]Contents ] [ [56]C-Kermit ] [ [57]Kermit Home ]
559 3.2. The "char" vs "unsigned char" Dilemma
561 This is one of the most aggravating and vexing characteristics of the C
562 language. By design, chars (and char *'s) are SIGNED. But in the modern
563 era, however, we need to process characters that can have (or include)
564 8-bit values, as in the ISO Latin-1, IBM CP 850, or UTF-8 character
565 sets, so this data must be treated as unsigned. But some C compilers
566 (such as those based on the Bell UNIX V7 compiler) do not support
567 "unsigned char" as a data type. Therefore we have the macro or typedef
568 CHAR, which we use when we need chars to be unsigned, but which,
569 unfortunately, resolves itself to "char" on those compilers that don't
570 support "unsigned char". AND SO... We have to do a lot of fiddling at
571 runtime to avoid sign extension and so forth.
573 Some modern compilers (e.g. IBM, DEC, Microsoft) have options that say
574 "make all chars be unsigned" (e.g. GCC "-funsigned-char") and we use
575 them when they are available. Other compilers don't have this option,
576 and at the same time, are becoming increasingly strict about type
577 mismatches, and spew out torrents of warnings when we use a CHAR where
578 a char is expected, or vice versa. We fix these one by one using casts,
579 and the code becomes increasingly ugly. But there remains a serious
580 problem, namely that certain library and kernel functions have
581 arguments that are declared as signed chars (or pointers to them),
582 whereas our character data is unsigned. Fine, we can can use casts here
583 too -- but who knows what happens inside these routines.
585 [ [58]Contents ] [ [59]C-Kermit ] [ [60]Kermit Home ]
589 When C-Kermit is on the far end of a connection, it is said to be in
590 remote mode. When C-Kermit has made a connection to another computer,
591 it is in local mode. (If C-Kermit is "in the middle" of a multihop
592 connection, it is still in local mode.)
594 On another axis, C-Kermit can be in any of several major states:
597 Reading and writing from the job's controlling terminal or
598 "console". In this mode, all i/o is handled by the Group E
599 conxxx() (console i/o) routines.
602 Reading and writing from the communications device. In this
603 mode, all i/o is handled by the Group E ttxxx() (terminal i/o)
607 Reading from the keyboard with conxxx() routines and writing to
608 the communications device with ttxxx() routines AND vice-versa.
610 When in local mode, the console and communications device are distinct.
611 During file transfer, Kermit may put up a file-transfer display on the
612 console and sample the console for interruption signals.
614 When in remote mode, the console and communications device are the
615 same, and therefore there can be no file-transfer display on the
616 console or interruptions from it (except for "in-band" interruptions
619 [ [61]Contents ] [ [62]C-Kermit ] [ [63]Kermit Home ]
621 4.A. Group A: Library Functions
623 Library functions, strictly portable, can be used by all modules on all
624 platforms: [64]ckclib.h, [65]ckclib.c.
626 (To be filled in... For now, see [66]Section 3.1 and the comments in
629 [ [67]Contents ] [ [68]C-Kermit ] [ [69]Kermit Home ]
631 4.B. Group B: Kermit File Transfer
633 The Kermit protocol kernel. These files, whose names start with "ckc
634 are supposed to be totally portable C, and are expected to compile
635 correctly on any platform with any C compiler. "Portable" does not mean
636 the same as as "ANSI" -- these modules must compile on 10- and 20-year
637 old computers, with C preprocessors, compilers, and/or linkers that
638 have all sorts of restrictions. The Group B modules do not include any
639 header files other than those that come with Kermit itself. They do not
640 contain any library calls except from the standard C library (e.g.
641 printf()). They most certainly do not contain any system calls. Files:
644 For use by C compilers that don't allow -D on the command line.
647 ASCII character symbol definitions.
650 System-independent signal-handling definitions and prototypes.
653 Originally, debugging definitions. Now this file also contains
654 all definitions and prototypes that are shared by all modules in
658 Kermit protocol symbol definitions.
661 Character-set-related symbol definitions (see next section).
664 The main program. This module contains the declarations of all
665 the protocol-related global variables that are shared among the
669 The protocol module itself, written in "wart", a lex-like
670 preprocessor that is distributed with Kermit under the name
673 [78]ckcfns.c, [79]ckcfn2.c, [80]ckcfn3.c
674 The protocol support functions used by the protocol module.
676 [81]Group B modules may call upon functions from [82]Group E, but not
677 from [83]Group D modules (with the single exception that the main
678 program invokes the user interface, which is in Group D). (This last
679 assertion is really only a conjecture.)
681 [ [84]Contents ] [ [85]C-Kermit ] [ [86]Kermit Home ]
683 4.C. Group C: Character-Set Conversion
685 Character set translation tables and functions. Used by the [87]Group
686 B, protocol modules, but may be specific to different computers. (So
687 far, all character character sets supported by C-Kermit are supported
688 in [88]ckuxla.c and [89]ckuxla.h, including Macintosh and IBM character
689 sets). These modules should be completely portable, and not rely on any
690 kind of system or library services.
693 Character-set definitions usable by all versions of C-Kermit.
696 Character-set definitions for computer "?", e.g. [91]ckuxla.h
697 for UNIX, [92]ckmxla.h for Macintosh.
700 Character-set translation tables and functions for computer "?",
701 For example, CKUXLA.C for UNIX, CKMXLA.C for Macintosh. So far,
702 these are the only two such modules. The UNIX module is used for
703 all versions of C-Kermit except the Macintosh version.
711 Here's how to add a new file character set in the original (non-Unicode
712 modules). Assuming it is based on the Roman (Latin) alphabet. Let's
713 call it "Barbarian". First, in ck?xla.h, add a definition for FC_BARBA
714 (8 chars maximum length) and increase MAXFCSETS by 1. Then, in
717 * Add a barbarian entry into the fcsinfo array.
718 * Add a "barbarian" entry to file character set keyword table,
720 * Add a "barbarian" entry to terminal character set keyword table,
722 * Add a translation table from Latin-1 to barbarian: yl1ba[].
723 * Add a translation table from barbarian to Latin-1: ybal1[].
724 * Add a translation function from Barbarian to ASCII: xbaas().
725 * Add a translation function from Barbarian to Latin-1: xbal1().
726 * Add a translation function from Latin-1 to Barbarian: xl1ba().
727 * etc etc for each transfer character set...
728 * Add translation function pointers to the xls and xlr tables.
730 Other translations involving Barbarian (e.g. from Barbarian to
731 Latin-Cyrillic) are performed through these tables and functions. See
732 ckuxla.h and ckuxla.c for extensive examples.
734 To add a new Transfer Character Set, e.g. Latin Alphabet 9 (for the
735 Euro symbol), again in the "old" character-set modules:
739 + Add a TC_xxxx definition and increase MAXTCSETS accordingly.
741 In ck?xla.h (since any transfer charset is also a file charset):
743 + Add an FC_xxxx definition and increase MAXFCSETS accordingly.
747 + Add a tcsinfo[] entry.
748 + Make a tcstab[] keyword table entry.
749 + Make an fcsinfo[] table entry.
750 + Make an fcstab[] keyword table entry.
751 + Make a tcstab[] keyword table entry.
752 + If necessary, make a langinfo[] table entry.
753 + Make entries in the function pointer arrays.
754 + Provide any needed functions.
756 As of C-Kermit 7.0, character sets are also handled in parallel by the
757 new (and very large) Unicode module, ckcuni.[ch]. Eventually we should
758 phase out the old way, described just above, and operate entirely in
759 (and through) Unicode. The advantages are many. The disadvantages are
760 size and performance. To add a character to the Unicode modules:
764 + (To be filled in...)
768 + (To be filled in...)
770 [ [96]Contents ] [ [97]C-Kermit ] [ [98]Kermit Home ]
772 4.D. Group D: User Interface
774 This is the code that communicates with the user, gets her commands,
775 informs her of the results. It may be command-line oriented,
776 interactive prompting dialog, menus and arrow keys, windows and mice,
777 speech recognition, telepathy, etc. The one provided is command-and
778 prompt, with the ability to read commands from various sources: the
779 console keyboard, a file, or a macro definition. The user interface has
780 three major functions:
782 1. Sets the parameters for the file transfer and then starts it. This
783 is done by setting certain (many) global variables, such as the
784 protocol machine start state, the file specification, file type,
785 communication parameters, packet length, window size, character
787 2. Displays messages on the user's screen during the file transfer,
788 using the screen() function, which is called by the group-1
790 3. Executes any commands directly that do not require Kermit protocol,
791 such as the CONNECT command, local file management commands,
792 parameter-setting commands, FTP client commands, etc.
794 If you plan to embed the [99]Group B, files into a program with a
795 different user interface, your interface must supply an appropriate
796 screen() function, plus a couple related ones like chkint() and
797 intmsg() for handling keyboard (or mouse, etc) interruptions during
798 file transfer. The best way to find out about this is to link all the
799 C-Kermit modules together except the ckuu*.o and ckucon.o modules, and
800 see which missing symbols turn up.
802 C-Kermit's character-oriented user interface (as opposed to the
803 Macintosh version's graphical user interface) consists of the following
804 modules. C-Kermit can be built with an interactive command parser, a
805 command-line-option-only parser, a graphical user interface, or any
806 combination, and it can even be built with no user interface at all (in
807 which case it runs as a remote-mode Kermit server).
811 The command parsing primitives used by the interactive command
812 parser to parse keywords, numbers, filenames, etc, and to give
813 help, complete fields, supply defaults, allow abbreviations and
814 editing, etc. This package is totally independent of Kermit, but
815 does depend on the [102]Group E functions.
818 Definitions of symbols used in Kermit's commands.
821 Kermit's interactive command parser, including the script
822 programming language: [104]ckuusr.c (includes top-level keyword
823 tables); [105]ckuus2.c (HELP command text); [106]ckuus3.c (most
824 of the SET command); [107]ckuus4.c (includes variables and
825 functions); ckuus[567].c (miscellaneous);
828 The command-line-option parser.
831 User interface functions common to both the interactive and
832 command-line parsers.
835 Version heralds for different implementations.
838 The (old, uucp-like) SCRIPT command
841 The DIAL command. Includes specific knowledge of many types of
844 Note that none of the above files is actually Unix-specific. Over time
845 they have proven to be portable among all platforms where C-Kermit is
846 built: Unix, VMS, AOS/VS, Amiga, OS-9, VOS, etc etc. Thus the third
847 letter should more properly be "c", but changing it would be too
851 The CONNECT command. Terminal connection, and in some cases
852 (Macintosh, Windows) also terminal emulation. NOTE: As of
853 C-Kermit 7.0, there are two different CONNECT modules for UNIX:
854 [113]ckucon.c -- the traditional, portable, fork()-based version
855 -- and [114]ckucns.c, a new version that uses select() rather
856 than forks so it can handle encryption. ckucns.c is the
857 preferred version for Unix; ckucon.c is not likely to keep pace
858 with it in terms of upgrades, etc. However, since select() is
859 not portable to every platform, ckucon.c will be kept
860 indefinitely for those platforms that can't use ckucns.c. NOTE:
861 SunLink X.25 support is available only in ckucon.c.
864 Modules having to do with authentication and encryption. Since
865 the relaxation of USA export laws, they are included with the
866 general source-code distribution. Secure C-Kermit binaries can
867 be built using special targets in the standard makefile.
868 However, secure prebuilt binaries may not be distributed.
870 For other implementations, the files may, and probably do, have
871 different names. For example, the Macintosh graphical user interface
872 filenames start with "ckm". Kermit 95 uses the ckucmd and ckuus*
873 modules, but has its own CONNECT command modules. And so on.
875 Here is a brief description of C-Kermit's "user interface interface",
876 from ckuusr.c. It is nowhere near complete; in particular, hundreds of
877 global variables are shared among the many modules. These should, some
878 day, be collected into classes or structures that can be passed around
879 as needed; not only for purity's sake, but also to allow for multiple
880 simultaneous communication sessions and or user interfaces. Our list of
881 things to do is endless, and reorganizing the source is almost always
884 The ckuus*.c modules (like many of the ckc*.c modules) depend on the
885 existence of C library features like fopen, fgets, feof, (f)printf,
886 argv/argc, etc. Other functions that are likely to vary among operating
887 systems -- like setting terminal modes or interrupts -- are invoked via
888 calls to functions that are defined in the [115]Group E
889 platform-dependent modules, ck?[ft]io.c. The command line parser
890 processes any arguments found on the command line, as passed to main()
891 via argv/argc. The interactive parser uses the facilities of the cmd
892 package (developed for this program, but, in theory, usable by any
893 program). Any command parser may be substituted for this one. The only
894 requirements for the Kermit command parser are these:
896 1. Set parameters via global variables like duplex, speed, ttname,
897 etc. See [116]ckcmai.c for the declarations and descriptions of
899 2. If a command can be executed without the use of Kermit protocol,
900 then execute the command directly and set the sstate (start state)
901 variable to 0. Examples include SET commands, local directory
902 listings, the CONNECT command.
903 3. If a command requires the Kermit protocol, set the following
906 'x' (enter server mode) (none)
907 'r' (send a 'get' command) cmarg, cmarg2
908 'v' (enter receive mode) cmarg2
909 'g' (send a generic command) cmarg
910 's' (send files) nfils, cmarg & cmarg2 OR cmlist
911 'c' (send a remote host command) cmarg
914 cmlist is an array of pointers to strings.
915 cmarg, cmarg2 are pointers to strings.
916 nfils is an integer (hmmm, probably should be an unsigned long).
919 A filename string (possibly wild), or:
920 a pointer to a prefabricated generic command string, or:
921 a pointer to a host command string.
924 The name to send a single file under, or:
925 the name under which to store an incoming file; must not
927 If it's the name for receiving, a null value means to
928 store the file under the name it arrives with.
931 A list of nonwild filenames, such as passed via argv.
933 nfils is an integer, interpreted as follows:
934 -1: filespec (possibly wild) in cmarg, must be expanded
936 0: send from stdin (standard input).
937 >0: number of files to send, from cmlist.
939 The screen() function is used to update the screen during file
940 transfer. The tlog() function writes to a transaction log (if TLOG is
941 defined). The debug() function writes to a debugging log (if DEBUG is
942 defined). The intmsg() and chkint() functions provide the user i/o for
943 interrupting file transfers.
945 [ [117]Contents ] [ [118]C-Kermit ] [ [119]Kermit Home ]
947 4.E. Group E: Platform-Dependent I/O
949 Platform-dependent function definitions. All the Kermit modules,
950 including the command package, call upon these functions, which are
951 designed to provide system-independent primitives for controlling and
952 manipulating devices and files. For Unix, these functions are defined
953 in the files [120]ckufio.c (files), [121]ckutio.c (communications), and
954 [122]ckusig.c (signal handling).
956 For VMS, the files are [123]ckvfio.c, ckvtio.c, and [124]ckusig.c (VMS
957 can use the same signal handling routines as Unix). It doesn't really
958 matter what the files are called, except for Kermit distribution
959 purposes (grouping related files together alphabetically), only that
960 each function is provided with the name indicated, observes the same
961 calling and return conventions, and has the same type.
963 The Group E modules contain both functions and global variables that
964 are accesssed by modules in the other groups. These are now described.
966 (By the way, I got this list by linking all the C-Kermit modules
967 together except ckutio and ckufio. These are the symbols that ld
968 reported as undefined. But that was a long time ago, probably circa
971 4.E.1. Global Variables
974 Pointer to string containing command for deleting files.
975 Example: char *DELCMD = "rm -f "; (UNIX)
976 Example: char *DELCMD = "delete "; (VMS)
977 Note trailing space. Filename is concatenated to end of this
978 string. NOTE: DELCMD is used only in versions that do not
979 provide their own built-in DELETE command.
982 Pointer to string containing command for listing files when a
984 Example: char *DIRCMD = "/bin/ls -l "; (UNIX)
985 Example: char *DIRCMD = "directory "; (VMS)
986 Note trailing space. Filename is concatenated to end of this
987 string. NOTE: DIRCMD is used only in versions that do not
988 provide their own built-in DIRECTORY command.
991 Pointer to string containing command for listing files when a
992 filespec is not given. (currently not used, handled in another
994 Example: char *DIRCMD2 = "/bin/ls -ld *";
995 NOTE: DIRCMD2 is used only in versions that do not provide their
996 own built-in DIRECTORY command.
999 Pointer to string containing command to display current
1001 Example: char *PWDCMD = "pwd ";
1002 NOTE: PWDCMD is used only in versions that do not provide their
1003 own built-in PWD command.
1006 Pointer to command to display free disk space in current
1008 Example: char *SPACMD = "df .";
1009 NOTE: SPACMD is used only in versions that do not provide their
1010 own built-in SPACE command.
1013 Pointer to command to display free disk space in another
1015 Example: char *SPACM2 = "df ";
1016 Note trailing space. Device or directory name is added to this
1017 string. NOTE: SPACMD2 is used only in versions that do not
1018 provide their own built-in SPACE command.
1021 Pointer to command for displaying the contents of a file.
1022 Example: char *TYPCMD = "cat ";
1023 Note trailing space. Device or directory name is added to this
1024 string. NOTE: TYPCMD is used only in versions that do not
1025 provide their own built-in TYPE command.
1028 Pointer to command for displaying logged-in users.
1029 Example: char *WHOCMD = "who ";
1030 Note trailing space. Specific user name may be added to this
1034 Flag for whether program is running in foreground (0) or
1035 background (nonzero). Background operation implies that screen
1036 output should not be done and that all errors should be fatal.
1039 Flag for who is to echo console typein:
1040 1: The program (system is not echoing).
1041 0: The OS, front end, terminal, etc (not this program).
1044 Pointer to string that names the computer and operating system.
1045 Example: char *ckxsys = " NeXT Mach 1.0";
1046 Tells what computer system ckxv applies to. In UNIX Kermit, this
1047 variable is also used to print the program herald, and in the
1048 SHOW VERSION command.
1051 Pointer to version/edit info of ck?tio.c module.
1052 Example: char *ckxv = "UNIX Communications Support, 6.0.169, 6
1054 Used by SHOW VERSION command.
1057 Like ckxsys, but briefer.
1058 Example: char *ckzsys = " 4.3 BSD";
1059 Tells what platform ckzv applies to. Used by the SHOW VERSION
1063 Pointer to version/edit info of ck?fio.c module.
1064 Example: char *ckzv = "UNIX File support, 6.0.113, 6 Sep 96";
1065 Used by SHOW VERSION command.
1068 Default flow control. 0 = none, 1 = Xon/Xoff, ... (see FLO_xxx
1069 symbols in ckcdeb.h)
1070 Set by Group E module. Used by [125]ckcmai.c to initialize flow
1074 Default location. 0 = remote, 1 = local. Set by Group E module.
1075 Used by ckcmai.c to initialize local variable. Used in various
1076 places in the user interface.
1079 Default parity. 0 = none, 'e' = even, 'o' = odd, 'm' = mark, 's'
1080 = space. Set by Group E module. Used by ckcmai.c to initialize
1084 Default communication device. Set by Group E module. Used in
1085 many places. This variable should be initialized the the symbol
1086 CTTNAM, which is defined in ckcdeb.h, e.g. as "/dev/tty" for
1087 UNIX, "TT:" for VMS, etc. Example: char *dftty = CTTNAM;
1090 Array of string pointers to filenames that matched the most
1091 recent wildcard match, i.e. the most recent call to zxpand().
1092 Used (at least) by command parsing package for partial filename
1096 Flag for whether to attempt to expand leading tildes in
1097 directory names (used in UNIX only, and then only when the
1098 symbol DTILDE is defined.
1101 The protocol being used to communicate over a network device.
1102 Values are defined in ckcnet.h. Example: NP_TELNET is network
1106 The maximum length for a filename, exclusive of any device or
1107 directory information, in the format of the host operating
1111 The maximum length for a fully specified filename, including
1112 device designator, directory name, network node name, etc, in
1113 the format of the host operating system, and including all
1117 File descriptor of the communication device. -1 if there is no
1118 open or usable connection, including when C-Kermit is in remote
1119 mode. Since this is not implemented everywhere, references to it
1120 are in #ifdef CK_TTYFD..#endif.
1122 [ [126]Contents ] [ [127]C-Kermit ] [ [128]Kermit Home ]
1126 These are divided into three categories: file-related functions (B.1),
1127 communication functions (B.2), and miscellaneous functions (B.3).
1129 4.E.2.1. File-Related Functions
1131 In most implementations, these are collected together into a module
1132 called ck?fio.c, where ? = "u" ([129]ckutio.c for Unix), "v"
1133 ([130]ckvtio.c for VMS), [131]etc. To be totally platform-independent,
1134 C-Kermit maintains its own file numbers, and provides the functions
1135 described in this section to deal with the files associated with them.
1136 The file numbers are referred to symbolically, and are defined as
1137 follows in ckcker.h:
1139 #define ZCTERM 0 /* Console terminal */
1140 #define ZSTDIO 1 /* Standard input/output */
1141 #define ZIFILE 2 /* Current input file for SEND command */
1142 #define ZOFILE 3 /* Current output file for RECEIVE command */
1143 #define ZDFILE 4 /* Current debugging log file */
1144 #define ZTFILE 5 /* Current transaction log file */
1145 #define ZPFILE 6 /* Current packet log file */
1146 #define ZSFILE 7 /* Current session log file */
1147 #define ZSYSFN 8 /* Input from a system function (pipe) */
1148 #define ZRFILE 9 /* Local file for READ command */ (NEW)
1149 #define ZWFILE 10 /* Local file for WRITE command */ (NEW)
1150 #define ZMFILE 11 /* Auxilliary file for internal use */ (NEW)
1151 #define ZNFILS 12 /* How many defined file numbers */
1153 In the descriptions below, fn refers to a filename, and n refers to one
1154 of these file numbers. Functions are of type int unless otherwise
1155 noted, and are listed mostly alphabetically.
1159 Checks the file number n. Returns:
1160 -1: File number n is out of range
1161 0: n is in range, but file is not open
1162 1: n in range and file is open
1165 iswild(filspec) char *filespec;
1166 Checks if the file specification is "wild", i.e. contains
1167 metacharacters or other notations intended to match multiple
1173 isdir(string) char *string;
1174 Checks if the string is the name of an existing directory. The
1175 idea is to check whether the string can be "cd'd" to, so in some
1176 cases (e.g. DOS) it might also indicate any file structured
1177 device, such as a disk drive (like A:). Other nonzero returns
1178 indicate system-dependent information; e.g. in VMS
1179 isdir("[.FOO]") returns 1 but isdir("FOO.DIR;1") returns 2 to
1180 indicate the directory-file name is in a format that needs
1181 conversion before it can be combined with a filename. Returns:
1182 0: not a directory (including any kind of error)
1183 1: it is an existing directory
1186 zfcdat(name) char *name;
1187 Returns modification (preferably, otherwise creation) date/time
1188 of file whose name is given in the argument string. Return value
1189 is a pointer to a string of the form yyyymmdd hh:mm:ss, for
1190 example 19931231 23:59:59, which represents the local time (no
1191 timezone or daylight savings time finagling required). Returns
1192 the null string ("") on failure. The text pointed to by the
1193 string pointer might be in a static buffer, and so should be
1194 copied to a safe place by the caller before any subsequent calls
1198 zfnqfp(fn, buflen, buf) char * fn; int buflen; char * buf;
1199 Given the filename fn, the corresponding fully qualified,
1200 absolute filename is placed into the buffer buf, whose length is
1201 buflen. On failure returns a NULL pointer. On success returns a
1202 pointer to a struct zfnfp containing pointers to the full
1203 pathname and to just the filename, and an int giving the length
1204 of the full pathname. All references to this function in
1205 mainline code must be protected by #ifdef ZFNQFP..#endif,
1206 because it is not present in all of the ck*fio.c modules. So if
1207 you implement this function in a version that did not have it
1208 before, be sure to add #define ZFNQFP in the appropriate spot in
1209 ckcdeb.h or in the build-procedure CFLAGS.
1212 zcmpfn(s1,s2) char * s2, * s2;
1213 Compares two filenames to see if they refer to the same.
1214 Internally, the arguments can be converted to fully qualified
1215 pathnames, e.g. with zfnqfp(), realpath(), or somesuch. In Unix
1216 or other systems where symbolic links exist, the link should be
1217 resolved before making the comparison or looking at the inodes.
1219 0: Files are not identical.
1220 1: Files are identical.
1223 zfseek(pos) long pos;
1224 Positions the input pointer on the current input file to the
1225 given position. The pos argument is 0-based, the offset
1226 (distance in bytes) from beginning of the file. Needed for
1227 RESEND, PSEND, and other recovery operations. This function is
1228 not necessarily possible on all systems, e.g. record-oriented
1229 systems. It should only be used on binary files (i.e. files we
1230 are sending in binary mode) and stream-oriented file systems.
1236 zchdir(dirnam) char *dirnam;
1237 Changes current or default directory to the one given in dirnam.
1244 Check to see if file with name fn is a regular, readable,
1245 existing file, suitable for Kermit to send -- not a directory,
1246 not a symbolic link, etc. Returns:
1247 -3: if file exists but is not accesssible (e.g.
1249 -2: if file exists but is not of a readable type (e.g. a
1251 -1: on error (e.g. file does not exist, or fn is garbage);
1252 >=0: (length of file) if file exists and is readable.
1253 Also see isdir(), zgetfs().
1256 zchkpid(pid) unsigned long pid;
1258 1: If the given process ID (e.g. pid in UNIX) is valid and
1263 zgetfs(fn) char *fn;
1264 Gets the size of the given file, regardless of accesssibility.
1265 Used for directory listings. Unlike zchki(), should return the
1266 size of any kind of file, even a directory. zgetfs() also should
1267 serve as a mini "get file info" function that can be used until
1268 we design a better one, by also setting some global variables:
1269 int zgfs_link = 1/0 = file is (not) a symbolic link.
1270 int zgfs_dir = 1/0 = file is (not) a directory.
1271 char linkname[] = if zgfs_link != 0, name of file link points
1274 -1: on error (e.g. file does not exist, or fn is garbage);
1275 >=0: (length of file) if file exists and is readable.
1279 Checks to see if a file of the given name can be created.
1281 -1: if file cannot be created, or on any kind of error.
1282 0: if file can be created.
1285 zchkspa(fn,len) char *f; long len;
1286 Checks to see if there is sufficient space to store the file
1287 named fn, which is len bytes long. If you can't write a function
1288 to do this, then just make a dummy that always returns 1; higher
1289 level code will recover from disk-full errors. The receiving
1290 Kermit uses this function to refuse an incoming file based on
1291 its size, via the attribute mechanism. Returns:
1293 0: if there is not enough space.
1294 1: if there is enough space.
1297 zchin(n,c) int n; int *c;
1298 Gets a character from file number n, return it in c (call with
1300 -1: on failure, including EOF.
1301 0: on success with character in c.
1304 zchout(n,c) int n; char c;
1305 Writes the character c to file number n. Returns:
1311 Closes file number n. Returns:
1316 zdelet(fn) char *name;
1317 Attempts to delete (remove, erase) the named file. Returns:
1319 1: if file was deleted successfully.
1323 Returns a pointer to the system-dependent numeric
1324 permissions/protection string for file f, or NULL upon failure.
1325 Used if CK_PERMS is defined.
1329 Returns a pointer to the system-dependent symbolic
1330 permissions/protection string for file f, or NULL upon failure.
1331 Used if CK_PERMS is defined. Example: In UNIX zgperm(f) might
1332 return "100770", but ziperm() might return "-rwxrwx---". In VMS,
1333 zgperm() would return a hexadecimal string, but ziperm() would
1334 return something like "(RWED,RWED,RE,)".
1338 Returns a pointer to the name of the current directory, folder,
1339 etc, or a NULL pointer if the current directory cannot be
1340 determined. If possible, the directory specification should be
1341 (a) fully specified, e.g. as a complete pathname, and (b) be
1342 suitable for appending a filename. Thus, for example, Unix
1343 directory names should end with '/'. VMS directory names should
1344 look like DEV:[NAME] (rather than, say, NAME.DIR;1).
1348 Returns a pointer to a string containing the user's home
1349 directory, or NULL upon error. Should be formatted like zgtdir()
1354 Fill buffer from input file. This function is used by the macro
1355 zminchar(), which is defined in ckcker.h. zminchar() manages its
1356 own buffer, and calls zinfill() to fill it whenever it becomes
1357 empty. It is used only for sending files, and reads characters
1358 only from file number ZIFILE. zinfill() returns -1 upon end of
1359 file, -2 upon fatal error, and -3 upon timeout (e.g. when
1360 reading from a pipe); otherwise it returns the first character
1361 from the buffer it just read.
1365 Kills the current job, session, process, etc, logs out,
1366 disappears. Used by the Kermit server when it receives a BYE
1367 command. On failure, returns -1. On success, does not return at
1368 all! This function should not be called until all other steps
1369 have been taken to close files, etc.
1372 zstrip(fn,&fn2) char *fn1, **fn2;
1373 Strips device and directory, etc, from file specification fn,
1374 leaving only the filename (including "extension" or "filetype"
1375 -- the part after the dot). For example DUA0:[PROGRAMS]OOFA.C;3
1376 becomes OOFA.C, or /usr/fdc/oofa.c becomes oofa.c. Returns a
1377 pointer to result in fn2.
1380 zsetperm(char * file, unsigned int code)
1381 Set permissions of file to given system-dependent code. 0: On
1386 zsetroot(char * dir)
1387 Sets the root for the user's file accesss, like Unix chroot(),
1388 but does not require privilege. In Unix, this must be
1389 implemented entirely by Kermit's own file accesss routines.
1392 -1: Invalid argument
1395 -4: Access to given directory denied
1396 -5: New root not within old root
1399 zinroot(char * file)
1400 If no root is set (zsetroot()), returns 1.
1401 Otherwise, if given file is in the root, returns 1.
1402 Otherwise, returns 0.
1405 zltor(fn,fn2) char *fn1, *fn2;
1406 Local-To-Remote filename translation. OBSOLETE: replaced by
1407 nzltor() (q.v.). Translates the local filename fn into a format
1408 suitable for transmission to an arbitrary type of computer, and
1409 copies the result into the buffer pointed to by fn2. Translation
1410 may involve (a) stripping the device and/or directory/path name,
1411 (b) converting lowercase to uppercase, (c) removing spaces and
1412 strange characters, or converting them to some innocuous
1413 alphabetic character like X, (d) discarding or converting extra
1414 periods (there should not be more than one). Does its best.
1415 Returns no value. name2 is a pointer to a buffer, furnished by
1416 the caller, into which zltor() writes the resulting name. No
1417 length checking is done.
1421 nzltor(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
1422 convert,pathnames,max;
1423 Replaces zltor(). This new version handles pathnames and checks
1424 length. fn1 and fn2 are as in zltor(). This version is called
1425 unconditionally for each file, rather than only when filename
1426 conversion is enabled. Pathnames can have the following values:
1428 PATH_OFF: Pathname, if any, is to be stripped
1429 PATH_REL: The relative pathname is to be included
1430 PATH_ABS: The full pathname is to be included
1432 After handling pathnames, conversion is done to the result as in
1433 the zltor() description if convert != 0; if relative or absolute
1434 pathnames are included, they are converted to UNIX format, i.e.
1435 with slash (/) as the directory separator. The max parameter
1436 specifies the maximum size of fn2. If convert > 0, the regular
1437 conversions are done; if convert < 0, minimal conversions are
1438 done (we skip uppercasing the letters, we allow more than one
1439 period, etc; this can be used when we know our partner is UNIX
1445 nzxpand(fn,flags) char *fn; int flags;
1446 Replaces zxpand(), which is obsolete as of C-Kermit 7.0.
1448 fn = Pointer to filename or pattern.
1449 flags = option bits:
1450 flags & ZX_FILONLY Match regular files
1451 flags & ZX_DIRONLY Match directories
1452 flags & ZX_RECURSE Descend through directory tree
1453 flags & ZX_MATCHDOT Match "dot files"
1454 flags & ZX_NOBACKUP Don't match "backup files"
1455 flags & ZX_NOLINKS Don't follow symlinks.
1457 Returns the number of files that match fn, with data structures
1458 set up so the first file (if any) will be returned by the next
1459 znext() call. If ZX_FILONLY and ZX_DIRONLY are both set, or
1460 neither one is set, files and directories are matched. Notes:
1462 1. It is essential that the number returned by nzxpand() reflect
1463 the actual number of filenames that will be returned by
1464 znext() calls. In other words:
1465 for (n = nzxpand(string,flags); n > 0; n--) {
1467 printf("%s\n", buf);
1470 should print all the file names; no more, no less.
1471 2. In UNIX, DOS, OS-9, etc, where directories contain entries for
1472 themselves (.) and the superior directory (..), these should
1473 NOT be included in the list under any circumstances, including
1474 when ZX_MATCHDOT is set.
1475 3. Additional option bits might be added in the future, e.g. for
1476 sorting (sort by date/name/size, reverse/ascending, etc).
1477 Currently this is done only in higher level code (through a
1478 hack in which the nzxpand() exports its filename array, which
1479 is not portable because not all OS's can use this mechanism).
1482 zmail(addr,fn) char *addr, fn;
1483 Send the local, existing file fn as e-mail to the address addr.
1486 2: if mail delivered but temp file can't be deleted
1487 -2: if mail can't be delivered
1490 zmkdir(path) char *path;
1491 The path can be a file specification that might contain
1492 directory information, in which the filename is expected to be
1493 included, or an unambiguous directory specification (e.g. in
1494 UNIX it must end with "/"). This routine attempts to create any
1495 directories in the given path that don't already exist. Returns
1496 0 or greater success: no directories needed creation, or else
1497 all directories that needed creation were created successfully;
1498 the return code is the number of directories that were created.
1499 Returns -1 on failure to create any of the needed directories.
1502 zrmdir(path) char *path;
1503 Attempts to remove the given directory. Returns 0 on success, -1
1504 on failure. The detailed semantics are open -- should it fail if
1505 the directory contains any files or subdirectories, etc. It is
1506 probably best for this routine to behave in whatever manner is
1507 customary on the underlying platform; e.g. in UNIX, VMS, DOS,
1508 etc, where directories can not be removed unless they are empty.
1511 znewn(fn,s) char *fn, **s;
1512 Transforms the name fn into a filename that is guaranteed to be
1513 unique. If the file fn does not exist, then the new name is the
1514 same as fn; Otherwise, it's different. this function does its
1515 best, returns no value. New name is created in caller's space.
1516 Call like this: znewn(old,&new);. The second parameter is a
1517 pointer to the new name. This pointer is set by znewn() to point
1518 to a static string in its own space, so be sure to the result to
1519 a safe place before calling this function again.
1523 Copies the next file name from a file list created by zxpand()
1524 into the string pointed to by fn (see zxpand). If no more files,
1525 then the null string is placed there. Returns 0 if there are no
1526 more filenames, with 0th element the array pointed to by fn set
1527 to NUL. If there is a filename, it is stored in the array
1528 pointed to by fn and a positive number is returned. NOTE: This
1529 is a change from earlier definitions of this function
1530 (pre-1999), which returned the number of files remaining; thus 0
1531 was the return value when returning the final file. However, no
1532 mainline code ever depended on the return value, so this change
1536 zopeni(n,fn) int n; char *fn;
1537 Opens the file named fn for input as file number n. Returns:
1542 zopeno(n,fn,zz,fcb) int n; char *name; struct zattr *zz; struct
1544 Attempts to open the named file for output as file number n. zz
1545 is a Kermit file attribute structure as defined in ckcdeb.h,
1546 containing various information about the file, including its
1547 size, creation date, and so forth. This function should attempt
1548 to honor as many of these as possible. fcb is a "file control
1549 block" in the traditional sense, defined in ckcdeb.h, containing
1550 information relevant to complicated file systems like VMS (RMS),
1551 IBM MVS, etc, like blocksize, record length, organization,
1552 record format, carriage control, etc. Returns:
1558 Dumps a file output buffer. Used with the macro zmchout()
1559 defined in ckcker.h. Used only with file number ZOFILE, i.e. the
1560 file that is being received by Kermit during file transfer.
1566 zprint(p,fn) char *p, *f;
1567 Prints the file with name fn on a local printer, with options p.
1570 3: if file sent to printer but can't be deleted
1571 -3: if file can't be printed
1574 zrename(fn,fn2) char *fn, *fn2;
1575 Changes the name of file fn to fn2. If fn2 is the name of an
1576 existing directory, or a file-structured device, then file fn is
1577 moved to that directory or device, keeping its original name. If
1578 fn2 lacks a directory separator when passed to this function, an
1579 appropriate one is supplied. Returns:
1584 zcopy(source,dest) char * source, * dest;
1585 Copies the source file to the destination. One file only. No
1586 wildcards. The destination string may be a filename or a
1587 directory name. Returns:
1590 -2: source file is not a regular file.
1591 -3: source file not found.
1592 -4: permission denied.
1593 -5: source and destination are the same file.
1599 Call with: "yyyymmdd hh:mm:ss" GMT/UTC date-time. Returns
1600 pointer to local date-time string "yyyymmdd hh:mm:ss" on
1601 success, NULL on failure.
1604 zrtol(fn,fn2) char *fn, *fn2;
1605 Remote-To-Local filename translation. OBSOLETE: replaced by
1606 nzrtol(). Translates a "standard" filename to a local filename.
1607 For example, in Unix this function might convert an
1608 all-uppercase name to lowercase, but leave lower- or mix-case
1609 names alone. Does its best, returns no value. New name is in
1610 string pointed to by fn2. No length checking is done.
1614 nzrtol(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
1615 convert,pathnames,max;
1616 Replaces zrtol. Like zrtol but handles pathnames and checks
1617 length. See nzltor for detailed description of parameters.
1622 zsattr(xx) struct zattr *xx;
1623 Fills in a Kermit file attribute structure for the file which is
1624 to be sent, namely the currently open ZIFILE. Note that this is
1625 not a very good design, but we're stuck with it. Callers must
1626 ensure that zsattr() is called only on real files, not on pipes,
1627 internally generated file-like objects such as server REMOTE
1628 command responses, etc. Returns:
1630 0: on success with the structure filled in.
1631 If any string member is null, it should be ignored by the
1633 If any numeric member is -1, it should be ignored by the caller.
1637 s contains to pointer to a command to be executed by the host
1638 computer's shell, command parser, or operating system. If the
1639 system allows the user to choose from a variety of command
1640 processors (shells), then this function should employ the user's
1641 preferred shell. If possible, the user's job (environment,
1642 process, etc) should be set up to catch keyboard interruption
1643 signals to allow the user to halt the system command and return
1644 to Kermit. The command must run in ordinary, unprivileged user
1645 mode. If possible, this function should return -1 on failure to
1646 start the command, or else it should return 1 if the command
1647 succeeded and 0 if it failed.
1651 zshcmd() and zsyscmd() should set this to the command's actual
1652 exit status code if possible.
1656 s contains to pointer to a command to be executed by the host
1657 computer's shell, command parser, or operating system. If the
1658 system allows the user to choose from a variety of command
1659 processors (shells), then this function should employ the system
1660 standard shell (e.g. /bin/sh for Unix), so that the results will
1661 always be the same for everybody. If possible, the user's job
1662 (environment, process, etc) should be set up to catch keyboard
1663 interruption signals to allow the user to halt the system
1664 command and return to Kermit. The command must run in ordinary,
1665 unprivileged user mode. If possible, this function should return
1666 -1 on failure to start the command, or else it should return 1
1667 if the command succeeded and 0 if it failed.
1670 z_exec(s,args) char * s; char * args[];
1671 This one executes the command s (which is searched for using the
1672 system's normal searching mechanism, such as PATH in UNIX), with
1673 the given argument vector, which follows the conventions of UNIX
1674 argv[]: the name of the command pointed to by element 0, the
1675 first arg by element 1, and so on. A null args[] pointer
1676 indicates the end of the argument list. All open files must
1677 remain open so the exec'd process can use them. Returns only if
1681 zsinl(n,s,x) int n, x; char *s;
1682 Reads a line from file number n. Writes the line into the
1683 address s provided by the caller. Writing terminates when
1684 newline is read, but with newline discarded. Writing also
1685 terminates upon EOF or if length x is exhausted. Returns:
1686 -1: on EOF or error.
1690 zsout(n,s) int n; char *s;
1691 Writes the string s out to file number n. Returns:
1696 zsoutl(n,s) int n; char *s;
1697 Writes the string s out to file number n and adds a line
1698 (record) terminator (boundary) appropriate for the system and
1699 the file format. Returns:
1704 zsoutx(n,s,x) int n, x; char *s;
1705 Writes exactly x characters from string s to file number n. If s
1706 has fewer than x characters, then the entire string s is
1709 >= 0: on success, the number of characters actually written.
1712 zstime(fn,yy,x) char *fn; struct zattr *yy; int x;
1713 Sets the creation date (and other attributes) of an existing
1714 file, or compares a file's creation date with a given date. Call
1717 fn: pointer to name of existing file.
1718 yy: Pointer to a Kermit file attribute structure in which yy->date.val
1719 is a date of the form yyyymmdd hh:mm:ss, e.g. 19900208 13:00:00, which
1720 is to be used for setting or comparing the file date. Other attributes
1721 in the struct can also be set, such as the protection/permission (See
1722 [132]Appendix I), when it makes sense (e.g. "yy->lprotect.val" can be
1723 set if the remote system ID matches the local one).
1724 x: A function code: 0 means to set the file's creation date as given.
1725 1 means compare the date from the yy struct with the file's date.
1728 -1: on any kind of error.
1729 0: if x is 0 and the file date was set successfully.
1730 0: if x is 1 and date from attribute structure > file creation
1732 1: if x is 1 and date from attribute structure <= file
1736 zstrip(name,name2) char *name, **name2;
1737 Strips pathname from filename "name". Constructs the resulting
1738 string in a static buffer in its own space and returns a pointer
1739 to it in name2. Also strips device name, file version numbers,
1740 and other "non-name" material.
1744 Runs a system command so its output can be accesssed as if it
1745 were file n. The command is run in ordinary, unprivileged user
1747 If n is ZSTDIO or ZCTERM, returns -1.
1748 If n is ZIFILE or ZRFILE, then Kermit reads from the command,
1749 otherwise Kermit writes to the command.
1750 Returns 0 on error, 1 on success.
1753 zxpand(fn) char *fn;
1754 OBSOLETE: Replaced by nzxpand(), q.v.
1759 Returns the number of files returned by the most recent
1760 nzxpand() call, and resets the list to the beginning so the next
1761 znext() call returns the first file. Returns -1 if zxpand has
1762 not yet been called. If this function is available, ZXREWIND
1763 should be defined; otherwise it should not be referenced.
1765 #endif /* ZXREWIND */
1768 xsystem(cmd) char *cmd;
1769 Executes the system command without redirecting any of its i/o,
1770 similar (well, identical) to system() in Unix. But before
1771 passing the command to the system, xsystem() ensures that all
1772 privileges are turned off, so that the system command executes
1773 in ordinary unprivileged user mode. If possible, xsystem()
1774 returns the return code of the command that was executed.
1776 4.E.2.2. IKSD Variables and Functions
1778 These must be implemented in any C-Kermit version that is to be
1779 installed as an Internet Kermit Service Daemon (IKSD). IKSD is expected
1780 to be started by the Internet Daemon (e.g. inetd) with its standard i/o
1781 redirected to the incoming connection.
1784 Nonzero if anonymous logins allowed.
1786 extern int inserver;
1787 Nonzero if started in IKSD mode.
1790 Nonzero if IKSD and user logged in anonymously.
1792 extern char * homdir;
1793 Pointer to user's home directory.
1795 extern char * anonroot;
1796 Pointer to file-system root for anonymous users.
1798 Existing functions must make "if (inserver && isguest)" checks for
1799 actions that would not be legal for guests: zdelete(), zrmdir(),
1800 zprint(), zmail(), etc.
1803 zvuser(name) char * name;
1804 Verifies that user "name" exists and is allowed to log in. If
1805 the name is "ftp" or "anonymous" and ckxanon != 0, a guest login
1806 is set up. Returns 0 if user not allowed to log in, nonzero if
1810 zvpass(string) char * string;
1811 Verifies password of the user from the most recent zvuser()
1812 call. Returns nonzero if password is valid for user, 0 if it
1813 isn't. Makes any appropriate system log entries (IKSD logins,
1814 failed login attempts, etc). If password is valid, logs the user
1815 in as herself (if real user), or sets up restricted anonymous
1816 accesss if user is guest (e.g. changes file-system root to
1817 anonroot and sets isguest = 1).
1821 Begins any desired system logging of an IKSD session.
1825 Terminates an IKSD session. In most cases this is simply a
1826 wrapper for exit() or doexit(), with some system logging added.
1828 4.E.2.3. Privilege Functions
1830 These functions are used by C-Kermit to adapt itself to operating
1831 systems where the program can be made to run in a "privileged" mode,
1832 e.g. setuid or setgid in Unix. C-Kermit should NOT read and write files
1833 or start subprocesses as a privileged program. This would present a
1834 serious threat to system security. The security package has been
1835 installed to prevent such security breaches by turning off the
1836 program's special privileges at all times except when they are needed.
1838 In UNIX, the only need Kermit has for privileged status is accesss to
1839 the UUCP lockfile directory, in order to read, create, and destroy
1840 lockfiles, and to open communication devices that are normally
1841 protected against the user (see the [133]Unix C-Kermit Installation
1842 Instructions for discussion). Therefore, privileges should only be
1843 enabled for these operations and disabled at all other times. This
1844 relieves the programmer of the responsibility of putting expensive and
1845 unreliable accesss checks around every file accesss and subprocess
1848 Strictly speaking, these functions are not required in all C-Kermit
1849 implementations, because their use (so far, at least) is internal to
1850 the Group E modules. However, they should be included in all C-Kermit
1851 implementations for operating systems that support the notion of a
1852 privileged program (UNIX, RSTS/E, what others?).
1856 Determine whether the program is running in privileged status.
1857 If so, turn off the privileges, in such a way that they can be
1858 turned on again when needed. Called from sysinit() at program
1859 startup time. Returns:
1861 nonzero on failure, in which case the program should halt
1866 If the program is not privileged, this function does nothing. If
1867 the program is privileged, this function returns it to
1868 privileged status. priv_ini() must have been called first.
1875 Turns privileges off (if they are on) in such a way that they
1876 can be turned back on again. Returns:
1882 Turns privileges off in such a way that they cannot be turned
1889 Attempts to turns privileges off in such a way that they can be
1890 turned on again later. Then checks to make sure that they were
1891 really turned off. If they were not really turned off, then they
1892 are cancelled permanently. Returns:
1896 4.E.2.4. Console-Related Functions
1898 These relate to the program's "console", or controlling terminal, i.e.
1899 the terminal that the user is logged in on and types commands at, or on
1900 a PC or workstation, the actual keyboard and screen.
1903 conbin(esc) char esc;
1904 Puts the console into "binary" mode, so that Kermit's command
1905 parser can control echoing and other treatment of characters
1906 that the user types. esc is the character that will be used to
1907 get Kermit's attention during packet mode; puts this in a global
1908 place. Sets the ckxech variable. Returns:
1913 concb(esc) char esc;
1914 Put console in "cbreak" (single-character wakeup) mode. That is,
1915 ensure that each console character is available to the program
1916 immediately when the user types it. Otherwise just like
1923 Returns a number, 0 or greater, the number of characters waiting
1924 to be read from the console, i.e. the number of characters that
1925 the user has typed that have not been read yet by Kermit.
1929 Returns the speed ("baud rate") of the controlling terminal, if
1930 known, otherwise -1L.
1933 congks(timo) int timo;
1934 Get Keyboard Scancode. Reads a keyboard scan code from the
1935 physical console keyboard. If the timo parameter is greater than
1936 zero, then times out and returns -2 if no character appears
1937 within the given number of seconds. Upon any other kind of
1938 error, returns -1. Upon success returns a scan code, which may
1939 be any positive integer. For situations where scan codes cannot
1940 be read (for example, when an ASCII terminal is used as the
1941 job's controlling terminal), this function is identical to
1942 coninc(), i.e. it returns an 8-bit character value. congks() is
1943 for use with workstations whose keyboards have Alternate,
1944 Command, Option, and similar modifier keys, and Function keys
1945 that generate codes greater than 255.
1949 Console get modes. Gets the current console terminal modes and
1950 saves them so that conres() can restore them later. Returns 1 if
1951 it got the modes OK, 0 if it did nothing (e.g. because Kermit is
1952 not connected with any terminal), -1 on error.
1955 coninc(timo) int timo;
1956 Console Input Character. Reads a character from the console. If
1957 the timo parameter is greater than zero, then coninc() times out
1958 and returns -2 if no character appears within the given number
1959 of seconds. Upon any other kind of error, returns -1. Upon
1960 success, returns the character itself, with a value in the range
1964 conint(f,s) SIGTYP (*f)(), (*s)();
1965 Sets the console to generate an interrupt if the user types a
1966 keyboard interrupt character, and to transfer control the
1967 signal-handling function f. For systems with job control, s is
1968 the address of the function that suspends the job. Sets the
1969 global variable "backgrd" to zero if Kermit is running in the
1970 foreground, and to nonzero if Kermit is running in the
1971 background. See ckcdeb.h for the definition of SIGTYP. No return
1976 Console no interrupts. Disable keyboard interrupts on the
1977 console. No return value.
1981 Writes character c to the console terminal. Returns:
1982 0 on failure, 1 on success.
1986 Writes string s to the console. Returns -1 on error, 0 or
1990 conola(s) char *s[]; {
1991 Writes an array of strings to the console. Returns -1 on error,
1992 0 or greater on success.
1996 Writes string s to the console, followed by the necessary line
1997 termination characters to put the console cursor at the
1998 beginning of the next line. Returns -1 on error, 0 or greater on
2003 Restores the console terminal to the modes obtained by congm().
2004 Returns: -1 on error, 0 on success.
2007 conxo(x,s) int x; char *s;
2008 Write x characters from string s to the console. Returns 0 or
2009 greater on success, -1 on error.
2013 Returns a pointer to the designator of the console keyboard
2014 type. For example, on a PC, this function would return "88",
2015 "101", etc. Upon failure, returns a pointer to the empty string.
2017 4.E.2.5. Communications Functions
2019 The communication device is the device used for terminal emulation and
2020 file transfer. It may or may not be the same device as the console, and
2021 it may or may not be a terminal (serial-port) device; it could also be
2022 a network connection. For brevity, the communication device is referred
2023 to here as the "tty". When the communication device is the same as the
2024 console device, Kermit is said to be in remote mode. When the two
2025 devices are different, Kermit is in local mode.
2029 Returns the number of characters that have arrived at the
2030 communication device but have not yet been read by ttinc(),
2031 ttinl(), and friends. If communication input is buffered (and it
2032 should be), this is the sum of the number of unread characters
2033 in Kermit's buffer PLUS the number of unread characters in the
2034 operating system's internal buffer. The call must be
2035 nondestructive and nonblocking, and as inexpensive as possible.
2037 0: or greater on success,
2038 0: in case of internal error,
2039 -1: or less when it determines the connection has been broken,
2040 or there is no connection.
2042 That is, a negative return from ttchk() should reliably indicate
2043 that there is no usable connection. Furthermore, ttchk() should
2044 be callable at any time to see if the connection is open. When
2045 the connection is open, every effort must be made to ensure that
2046 ttchk returns an accurate number of characters waiting to be
2047 read, rather than just 0 (no characters) or 1 (1 or more
2048 characters), as would be the case when we use select(). This
2049 aspect of ttchk's operation is critical to successful operation
2050 of sliding windows and streaming, but "nondestructive buffer
2051 peeking" is an obscure operating system feature, and so when it
2052 is not available, we have to do it ourselves by managing our own
2053 internal buffer at a level below ttinc(), ttinl(), etc, as in
2054 the UNIX version (non-FIONREAD case).
2056 An external global variable, clsondisc, if nonzero, means that
2057 if a serial connection drops (carrier on-to-off transition
2058 detected by ttchk()), the device should be closed and released
2063 Closes the communication device (tty or network). If there were
2064 any kind of exclusive accesss locks connected with the tty,
2065 these are released. If the tty has a modem connection, it is
2066 hung up. For true tty devices, the original tty device modes are
2073 Flush communications input buffer. If any characters have
2074 arrived but have not yet been read, discard these characters. If
2075 communications input is buffered by Kermit (and it should be),
2076 this function flushes Kermit's buffer as well as the operating
2077 system's internal input buffer. Returns:
2083 Flush tty output buffer. If any characters have been written but
2084 not actually transmitted (e.g. because the system has been
2085 flow-controlled), remove them from the system's output buffer.
2086 (Note, this function is not actually used, but it is recommended
2087 that all C-Kermit programmers add it for future use, even if it
2088 is only a dummy function that returns 0 always.)
2092 Looks for the modem signals CTS, DSR, and CTS, and returns those
2093 that are on in as its return value, in a bit mask as described
2094 for ttwmdm, in which a bit is on (1) or off (0) according to
2095 whether the corresponding signal is on (asserted) or off (not
2096 asserted). Return values:
2098 -2: if the line does not have modem control
2100 >=0: on success, with bit mask containing the modem signals.
2104 Returns the current tty speed in BITS (not CHARACTERS) per
2105 second, or -1 if it is not known or if the tty is really a
2106 network, or upon any kind of error. On success, the speed
2107 returned is the actual number of bits per second, like 1200,
2112 Get terminal window size. Returns -1 on error, 0 if the window
2113 size can't be obtained, 1 if the window size has been
2114 successfully obtained. Upon success, the external global
2115 variables tt_rows and tt_cols are set to the number of screen
2116 rows and number of screen columns, respectively. As this
2117 function is not implemented in all ck*tio.c modules, calls to it
2118 must be wrapped in #ifdef CK_TTGWSIZ..#endif. NOTE: This
2119 function must be available to use the TELNET NAWS feature
2120 (Negotiate About Window Size) as well as Rlogin.
2124 Hang up the current tty device. For real tty devices, turn off
2125 DTR for about 1/3-1/2 second (or other length of time, depending
2126 on the system). If the tty is really a network connection, close
2129 0: if it does not even try to hang up.
2130 1: if it believes it hung up successfully.
2134 Turns off all pending timer interrupts.
2137 ttinc(timo) int timo; (function is old, return codes are new)
2138 Reads one character from the communication device. If timo is
2139 greater than zero, wait the given number of seconds and then
2140 time out if no character arrives, otherwise wait forever for a
2142 -3: internal error (e.g. tty modes set wrong)
2143 -2: communications disconnect
2144 -1: timeout or other error
2145 >=0: the character that was read.
2146 It is HIGHLY RECOMMENDED that ttinc() be internally buffered so
2147 that calls to it are relatively inexpensive. If it is possible
2148 to to implement ttinc() as a macro, all the better, for example
2151 #define ttinc(t) ( (--txbufn >= 0) ? txbuf[ttbufp++] : txbufr(t) )
2153 (see description of txbufr() below)
2156 ttinl(dest,max,timo,eol,start,turn) int max,timo,turn; CHAR
2158 ttinl() is Kermit's packet reader. Reads a packet from the
2159 communications device, or up to max characters, whichever occurs
2160 first. A line is a string of characters starting with the start
2161 character up to and including the character given in eol or
2162 until the length is exhausted, or, if turn != 0, until the line
2163 turnaround character (turn) is read. If turn is 0, ttinl()
2164 *should* use the packet length field to detect the end, to allow
2165 for the possibility that the eol character appears unprefixed in
2166 the packet data. (The turnaround character is for half-duplex
2167 linemode connections.)
2169 If timo is greater than zero, ttinl() times out if the eol
2170 character is not encountered within the given number of seconds
2173 The characters that were input are copied into "dest" with their
2174 parity bits stripped if parity is not none. The first character
2175 copied into dest should be the start character, and the last
2176 should be the final character of the packet (the last block
2177 check character). ttinl() should also absorb and discard the eol
2178 and turn characters, and any other characters that are waiting
2179 to be read, up until the next start character, so that
2180 subsequent calls to ttchk() will not succeed simply because
2181 there are some terminators still sitting in the buffer that
2182 ttinl() didn't read. This operation, if performed, MUST NOT
2183 BLOCK (so if it can't be performed in a guaranteed nonblocking
2186 On success, ttinl() returns the number of characters read.
2187 Optionally, ttinl() can sense the parity of incoming packets. If
2188 it does this, then it should set the global variable ttprty
2189 accordingly. ttinl() should be coded to be as efficient as
2190 possible, since it is at the "inner loop" of packet reception.
2192 -1: Timeout or other possibly correctable error.
2193 -2: Interrupted from keyboard.
2194 -3: Uncorrectable i/o error -- connection lost, configuration
2196 >=0: on success, the number of characters that were actually
2197 read and placed in the dest buffer, not counting the trailing
2202 Outputs the character c to the communication line. If the
2203 operation fails to complete within two seconds, this function
2204 returns -1. Otherwise it returns the number of characters
2205 actually written to the tty (0 or 1). This function should only
2206 be used for interactive, character-mode operations, like
2207 terminal connection, script execution, dialer i/o, where the
2208 overhead of the signals and alarms does not create a bottleneck.
2209 (THIS DESCRIPTION NEEDS IMPROVEMENT -- If the operation fails
2210 within a "certain amount of time"... which might be dependent on
2211 the communication method, speed, etc. In particular,
2212 flow-control deadlocks must be accounted for and broken out of
2213 to prevent the program from hanging indefinitely, etc.)
2216 ttol(s,n) int n; char *s;
2217 Kermit's packet writer. Writes the n characters of the string
2218 pointed to to by s. NOTE: It is ttol's responsibility to write
2219 ALL of the characters, not just some of them. Returns:
2220 -1: on a possibly correctable error (so it can be retried).
2221 -3: on a fatal error, e.g. connection lost.
2222 >=0: on success, the actual number of characters written (the
2223 specific number is not actually used for anything).
2226 ttopen(ttname,lcl,modem,timo) char *ttname; int *lcl, modem,
2228 Opens a tty device, if it is not already open. ttopen must check
2229 to make sure the SAME device is not already open; if it is,
2230 ttopen returns successfully without doing anything. If a
2231 DIFFERENT device is currently open, ttopen() must call ttclos()
2232 to close it before opening the new one.
2237 character string - device name or network host name.
2240 If called with lcl < 0, sets value of lcl as
2242 0: the terminal named by ttname is the job's
2243 controlling terminal.
2244 1: the terminal named by ttname is not the job's
2245 controlling terminal.
2246 If the device is already open, or if the requested
2247 device can't be opened, then lcl remains (and is
2251 Less than zero: this is the negative of the network
2252 type, and ttname is a network host name. Network
2253 types (from [134]ckcnet.h:
2255 NET_TCPB 1 TCP/IP Berkeley (socket) (implemented in [135]ckutio.c)
2256 NET_TCPA 2 TCP/IP AT&T (streams) (not yet implemented)
2257 NET_DEC 3 DECnet (not yet implemented)
2259 Zero or greater: ttname is a terminal device name.
2260 Zero means a direct connection (don't use modem
2261 signals). Positive means use modem signals depending
2262 on the current setting of ttcarr (see ttscarr()).
2265 > 0: number of seconds to wait for open() to return
2267 <=0: no timer, wait forever (e.g. for incoming
2269 For real tty devices, ttopen() attempts to gain
2270 exclusive accesss to the tty device, for example in
2271 UNIX by creating a "lockfile" (in other operating
2272 systems, like VMS, exclusive accesss probably
2273 requires no special action).
2276 Copies its arguments and the tty file descriptor to global
2277 variables that are available to the other tty-related
2278 functions, with the lcl value altered as described above.
2279 Gets all parameters and settings associated with the line
2280 and puts them in a global area, so that they can be
2281 restored by ttres(), e.g. when the device is closed.
2285 -5: if device is in use
2286 -4: if accesss to device is denied
2287 -3: if accesss to lock mechanism denied
2288 -2: upon timeout waiting for device to open
2292 ttpkt(speed,flow,parity) long speed; int flow, parity;
2293 Puts the currently open tty device into the appropriate modes
2294 for transmitting and receiving Kermit packets.
2299 if speed > -1, and the device is a true tty device,
2300 and Kermit is in local mode, ttpkt also sets the
2304 if in the range 0-3, ttpkt selects the corresponding
2305 type of flow control. Currently 0 is defined as no
2306 flow control, 1 is Xon/Xoff, and no other types are
2307 defined. If (and this is a horrible hack, but it
2308 goes back many years and will be hard to eradicate)
2309 flow is 4, then the appropriate tty modes are set
2310 for modem dialing, a special case in which we talk
2311 to a modem-controlled line without requiring
2312 carrier. If flow is 5, then we require carrier.
2315 This is simply copied into a global variable so that
2316 other functions (like ttinl, ttinc, etc) can use it.
2319 Copies its arguments to global variables, flushes the
2320 terminal device input buffer.
2328 Enables the given type of flow control on the open serial
2329 communications device immediately. Arguments are the FLO_xxx
2330 values from ckcdeb.h, except FLO_DIAL, FLO_DIAX, or FLO_AUTO,
2331 which are not actual flow-control types. Returns 0 on success,
2337 Returns a pointer to an array of longs, or NULL on failure. On
2338 success, element 0 of the array contains number, n, indicating
2339 how many follow. Elements 1-n are serial speeds, expressed in
2340 bits per second, that are legal on this platform. The user
2341 interface may use this list to construct a menu, keyword table,
2344 #endif /* TTSPDLIST */
2348 Restores the tty device to the modes and settings that were in
2349 effect at the time it was opened (see ttopen). Returns:
2354 ttruncmd(string) char * string;
2355 Runs the given command on the local system, but redirects its
2356 input and output to the communication (SET LINE, SET PORT, or
2357 SET HOST) device. Returns:
2362 ttscarr(carrier) int carrier;
2363 Copies its argument to a variable that is global to the other
2364 tty-related functions, and then returns it. The values for
2365 carrier are defined in ckcdeb.h: CAR_ON, CAR_OFF, CAR_AUTO.
2366 ttopen(), ttpkt(), and ttvt() use this variable when deciding
2367 how to open the tty device and what modes to select. The
2370 CAR_OFF: Ignore carrier at all times.
2371 CAR_ON: Require carrier at all times, except when dialing. This means,
2372 for example, that ttopen() could hang forever waiting for carrier if it
2374 CAR_AUTO: If the modem type is zero (i.e. the connection is direct),
2375 this is the same as CAR_OFF. If the modem type is positive, then heed
2376 carrier during CONNECT (ttvt mode), but ignore it at other times
2377 (packet mode, during SET LINE, etc). Compatible with pre-5A versions of
2378 C-Kermit. This should be the default carrier mode.
2380 Kermit's DIAL command ignores the carrier setting, but ttopen(),
2381 ttvt(), and ttpkt() all honor the carrier option in effect at
2382 the time they are called. None of this applies to remote mode
2383 (the tty device is the job's controlling terminal) or to network
2384 host connections (modem type is negative).
2388 Sends a BREAK signal on the tty device. On a real tty device,
2389 send a real BREAK lasting approximately 275 milliseconds. If
2390 this is not possible, simulate a BREAK by (for example) dropping
2391 down some very low baud rate, like 50, and sending a bunch of
2392 null characters. On a network connection, do the appropriate
2393 network protocol for BREAK. Returns:
2399 Like ttsndb(), but sends a "Long BREAK" (approx 1.5 seconds).
2400 For network connections, it is identical to ttsndb(). Currently,
2401 this function is used only if CK_LBRK is defined (as it is for
2405 ttsspd(cps) int cps;
2406 For serial devices only, set the device transmission speed to
2407 (note carefully) TEN TIMES the argument. The argument is in
2408 characters per second, but transmission speeds are in bits per
2409 second. cps are used rather than bps because high speeds like
2410 38400 are not expressible in a 16-bit int but longs cannot be
2411 used because keyword-table values are ints and not longs. If the
2412 argument is 7, then the bps is 75, not 70. If the argument is
2413 888, this is a special code for 75/1200 split-speed operation
2414 (75 bps out, 1200 bps in). Returns:
2415 -1: on error, meaning the requested speed is not valid or
2417 >=0: on success (don't try to use this value for anything).
2420 ttvt(speed,flow) long speed; int flow;
2421 Puts the currently open tty device into the appropriate modes
2422 for terminal emulation. The arguments are interpreted as in
2423 ttpkt(). Side effects: ttvt() stores its arguments in global
2424 variables, and sets a flag that it has been called so that
2425 subsequent calls can be ignored so long as the arguments are the
2426 same as in the last effective call. Other functions, such as
2427 ttopen(), ttclose(), ttres(), ttvt(), etc, that change the tty
2428 device in any way must unset this flag. In UNIX Kermit, this
2429 flag is called tvtflg.
2432 ttwmdm(mdmsig,timo) int mdmsig, timo;
2433 Waits up to timo seconds for all of the given modem signals to
2434 appear. mdmsig is a bit mask, in which a bit is on (1) or off
2435 (0) according to whether the corresponding signal is to be
2436 waited for. These symbols are defined in ckcdeb.h:
2437 BM_CTS (bit 0) means wait for Clear To Send
2438 BM_DSR (bit 1) means wait for Data Set Ready
2439 BM_DCD (bit 2) means wait for Carrier Detect
2441 -3: Not implemented.
2442 -2: This line does not have modem control.
2443 -1: Timeout: time limit exceeded before all signals were
2448 ttxin(n,buf) int n; CHAR *buf;
2449 Reads x characters from the tty device into the specified buf,
2450 stripping parity if parity is not none. This call waits forever,
2451 there is no timeout. This function is designed to be called only
2452 when you know that at least x characters are waiting to be read
2453 (as determined, for example, by ttchk()). This function should
2454 use the same buffer as ttinc().
2457 txbufr(timo) int timo;
2458 Reads characters into the internal communications input buffer.
2459 timo is a timeout interval, in seconds. 0 means no timeout, wait
2460 forever. Called by ttinc() (and possibly ttxin() and ttinl())
2461 when the communications input buffer is empty. The buffer should
2462 be called ttxbuf[], its length is defined by the symbol TXBUFL.
2463 The global variable txbufn is the number of characters available
2464 to be read from ttxbuf[], and txbufp is the index of the next
2465 character to be read. Should not be called if txbufn > 0, in
2466 which case the buffer does not need refilling. This routine
2468 -2: Communications disconnect
2470 >=0: A character (0 - 255) On success, the first character that
2471 was read, with the variables txbufn and txbufp set appropriately
2472 for any remaining characters.
2473 NOTE: Currently this routine is used internally only by the UNIX
2474 and VMS versions. The aim is to make it available to all
2475 versions so there is one single coherent and efficient way of
2476 reading from the communications device or network.
2478 4.E.2.6. Miscellaneous system-dependent functions
2482 Returns a pointer, s, to the current date-and-time string in s.
2483 This string must be in the fixed-field format associated with
2484 the C runtime asctime() function, like: "Sun Sep 16 13:23:45
2485 1973\n" so that callers of this function can extract the
2486 different fields. The pointer value is filled in by ztime, and
2487 the data it points to is not safe, so should be copied to a safe
2488 place before use. ztime() has no return value. As a side effect,
2489 this routine can also fill in the following two external
2490 variables (which must be defined in the system-dependent modules
2492 long ztusec: Fraction of seconds of clock time, microseconds.
2493 long ztmsec: Fraction of seconds of clock time, milliseconds.
2494 If these variables are not set by zstime(), they remain at their
2495 initial value of -1L.
2499 Returns the current value of the elapsed time counter in seconds
2500 (see rtimer), or 0 on any kind of error.
2505 Returns the current value of the elapsed time counter in
2506 seconds, as a floating point number, capable of representing not
2507 only whole seconds, but also the fractional part, to the
2508 millisecond or microsecond level, whatever precision is
2509 available. Requires a function to get times at subsecond
2510 precision, as well as floating-point support. That's why it's
2513 #endif /* GFTIMER */
2517 Sleeps (pauses, does nothing) for m milliseconds (a millisecond
2518 is one thousandth of a second). Returns:
2524 Sets the elapsed time counter to zero. If you want to time how
2525 long an operation takes, call rtimer() when it starts and gtimer
2526 when it ends. rtimer() has no return value.
2531 Sets the elapsed time counter to zero. If you want to time how
2532 long an operation takes, call rftimer() when it starts and
2533 gftimer when it ends. rftimer() has no return value. Note:
2534 rftimer() is to be used with gftimer() and rtimer() is to be
2535 used with gtimer(). See the rftimer() description.
2537 #endif /* GFTIMER */
2541 Does whatever needs doing upon program start. In particular, if
2542 the program is running in any kind of privileged mode, turns off
2543 the privileges (see priv_ini()). Returns:
2549 Does whatever needs doing upon program exit. Returns:
2555 Suspends the Kermit process, puts it in the background so it can
2556 be continued ("foregrounded") later. Returns:
2557 -1: if this function is not supported.
2560 [ [136]Contents ] [ [137]C-Kermit ] [ [138]Kermit Home ]
2562 4.F. Group F: Network Support
2564 As of version 5A, C-Kermit includes support for several networks.
2565 Originally, this was just worked into the ttopen(), ttclos(), ttinc(),
2566 ttinl(), and similar routines in [139]ckutio.c. But this made it
2567 impossible to share this code with non-UNIX versions, like VMS, AOS/VS,
2568 OS/2, etc. So as of edit 168, network code has been separated out into
2569 its own module and header file, ckcnet.c and ckcnet.h:
2571 [140]ckcnet.h: Network-related symbol definitions.
2572 [141]ckcnet.c: Network i/o (TCP/IP, X.25, etc), shared by most
2574 [142]cklnet.c: Network i/o (TCP/IP, X.25, etc) specific to Stratus
2577 The routines and variables in these modules fall into two categories:
2579 1. Support for specific network packages like SunLink X.25 and TGV
2581 2. support for specific network virtual terminal protocols like CCITT
2582 X.3 and TCP/IP Telnet.
2584 Category (1) functions are analogs to the tt*() functions, and have
2585 names like netopen, netclos, nettinc, etc. Group A-D modules do not
2586 (and must not) know anything about these functions -- they continue to
2587 call the old Group E functions (ttopen, ttinc, etc). Category (2)
2588 functions are protocol specific and have names prefixed by a protocol
2589 identifier, like tn for telnet x25 for X.25.
2591 ckcnet.h contains prototypes for all these functions, as well as symbol
2592 definitions for network types, protocols, and network- and protocol-
2593 specific symbols, as well as #includes for the header files necessary
2594 for each network and protocol.
2596 The following functions are to be provided for networks that do not use
2597 normal system i/o (open, read, write, close):
2601 To be called from within ttopen() when a network connection is
2602 requested. Calling conventions and purpose same as Group E
2607 To be called from within ttclos() when a network connection is
2608 being closed. Calling conventions and purpose same as Group E
2613 To be called from within ttchk(). Calling conventions and
2614 purpose same as Group E ttchk().
2618 To be called from within ttflui(). Calling conventions and
2619 purpose same as Group E ttflui().
2623 To send a network break (attention) signal. Calling conventions
2624 and purpose same as Group E ttsndbrk().
2628 To get a character from the network. Calling conventions same as
2633 Send a "character" (byte) to the network. Calling conventions
2634 same as Group E ttoc().
2638 Send a "line" (sequence of bytes) to the network. Calling
2639 conventions same as Group E ttol().
2641 Conceivably, some systems support network connections simply by letting
2642 you open a device of a certain name and letting you do i/o to it.
2643 Others (like the Berkeley sockets TCP/IP library on UNIX) require you
2644 to open the connection in a special way, but then do normal i/o (read,
2645 write). In such a case, you would use netopen(), but you would not use
2646 nettinc, nettoc, etc.
2648 VMS TCP/IP products have their own set of functions for all network
2649 operations, so in that case the full range of netxxx() functions is
2652 The technique is to put a test in each corresponding ttxxx() function
2653 to see if a network connection is active (or is being requested), test
2654 for which kind of network it is, and if necessary route the call to the
2655 corresponding netxxx() function. The netxxx() function must also
2656 contain code to test for the network type, which is available via the
2657 global variable ttnet.
2659 [ [143]Contents ] [ [144]C-Kermit ] [ [145]Kermit Home ]
2661 4.F.1. Telnet Protocol
2663 (This section needs a great deal of updating...)
2665 As of edit 195, Telnet protocol is split out into its own files, since
2666 it can be implemented in remote mode, which does not have a network
2669 [146]ckctel.h: Telnet protocol symbol definitions.
2670 [147]ckctel.c: Telnet protocol.
2672 The Telnet protocol is supported by the following variables and
2676 Nonzero if telnet protocol initialized, zero otherwise.
2680 Initialize the telnet protocol (send initial options).
2684 Send a telnet option.
2688 Receive and act on a telnet option from the remote.
2692 Send terminal type using telnet protocol.
2696 (To be filled in...) See the [148]source file
2698 4.F.3. HTTP Protocol
2700 (To be filled in...)
2702 4.F.4. X.25 Networks
2704 These routines were written SunLink X.25 and have since been adapted to
2705 at least on one other: IBM AIXLink/X.25.
2709 Reads and prints X.25 diagnostics
2713 X.25 out of band signal handler
2717 Sends X.25 interrupt packet
2721 Resets X.25 virtual circuit
2725 Clear X.25 virtual circuit
2741 Reads n characters from X.25 circuit.
2745 Read a Kermit packet from X.25 circuit.
2747 [ [149]Contents ] [ [150]C-Kermit ] [ [151]Kermit Home ]
2749 4.F.5. Adding New Network Types
2751 Example: Adding support for IBM X.25 and Hewlett Packard X.25. First,
2752 add new network type symbols for each one. There are already some
2753 network types defined for other X.25 packages:
2755 NET_SX25 is the network-type ID for SunLink X.25.
2756 NET_VX25 is the network-type ID for VOS X.25.
2758 So first you should new symbols for the new network types, giving them
2759 the next numbers in the sequence, e.g.:
2761 #define NET_HX25 11 /* Hewlett-Packard X.25 */
2762 #define NET_IX25 12 /* IBM X.25 */
2764 This is in ckcnet.h.
2766 Then we need symbols to say that we are actually compiling in the code
2767 for these platforms. These would be defined on the cc command line:
2772 So we can build C-Kermit versions for AIX and HP-UX both with and
2773 without X.25 support (since not all AIX and IBM systems have the needed
2774 libraries, and so an executable that was linked with them might no
2787 And then use ANYX25 for code that is common to all of them, and IBMX25
2788 or HPX25 for code specific to IBM or HP.
2790 It might also happen that some code can be shared between two or more
2791 of these, but not the others. Suppose, for example, that you write code
2792 that applies to both IBM and HP, but not Sun or VOS X.25. Then you add
2793 the following definition to ckcnet.h:
2803 #endif /* HPORIBMX25 */
2805 You can NOT use constructions like "#if defined (HPX25 || IBMX25)";
2806 they are not portable.
2808 [ [152]Contents ] [ [153]C-Kermit ] [ [154]Kermit Home ]
2810 4.G. Group G: Formatted Screen Support
2812 So far, this is used only for the fullscreen local-mode file transfer
2813 display. In the future, it might be extended to other uses. The
2814 fullscreen display code is in and around the routine screenc() in
2817 In the UNIX version, we use the curses library, plus one call from the
2818 termcap library. In other versions (OS/2, VMS, etc) we insert dummy
2819 routines that have the same names as curses routines. So far, there are
2820 two methods for simulating curses routines:
2822 1. In VMS, we use the Screen Management Library (SMG), and insert
2823 stubs to convert curses calls into SMG calls.
2824 2. In OS/2, we use the MYCURSES code, in which the stub routines
2825 actually emit the appropriate escape sequences themselves.
2827 Here are the stub routines:
2830 tgetent(char *buf, char *term)
2831 Arguments are ignored. Returns 1 if the user has a supported
2832 terminal type, 0 otherwise. Sets a global variable (for example,
2833 "isvt52" or "isdasher") to indicate the terminal type.
2836 move(int row, int col)
2837 Sends the escape sequence to position the cursor at the
2838 indicated row and column. The numbers are 0-based, e.g. the home
2843 Sends the escape sequence to clear the screen.
2847 Sends the escape sequence to clear from the current cursor
2848 position to the end of the line.
2850 In the MYCURSES case, code must be added to each of the last three
2851 routines to emit the appropriate escape sequences for a new terminal
2854 clearok(curscr), wrefresh()
2855 In real curses, these two calls are required to refresh the
2856 screen, for example after it was fractured by a broadcast
2857 message. These are useful only if the underlying screen
2858 management service keeps a copy of the entire screen, as curses
2859 and SMG do. C-Kermit does not do this itself.
2861 [ [156]Contents ] [ [157]C-Kermit ] [ [158]Kermit Home ]
2863 4.H. Group H: Pseudoterminal Support
2865 (To be filled in...) But see: [159]these comments, and the source files
2866 [160]ckupty.h and [161]ckupty.c.
2868 4.I. Group I: Security
2870 (To be filled in...) Meanwhile, see [162]security.html.
2872 [ [163]Contents ] [ [164]C-Kermit ] [ [165]Kermit Home ]
2874 APPENDIX I. FILE PERMISSIONS
2876 I.1. Format of System-Dependent File Permissions in A-Packets
2878 The format of this field (the "," attribute) is interpreted according
2879 to the System ID ("." Attribute).
2881 For UNIX (System ID = U1), it's the familiar 3-digit octal number, the
2882 low-order 9 bits of the filemode: Owner, Group, World, e.g. 660 =
2883 read/write accesss for owner and group, none for world, recorded as a
2884 3-digit octal string. High-order UNIX permission bits are not
2887 For VMS (System ID = D7), it's a 4-digit hex string, representing the
2888 16-bit file protection WGOS fields (World,Group,Owner,System), in that
2889 order (which is the reverse of how they're shown in a directory
2890 listing); in each field, Bit 0 = Read, 1 = Write, 2 = Execute, 3 =
2891 Delete. A bit value of 0 means permission is granted, 1 means
2892 permission is denied. Sample:
2894 r-01-00-^A/!FWERMIT.EXE'"
2895 s-01-00-^AE!Y/amd/watsun/w/fdc/new/wermit.exe.DV
2896 r-02-01-^A]"A."D7""B8#119980101 18:14:05!#8531&872960,$A20B-!7(#512@ #.Y
2899 A VMS directory listing shows the file's protection as (E,RWED,RED,RE)
2900 which really means (S=E,O=RWED,G=RED,W=RE), which is reverse order from
2901 the internal storage, so (RE,RED,RWED,E). Now translate each letter to
2902 its corresponding bit:
2904 RE=0101, RED=1101, RWED=1111, E=0010
2906 Now reverse the bits:
2908 RE=1010, RED=0010, RWED=0000, E=1101
2910 This gives the 16-bit quantity:
2914 This is the internal representation of the VMS file permission; in hex:
2918 as shown in the sample packet above.
2920 The VMS format probably would also apply to RSX or any other FILES-11
2923 I.2. Handling of Generic Protection
2925 To be used when the two systems are different (and/or do not recognize
2926 or understand each other's local protection codes).
2928 First of all, the book is wrong. This should not be the World
2929 protection, but the Owner protection. The other fields should be set
2930 according to system defaults (e.g. UNIX umask, VMS default protection,
2931 etc), except that no non-Owner field should give more permissions than
2934 [ [166]Top ] [ [167]Contents ] [ [168]C-Kermit Home ] [ [169]Kermit
2936 __________________________________________________________________
2939 C-Kermit Program Logic Manual / [170]The Kermit Project /
2940 [171]kermit@columbia.edu / 30 June 2011
2944 1. http://www.columbia.edu/
2945 2. mailto:kermit@columbia.edu
2946 3. http://www.columbia.edu/kermit/index.html
2947 4. http://www.columbia.edu/kermit/k95.html
2948 5. http://www.columbia.edu/kermit/ckermit.html
2949 6. http://www.columbia.edu/kermit/ckscripts.html
2950 7. http://www.columbia.edu/kermit/current.html
2951 8. http://www.columbia.edu/kermit/whatsnew.html
2952 9. http://www.columbia.edu/kermit/ckfaq.html
2953 10. http://www.columbia.edu/kermit/support.html
2954 11. http://www.columbia.edu/kermit/
2955 12. http://www.columbia.edu/kermit/ckcplm.html
2956 13. http://www.columbia.edu/kermit/ckcplm.html#x1
2957 14. http://www.columbia.edu/kermit/ckcplm.html#x2
2958 15. http://www.columbia.edu/kermit/ckcplm.html#x3
2959 16. http://www.columbia.edu/kermit/ckcplm.html#x4
2960 17. http://www.columbia.edu/kermit/ckcplm.html#x4.A
2961 18. http://www.columbia.edu/kermit/ckcplm.html#x4.B
2962 19. http://www.columbia.edu/kermit/ckcplm.html#x4.C
2963 20. http://www.columbia.edu/kermit/ckcplm.html#x4.D
2964 21. http://www.columbia.edu/kermit/ckcplm.html#x4.E
2965 22. http://www.columbia.edu/kermit/ckcplm.html#x4.F
2966 23. http://www.columbia.edu/kermit/ckcplm.html#x4.G
2967 24. http://www.columbia.edu/kermit/ckcplm.html#x4.H
2968 25. http://www.columbia.edu/kermit/ckcplm.html#x4.I
2969 26. http://www.columbia.edu/kermit/ckcplm.html#xa1
2970 27. http://www.amazon.com/gp/product/0932376886?ie=UTF8&tag=aleidmoreldom-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=0932376886
2971 28. http://www.columbia.edu/kermit/ckcplm.html#contents
2972 29. http://www.columbia.edu/kermit/vax_11-750.jpg
2973 30. http://www.columbia.edu/cu/computinghistory/hermit.html
2974 31. http://www.columbia.edu/kermit/cudocs/ilosetup.html
2975 32. ftp://kermit.columbia.edu/kermit/f/ckc04e.txt
2976 33. ftp://kermit.columbia.edu/kermit/f/ckc04f.txt
2977 34. ftp://kermit.columbia.edu/kermit/f/ckc168.txt
2978 35. ftp://kermit.columbia.edu/kermit/f/ckc178.txt
2979 36. ftp://kermit.columbia.edu/kermit/f/ckc188.txt
2980 37. ftp://kermit.columbia.edu/kermit/f/ckc189.txt
2981 38. ftp://kermit.columbia.edu/kermit/f/ckc192.txt
2982 39. ftp://kermit.columbia.edu/kermit/f/ckc197.txt
2983 40. ftp://kermit.columbia.edu/kermit/f/ckc200.txt
2984 41. ftp://kermit.columbia.edu/kermit/f/ckc211.txt
2985 42. ftp://kermit.columbia.edu/kermit/f/ckc300.txt
2986 43. http://www.columbia.edu/kermit/ckcplm.html#contents
2987 44. http://www.columbia.edu/kermit/ckermit.html
2988 45. http://www.columbia.edu/kermit/index.html
2989 46. ftp://kermit.columbia.edu/kermit/c-kermit/ckcpro.w
2990 47. http://www.columbia.edu/kermit/ckcplm.html#contents
2991 48. http://www.columbia.edu/kermit/ckermit.html
2992 49. http://www.columbia.edu/kermit/index.html
2993 50. http://www.columbia.edu/kermit/ckcplm.html#x3.2
2994 51. http://www.columbia.edu/kermit/ckcplm.html#contents
2995 52. http://www.columbia.edu/kermit/ckermit.html
2996 53. http://www.columbia.edu/kermit/index.html
2997 54. http://www.columbia.edu/kermit/ckcplm.html#x4.A
2998 55. http://www.columbia.edu/kermit/ckcplm.html#contents
2999 56. http://www.columbia.edu/kermit/ckermit.html
3000 57. http://www.columbia.edu/kermit/index.html
3001 58. http://www.columbia.edu/kermit/ckcplm.html#contents
3002 59. http://www.columbia.edu/kermit/ckermit.html
3003 60. http://www.columbia.edu/kermit/index.html
3004 61. http://www.columbia.edu/kermit/ckcplm.html#contents
3005 62. http://www.columbia.edu/kermit/ckermit.html
3006 63. http://www.columbia.edu/kermit/index.html
3007 64. ftp://kermit.columbia.edu/kermit/c-kermit/ckclib.h
3008 65. ftp://kermit.columbia.edu/kermit/c-kermit/ckclib.c
3009 66. http://www.columbia.edu/kermit/ckcplm.html#x3.1
3010 67. http://www.columbia.edu/kermit/ckcplm.html#contents
3011 68. http://www.columbia.edu/kermit/ckermit.html
3012 69. http://www.columbia.edu/kermit/index.html
3013 70. ftp://kermit.columbia.edu/kermit/c-kermit/ckcsym.h
3014 71. ftp://kermit.columbia.edu/kermit/c-kermit/ckcasc.h
3015 72. ftp://kermit.columbia.edu/kermit/c-kermit/ckcsig.h
3016 73. ftp://kermit.columbia.edu/kermit/c-kermit/ckcdeb.h
3017 74. ftp://kermit.columbia.edu/kermit/c-kermit/ckcker.h
3018 75. ftp://kermit.columbia.edu/kermit/c-kermit/ckcxla.h
3019 76. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
3020 77. ftp://kermit.columbia.edu/kermit/c-kermit/ckcpro.w
3021 78. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfns.c
3022 79. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfn2.c
3023 80. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfn3.c
3024 81. http://www.columbia.edu/kermit/ckcplm.html#x4.B
3025 82. http://www.columbia.edu/kermit/ckcplm.html#x4.E
3026 83. http://www.columbia.edu/kermit/ckcplm.html#x4.D
3027 84. http://www.columbia.edu/kermit/ckcplm.html#contents
3028 85. http://www.columbia.edu/kermit/ckermit.html
3029 86. http://www.columbia.edu/kermit/index.html
3030 87. http://www.columbia.edu/kermit/ckcplm.html#x4.B
3031 88. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.c
3032 89. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.h
3033 90. ftp://kermit.columbia.edu/kermit/c-kermit/ckcxla.h
3034 91. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.h
3035 92. ftp://kermit.columbia.edu/kermit/c-kermit/ckmxla.h
3036 93. ftp://kermit.columbia.edu/kermit/c-kermit/ck?xla
3037 94. ftp://kermit.columbia.edu/kermit/c-kermit/ckcuni.h
3038 95. ftp://kermit.columbia.edu/kermit/c-kermit/ckcuni.c
3039 96. http://www.columbia.edu/kermit/ckcplm.html#contents
3040 97. http://www.columbia.edu/kermit/ckermit.html
3041 98. http://www.columbia.edu/kermit/index.html
3042 99. http://www.columbia.edu/kermit/ckcplm.html#x4.B
3043 100. ftp://kermit.columbia.edu/kermit/c-kermit/ckucmd.h
3044 101. ftp://kermit.columbia.edu/kermit/c-kermit/ckucmd.c
3045 102. http://www.columbia.edu/kermit/ckcplm.html#x4.E
3046 103. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusr.h
3047 104. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusr.c
3048 105. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus2.c
3049 106. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus3.c
3050 107. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus4.c
3051 108. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusy.c
3052 109. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusx.c
3053 110. ftp://kermit.columbia.edu/kermit/c-kermit/ckuver.h
3054 111. ftp://kermit.columbia.edu/kermit/c-kermit/ckuscr.c
3055 112. ftp://kermit.columbia.edu/kermit/c-kermit/ckudia.c
3056 113. ftp://kermit.columbia.edu/kermit/c-kermit/ckucon.c
3057 114. ftp://kermit.columbia.edu/kermit/c-kermit/ckucns.c
3058 115. http://www.columbia.edu/kermit/ckcplm.html#x4.E
3059 116. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
3060 117. http://www.columbia.edu/kermit/ckcplm.html#contents
3061 118. http://www.columbia.edu/kermit/ckermit.html
3062 119. http://www.columbia.edu/kermit/index.html
3063 120. ftp://kermit.columbia.edu/kermit/c-kermit/ckufio.c
3064 121. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3065 122. ftp://kermit.columbia.edu/kermit/c-kermit/ckusig.c
3066 123. ftp://kermit.columbia.edu/kermit/c-kermit/ckvfio.c
3067 124. ftp://kermit.columbia.edu/kermit/c-kermit/ckusig.c
3068 125. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
3069 126. http://www.columbia.edu/kermit/ckcplm.html#contents
3070 127. http://www.columbia.edu/kermit/ckermit.html
3071 128. http://www.columbia.edu/kermit/index.html
3072 129. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3073 130. ftp://kermit.columbia.edu/kermit/c-kermit/ckvtio.c
3074 131. http://www.columbia.edu/kermit/ckcplm.html#x2
3075 132. http://www.columbia.edu/kermit/ckcplm.html#xa1
3076 133. http://www.columbia.edu/kermit/ckuins.html
3077 134. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.h
3078 135. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3079 136. http://www.columbia.edu/kermit/ckcplm.html#contents
3080 137. http://www.columbia.edu/kermit/ckermit.html
3081 138. http://www.columbia.edu/kermit/index.html
3082 139. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3083 140. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.h
3084 141. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.c
3085 142. ftp://kermit.columbia.edu/kermit/c-kermit/cklnet.c
3086 143. http://www.columbia.edu/kermit/ckcplm.html#contents
3087 144. http://www.columbia.edu/kermit/ckermit.html
3088 145. http://www.columbia.edu/kermit/index.html
3089 146. ftp://kermit.columbia.edu/kermit/c-kermit/ckctel.h
3090 147. ftp://kermit.columbia.edu/kermit/c-kermit/ckctel.c
3091 148. ftp://kermit.columbia.edu/kermit/c-kermit/ckcftp.c
3092 149. http://www.columbia.edu/kermit/ckcplm.html#contents
3093 150. http://www.columbia.edu/kermit/ckermit.html
3094 151. http://www.columbia.edu/kermit/index.html
3095 152. http://www.columbia.edu/kermit/ckcplm.html#contents
3096 153. http://www.columbia.edu/kermit/ckermit.html
3097 154. http://www.columbia.edu/kermit/index.html
3098 155. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusx.c
3099 156. http://www.columbia.edu/kermit/ckcplm.html#contents
3100 157. http://www.columbia.edu/kermit/ckermit.html
3101 158. http://www.columbia.edu/kermit/index.html
3102 159. http://www.columbia.edu/kermit/ckermit90.html#LooseEnd
3103 160. ftp://kermit.columbia.edu/kermit/f/ckupty.h
3104 161. ftp://kermit.columbia.edu/kermit/f/ckupty.c
3105 162. http://www.columbia.edu/kermit/security.html
3106 163. http://www.columbia.edu/kermit/ckcplm.html#contents
3107 164. http://www.columbia.edu/kermit/ckermit.html
3108 165. http://www.columbia.edu/kermit/index.html
3109 166. http://www.columbia.edu/kermit/ckcplm.html#top
3110 167. http://www.columbia.edu/kermit/ckcplm.html#contents
3111 168. http://www.columbia.edu/kermit/ckermit.html
3112 169. http://www.columbia.edu/kermit/index.html
3113 170. http://www.columbia.edu/kermit/index.html
3114 171. mailto:kermit@columbia.edu