2 C-Kermit Program Logic Manual
8 As of: C-Kermit 8.0.211, 10 April 2004
9 This page last updated: Sat Apr 10 16:45:30 2004 (New York USA Time)
11 IF YOU ARE READING A PLAIN-TEXT version of this document, note that
12 this file is a plain-text dump of a Web page. You can visit the
13 original (and possibly more up-to-date) Web page here:
15 [3]http://www.columbia.edu/kermit/ckcplm.html
17 [ [4]C-Kermit Home ] [ [5]Kermit Home ]
18 ________________________________________________________________________
24 3. [8]SOURCE CODE PORTABILITY AND STYLE
26 4.A. [10]Group A: Library Routines
27 4.B. [11]Group B: Kermit File Transfer
28 4.C. [12]Group C: Character-Set Conversion
29 4.D. [13]Group D: User Interface
30 4.E. [14]Group E: Platform-Dependent I/O
31 4.F. [15]Group F: Network Support
32 4.G. [16]Group G: Formatted Screen Support
33 4.H. [17]Group H: Pseudoterminal Support
34 4.I. [18]Group I: Security
35 I. [19]APPENDIX I: FILE PERMISSIONS
36 ________________________________________________________________________
40 The Kermit Protocol is specified in the book Kermit, A File Transfer
41 Protocol by Frank da Cruz, Digital Press / Butterworth Heinemann,
42 Newton, MA, USA (1987), 379 pages, ISBN 0-932376-88-6. It is assumed
43 the reader is familiar with the Kermit protocol specification.
45 This file describes the relationship among the modules and functions
46 of C-Kermit 5A and later, and other programming considerations.
47 C-Kermit is designed to be portable to any kind of computer that has a
48 C compiler. The source code is broken into many files that are grouped
49 according to their function, as shown in the [20]Contents.
51 C-Kermit has seen constant development since 1985. Throughout its
52 history, there has been a neverending tug-of-war among:
54 a. Functionality: adding new features, fixing bugs, improving
56 b. Adding support for new platforms.
57 c. "Buzzword 1.0 compliance".
59 The latter category is the most frustrating, since it generally
60 involves massive changes just to keep the software doing what it did
61 before in some new setting: e.g. the K&R-to-ANSIC conversion (which
62 had to be done, of course, without breaking K&R); Y2K (not a big deal
63 in our case); the many and varied UNIX and other API "standards";
66 [ [21]Contents ] [ [22]C-Kermit ] [ [23]Kermit Home ]
67 ________________________________________________________________________
71 C-Kermit source files begin with the two letters "ck", for example
72 ckutio.c. Filenames are kept short (6.3) for maximum portability and
73 (obviously I hope) do not contain spaces or more than one period. The
74 third character in the name denotes something about the function group
75 and the expected level of portability:
77 a General descriptive material and documentation (text)
78 b BOO file encoders and decoders (obsolete)
79 c All platforms with C compilers (*)
81 e Reserved for "ckermit" files, like ckermit.ini, ckermit2.txt
85 i Commodore Amiga (Intuition)
89 m Macintosh with Mac OS 1-9
90 n Microsoft Windows NT/2000/XP
91 o OS/2 and/or Microsoft Windows 9x/ME/NT/2000/XP
92 p Plan 9 from Bell Labs
94 r DEC PDP-11 with RSTS/E (never used, open for reassigment)
95 s Atari ST GEMDOS (last supported in version 5A(189))
96 t DEC PDP-11 with RT-11 (never used, open for reassigment)
97 u Unix-based operating systems (*)
99 w Wart (Lex-like preprocessor, platform independent)
109 (*) In fact there is little distinction between the ckc*.* and cku*.*
110 categories. It would make more sense for all cku*.* modules to be
111 ckc*.* ones, except ckufio.c, ckutio.c, ckucon.c, ckucns.c, and
112 ckupty.c, which truly are specific to Unix. The rest (ckuus*.c,
113 ckucmd.c, etc) are quite portable.
115 One hint before proceeding: functions are scattered all over the
116 ckc*.c and cku*.c modules, where function size has begun to take
117 precedence over the desirability of grouping related functions
118 together, the aim being to keep any particular module from growing
119 disproportionately large. The easiest way (in UNIX) to find out in
120 what source file a given function is defined is like this (where the
121 desired function is foo()...):
125 This works because the coding convention has been to make function
126 names always start on the left margin with their contents indented,
134 Also note the style for bracket placement. This allows
135 bracket-matching text editors (such as EMACS) to help you make sure
136 you know which opening bracket a closing bracket matches, particularly
137 when the opening bracket is above the visible screen, and it also
138 makes it easy to find the end of a function (search for '}' on the
141 Of course EMACS tags work nicely with this format too:
143 $ cd kermit-source-directory
146 Esc-X Visit-Tags-Table<CR><CR>
148 (but remember that the source file for ckcpro.c is [24]ckcpro.w!)
152 * Tabs should be set every 8 spaces, as on a VT100.
153 * All lines must no more than 79 characters wide after tab
155 * Note the distinction between physical tabs (ASCII 9) and the
156 indentation conventions, which are: 4 for block contents, 2 for
157 most other stuff (obviously this is not a portability issue, just
160 [ [25]Contents ] [ [26]C-Kermit ] [ [27]Kermit Home ]
161 ________________________________________________________________________
163 3. SOURCE CODE PORTABILITY AND STYLE
165 C-Kermit was designed in 1985 as a platform-independent replacement
166 for the earlier Unix Kermit. c-Kermit's design was expected to promote
167 portability, and judging from the number of platforms to which it has
168 been adapted since then, the model is effective, if not ideal
169 (obviously if we had it all to do over, we'd change a few things). To
170 answer the oft-repeated question: "Why are there so many #ifdefs?",
173 * Many of them are related to feature selection and program size,
174 and so need to be there anyway.
175 * Those that treat compiler, library, platform, header-file, and
176 similar differences have built up over time as hundreds of people
177 all over the world adapted C-Kermit to their particular
178 environments and sent back their changes. There might be more
179 politically-correct ways to achieve portability, but this one is
180 natural and proven. The basic idea is to introduce changes that
181 can be selected by defining a symbol, which, if not defined,
182 leaves the program exactly as it was before the changes.
183 * Although it might be possible to "clean up" the "#ifdef mess",
184 nobody has access to all the hundreds of platforms served by the
185 #ifdefs to check the results.
187 And to answer the second-most-oft-repeated question: "Why don't you
188 just use GNU autoconfig / automake / autowhatever instead of
189 hard-coding all those #ifdefs?" Answers:
191 * The GNU tools are not available on all the platforms where
192 C-Kermit must be built and I wouldn't necessarily trust them if
194 * Each platform is a moving target, so the tools themselves would
195 need to updated before Kermit could be updated.
196 * It would only add another layer of complexity to an already
198 * Conversion at this point would not be practical unless there was a
199 way to test the results on all the hundreds of platforms where
200 C-Kermit is supposed to build.
202 When writing code for the system-indendent C-Kermit modules, please
203 stick to the following coding conventions to ensure portability to the
204 widest possible variety of C preprocessors, compilers, and linkers, as
205 well as certain network and/or email transports. The same holds true
206 for many of the "system dependent" modules too; particularly the Unix
207 ones, since they must be buildable by a wide variety of compilers and
208 linkers, new and old.
210 This list does not purport to be comprehensive, and although some
211 items on it might seem far-fetched, they would not be listed unless I
212 had encountered them somewhere, some time. I wish I had kept better
213 records so I could cite specific platforms and compilers.
215 * Try to keep variable and function names unique within 6
216 characters, especially if they are used across modules, since 6 is
217 the maximum for some old linkers (actually, this goes back to
218 TOPS-10 and -20 and other old DEC OS's where C-Kermit never ran
219 anyway; a more realistic maximum is probably somewhere between 8
220 and 16). We know for certain that VAX C has a 31-character max
221 because it complains -- others might not complain, but just
222 silently truncate, thus folding two or more routines/variables
224 * Keep preprocessor symbols unique within 8 characters; that's the
225 max for some preprocessors (sorry, I can't give a specific
226 example, but in 1988 or thereabouts, I had to change character-set
227 symbols like TC_LATIN1 and TC_LATIN2 to TC_1LATIN and TC_2LATIN
228 because the digits were being truncated and ignored on a platform
229 where I actually had to build C-Kermit 5A; unfortunately I didn't
230 note which platform -- maybe some early Ultrix version?)
231 * Don't create preprocessor symbols, or variable or function names,
232 that start with underscore (_). These are usually reserved for
233 internal use by the compiler and header files.
234 * Don't put #include directives inside functions or { blocks }.
235 * Don't use the #if or #elif preprocessor constructions, only use
236 #ifdef, #ifndef, #define, #undef, and #endif.
237 * Put tokens after #endif in comment brackets, e.g.
239 * Don't indent preprocessor statements - # must always be first char
241 * Don't put whitespace after # in preprocessor statements.
242 * Don't use #pragma, even within #ifdefs -- it makes some
243 preprocessors give up.
244 * Same goes for #module, #if, etc - #ifdefs do NOT protect them.
245 * Don't use logical operators in preprocessor constructions.
246 * Avoid #ifdefs inside argument list to function calls (I can't
247 remember why this one is here, but probably needn't be; we do this
249 * Always cast strlen() in expressions to int:
250 if ((int)strlen(foo) < x)...
251 * Any variable whose value might exceed 16383 should be declared as
252 long, or if that is not possible, then as unsigned.
253 * Avoid typedefs; they might be portable but they are very confusing
254 and there's no way to test for their presence or absence at
255 compile time. Use preprocessor symbols instead if possible; at
256 least you can test their definitions.
257 * Unsigned long is not portable; use a preprocessor symbol (Kermit
258 uses ULONG for this).
259 * Long long is not portable. If you really need it, be creative.
260 * Similarly 1234LL is not portable, nor almost any other constant
261 modifier other than L.
262 * Unsigned char is not portable, use CHAR (a preprocessor symbol
263 defined in the Kermit header files) and always take precautions
264 against character signage (more about this [28]below).
265 * Don't use initializers with automatic arrays or structs: it's not
267 * Don't use big automatic arrays or structs in functions that might
268 be called recursively; some platforms have fixed-size stacks (e.g.
269 Windows 9x: 256K) and recursive functions crash with stack
270 overflow. Even when there is not a compiler limitation, this
271 causes memory to be consumed without bound, and can end up filling
273 * Don't assume that struct assignment performs a copy, or that it
275 * Don't use sizeof to get the size of an array; someone might come
276 along later and and change it from static to malloc'd. Always use
277 a symbol to refer to the array's size.
278 * Don't put prototypes for static functions into header files that
279 are used by modules that don't contain that function; the link
280 step can fail with unresolved references (e.g. on AOS/VS).
281 * Avoid the construction *++p (the order of evaluation varies; it
282 shouldn't but at least one compiler had a bug that made me include
284 * Don't use triple assignments, like a = b = c = 0; (or quadruple,
285 etc). Some compilers generate bad code for these, or crash, etc
286 (some version of DEC C as I recall).
287 * Some compilers don't allow structure members to have the same
288 names as other identifiers. Try to give structure members unique
290 * Don't assume anything about order of evaluation in boolean
291 expressions, or that they will stop early if a required condition
293 if (i > 0 && p[i-1] == blah)
294 can still dump core if i == 0 (hopefully this is not true of any
295 modern compiler, but I would not have said this if it did not
296 actually happen somewhere).
297 * Don't have a switch() statement with no cases (e.g. because of
298 #ifdefs); this is a fatal error in some compilers.
299 * Don't put lots of code in a switch case; move it out to a separate
300 function; some compilers run out of memory when presented with a
301 huge switch() statement -- it's not the number of cases that
302 matters; it's the overall amount of code.
303 * Some compilers might also limit the number of switch() cases, e.g.
305 * Don't put anything between "switch() {" and "case:" -- switch
306 blocks are not like other blocks.
307 * Don't jump into or out of switches.
308 * Don't make character-string constants longer than about 250 bytes.
309 Longer strings should be broken up into arrays of strings.
310 * Don't write into character-string constants (obviously). Even when
311 you know you are not writing past the end; the compiler or linker
312 might have put them into read-only and/or shared memory, and/or
313 coalesced multiple equal constants so if you change one you change
315 * Don't depend on '\r' being carriage return.
316 * Don't depend on '\n' being linefeed or for that matter any SINGLE
318 * Don't depend on '\r' and '\n' being different (e.g. as separate
320 * In other words, don't use \n or \r to stand for specific
321 characters; use \012 and \015 instead.
322 * Don't code for "buzzword 1.0 compliance", unless "buzzword" is K&R
323 and "1.0" is the first edition.
324 * Don't use or depend on anything_t (size_t, pid_t, etc), except
325 time_t, without #ifdef protection (time_t is the only one I've
326 found that is accepted everywhere). This is a tough one because
327 the same function might require (say) a size_t arg on one
328 platform, whereas size_t is unheard of on another; or worse, it
329 might require a totally different data type, like int or long or
330 some other typedef'd thing. It has often proved necessary to
331 define a symbol to stand for the type of a particular argument to
332 a particular library or system function to get around this
334 * Don't use or depend on internationalization ("i18n") features,
335 wchar_t, locales, etc, in portable code; they are not portable.
336 Anyway, locales are not the right model for Kermit's
337 multi-character-set support. Kermit does all character-set
338 conversion itself and does not use any external libraries or
340 * In particular, don't use any library functions that deal with wide
341 characters or Unicode in any form. These are not only nonportable,
342 but a constantly shifting target (e.g. the ones in glibc).
343 * Don't make any assumption about signal handler type. It can be
344 void, int, long, or anything else. Always declare signal handlers
345 as SIGTYP (see definition in ckcdeb.h and augment it if necessary)
346 and always use SIGRETURN at exit points from signal handlers.
347 * Signals should always be re-armed to be used again (this barely
348 scratches the surface -- the differences between BSD/V7 and System
349 V and POSIX signal handling are numerous, and some platforms do
350 not even support signals, alarms, or longjmps correctly or at all
351 -- avoid all of this if you can).
352 * On the other hand, don't assume that signals are disarmed after
353 being raised. In some platforms you have to re-arm them, in others
355 * Don't call malloc() and friends from a signal handler; don't do
356 anything but setting integer global variables in a signal handler.
357 * malloc() does not initialize allocated memory -- it never said it
358 did. Don't expect it to be all 0's.
359 * Did You Know: malloc() can succeed and the program can still dump
360 core later when it attempts to use the malloc'd memory? (This
361 happens when allocation is deferred until use and swap space is
363 * memset(), memmove(), and memcpy() are not portable, don't use them
364 without protecting them in ifdefs (we have USE_MEMCPY for this).
365 bzero()/bcopy() too, except we're guaranteed to have
366 bzero()/bcopy() when using the sockets library (not really). See
367 examples in the source.
368 * Don't assume that strncpy() stops on the first null byte -- most
369 versions always copy the number of bytes given in arg 3, padding
370 out with 0's and overwriting whatever was there before. Use
371 C-Kermit ckstrncpy() if you want predictable non-padding behavior,
372 guaranteed NUL-termination, and a useful return code.
373 * DID YOU KNOW.. that some versions of inet_blah() routines return
374 IP addresses in network byte order, while others return them local
375 machine byte order? So passing them to ntohs() or whatever is not
376 always the right thing to do.
377 * Don't use ANSI-format function declarations without #ifdef
378 CK_ANSIC, and always provide an #else for the non-ANSI case.
379 * Use the Kermit _PROTOTYP() macro for declaring function
380 prototypes; it works in both the ANSI and non-ANSI cases.
381 * Don't depend on any other ANSI preprocessor features like
382 "pasting" -- they are often missing or nonoperational.
383 * Don't assume any C++ syntax or semantics.
384 * Don't use // as a comment introducer. C is not C++.
385 * Don't declare a string as "char foo[]" in one module and "extern
386 char * foo" in another, or vice-versa: this causes core dumps.
387 * With compiler makers falling all over themselves trying to outdo
388 each other in ANSI strictness, it has become increasingly
389 necessary to cast EVERYTHING. This is increasingly true for char
390 vs unsigned char. We need to use unsigned chars if we want to deal
391 with 8-bit character sets, but most character- and string-oriented
392 APIs want (signed) char arguments, so explicit casts are
393 necessary. It would be nice if every compiler had a
394 -funsigned-char option (as gcc does), but they don't.
395 * a[x], where x is an unsigned char, can produce a wild memory
396 reference if x, when promoted to an int, becomes negative. Cast it
397 to (unsigned), even though it ALREADY IS unsigned.
398 * Be careful how you declare functions that have char or long
399 arguments; for ANSI compilers you MUST use ANSI declarations to
400 avoid promotion problems, but you can't use ANSI declarations with
401 non-ANSI compilers. Thus declarations of such functions must be
402 hideously entwined in #ifdefs. Example: latter:
403 int /* Put character in server command buffer */
408 #endif /* CK_ANSIC */
411 *srvptr = '\0'; /* Make sure buffer is null-terminated */
414 * Be careful how you return characters from functions that return
415 int values -- "getc-like functions" -- in the ANSI world. Unless
416 you explicitly cast the return value to (unsigned), it is likely
417 to be "promoted" to an int and have its sign extended.
418 * At least one compiler (the one on DEC OSF/1 1.3) treats "/*" and
419 "*/" within string constants as comment begin and end. No amount
420 of #ifdefs will get around this one. You simply can't put these
421 sequences in a string constant, e.g. "/usr/local/doc/*.*".
422 * Avoid putting multiple macro references on a single line, e.g.:
423 putchar(BS); putchar(SP); putchar(BS)
425 This overflows the CPP output buffer of more than a few C
426 preprocessors (this happened, for example, with SunOS 4.1 cc, which
427 evidently has a 1K macro expansion buffer).
429 C-Kermit needs constant adjustment to new OS and compiler releases.
430 Every new OS release shuffles header files or their contents, or
431 prototypes, or data types, or levels of ANSI strictness, etc. Every
432 time you make an adjustment to remove a new compilation error, BE VERY
433 CAREFUL to #ifdef it on a symbol unique to the new configuration so
434 that the previous configuration (and all other configurations on all
435 other platforms) remain as before.
437 Assume nothing. Don't assume header files are where they are supposed
438 to be, that they contain what you think they contain, that they define
439 specific symbols to have certain values -- or define them at all!
440 Don't assume system header files protect themselves against multiple
441 inclusion. Don't assume that particular system or library calls are
442 available, or that the arguments are what you think they are -- order,
443 data type, passed by reference vs value, etc. Be conservative when
444 attempting to write portable code. Avoid all advanced features.
446 If you see something that does not make sense, don't assume it's a
447 mistake -- it might be there for a reason, and changing it or removing
448 is likely to cause compilation, linking, or runtime failures sometime,
449 somewhere. Some huge percentage of the code, especially in the
450 platform-dependent modules, is workarounds for compiler, linker, or
453 But finally... feel free to violate any or all of these rules in
454 platform-specific modules for environments in which the rules are
455 certain not to apply. For example, in VMS-specific code, it is OK to
456 use #if, because VAX C, DEC C, and VMS GCC all support it.
458 [ [29]Contents ] [ [30]C-Kermit ] [ [31]Kermit Home ]
459 ________________________________________________________________________
463 The C language and standard C library are notoriously inadequate and
464 unsafe. Strings are arrays of characters, usually referenced through
465 pointers. There is no native string datatype. Buffers are fixed size,
466 and C provides no runtime bounds checking, thus allowing overwriting
467 of other data or even program code. With the popularization of the
468 Internet, the "buffer exploit" has become a preferred method for
469 hackers to hijack privileged programs; long data strings are fed to a
470 program in hopes that it uses unsafe C library calls such as strcpy()
471 or sprintf() to copy strings into automatic arrays, thus overwriting
472 the call stack, and therefore the routine's return address. When such
473 a hole is discovered, a "string" can be constructed that contains
474 machine code to hijack the program's privileges and penetrate the
477 This problem is partially addressed by the strn...() routines, which
478 should always be used in preference to their str...() equivalents
479 (except when the copy operation has already been prechecked, or there
480 is a good reason for not using them, e.g. the sometimes undesirable
481 side effect of strncpy() zeroing the remainder of the buffer). The
482 most gaping whole, however, is sprintf(), which performs no length
483 checking on its destination buffer, and is not easy to replace.
484 Although snprintf() routines are starting to appear, they are not yet
485 widespread, and certainly not universal, nor are they especially
486 portable, or even full-featured.
488 For these reasons, we have started to build up our own little library
489 of C Library replacements, ckclib.[ch]. These are safe and highly
490 portable primitives for memory management and string manipulation,
494 Like strncpy but returns a useful value, doesn't zero buffer.
503 Returns character as string
506 Used with ck?to?() as a safe sprintf() replacement for up to 4
510 Like ckmakmsg() but accepts up to 12 items
512 More about library functions in [32]Section 4.A.
514 [ [33]Contents ] [ [34]C-Kermit ] [ [35]Kermit Home ]
515 ________________________________________________________________________
517 3.2. The "char" vs "unsigned char" Dilemma
519 This is one of the most aggravating and vexing characteristics of the
520 C language. By design, chars (and char *'s) are SIGNED. But in the
521 modern era, however, we need to process characters that can have (or
522 include) 8-bit values, as in the ISO Latin-1, IBM CP 850, or UTF-8
523 character sets, so this data must be treated as unsigned. But some C
524 compilers (such as those based on the Bell UNIX V7 compiler) do not
525 support "unsigned char" as a data type. Therefore we have the macro or
526 typedef CHAR, which we use when we need chars to be unsigned, but
527 which, unfortunately, resolves itself to "char" on those compilers
528 that don't support "unsigned char". AND SO... We have to do a lot of
529 fiddling at runtime to avoid sign extension and so forth.
531 Some modern compilers (e.g. IBM, DEC, Microsoft) have options that say
532 "make all chars be unsigned" (e.g. GCC "-funsigned-char") and we use
533 them when they are available. Other compilers don't have this option,
534 and at the same time, are becoming increasingly strict about type
535 mismatches, and spew out torrents of warnings when we use a CHAR where
536 a char is expected, or vice versa. We fix these one by one using
537 casts, and the code becomes increasingly ugly. But there remains a
538 serious problem, namely that certain library and kernel functions have
539 arguments that are declared as signed chars (or pointers to them),
540 whereas our character data is unsigned. Fine, we can can use casts
541 here too -- but who knows what happens inside these routines.
543 [ [36]Contents ] [ [37]C-Kermit ] [ [38]Kermit Home ]
544 ________________________________________________________________________
548 When C-Kermit is on the far end of a connection, it is said to be in
549 remote mode. When C-Kermit has made a connection to another computer,
550 it is in local mode. (If C-Kermit is "in the middle" of a multihop
551 connection, it is still in local mode.)
553 On another axis, C-Kermit can be in any of several major states:
556 Reading and writing from the job's controlling terminal or
557 "console". In this mode, all i/o is handled by the Group E
558 conxxx() (console i/o) routines.
561 Reading and writing from the communicatons device. In this
562 mode, all i/o is handled by the Group E ttxxx() (terminal i/o)
566 Reading from the keyboard with conxxx() routines and writing to
567 the communications device with ttxxx() routines AND vice-versa.
569 When in local mode, the console and communications device are
570 distinct. During file transfer, Kermit may put up a file-transfer
571 display on the console and sample the console for interruption
574 When in remote mode, the console and communications device are the
575 same, and therefore there can be no file-transfer display on the
576 console or interruptions from it (except for "in-band" interruptions
579 [ [39]Contents ] [ [40]C-Kermit ] [ [41]Kermit Home ]
580 ________________________________________________________________________
582 4.A. Group A: Library Functions
584 Library functions, strictly portable, can be used by all modules on
585 all platforms: [42]ckclib.h, [43]ckclib.c.
587 (To be filled in... For now, see [44]Section 3.1 and the comments in
590 [ [45]Contents ] [ [46]C-Kermit ] [ [47]Kermit Home ]
591 ________________________________________________________________________
593 4.B. Group B: Kermit File Transfer
595 The Kermit protocol kernel. These files, whose names start with "ckc
596 are supposed to be totally portable C, and are expected to compile
597 correctly on any platform with any C compiler. "Portable" does not
598 mean the same as as "ANSI" -- these modules must compile on 10- and
599 20-year old computers, with C preprocessors, compilers, and/or linkers
600 that have all sorts of restrictions. The Group B modules do not
601 include any header files other than those that come with Kermit
602 itself. They do not contain any library calls except from the standard
603 C library (e.g. printf()). They most certainly do not contain any
607 For use by C compilers that don't allow -D on the command line.
610 ASCII character symbol definitions.
613 System-independent signal-handling definitions and prototypes.
616 Originally, debugging definitions. Now this file also contains
617 all definitions and prototypes that are shared by all modules
621 Kermit protocol symbol definitions.
624 Character-set-related symbol definitions (see next section).
627 The main program. This module contains the declarations of all
628 the protocol-related global variables that are shared among the
632 The protocol module itself, written in "wart", a lex-like
633 preprocessor that is distributed with Kermit under the name
636 [56]ckcfns.c, [57]ckcfn2.c, [58]ckcfn3.c
637 The protocol support functions used by the protocol module.
639 [59]Group B modules may call upon functions from [60]Group E, but not
640 from [61]Group D modules (with the single exception that the main
641 program invokes the user interface, which is in Group D). (This last
642 assertion is really only a conjecture.)
644 [ [62]Contents ] [ [63]C-Kermit ] [ [64]Kermit Home ]
645 ________________________________________________________________________
647 4.C. Group C: Character-Set Conversion
649 Character set translation tables and functions. Used by the [65]Group
650 B, protocol modules, but may be specific to different computers. (So
651 far, all character character sets supported by C-Kermit are supported
652 in [66]ckuxla.c and [67]ckuxla.h, including Macintosh and IBM
653 character sets). These modules should be completely portable, and not
654 rely on any kind of system or library services.
657 Character-set definitions usable by all versions of C-Kermit.
660 Character-set definitions for computer "?", e.g. [69]ckuxla.h
661 for UNIX, [70]ckmxla.h for Macintosh.
664 Character-set translation tables and functions for computer
665 "?", For example, CKUXLA.C for UNIX, CKMXLA.C for Macintosh. So
666 far, these are the only two such modules. The UNIX module is
667 used for all versions of C-Kermit except the Macintosh version.
675 Here's how to add a new file character set in the original
676 (non-Unicode modules). Assuming it is based on the Roman (Latin)
677 alphabet. Let's call it "Barbarian". First, in ck?xla.h, add a
678 definition for FC_BARBA (8 chars maximum length) and increase
679 MAXFCSETS by 1. Then, in ck?xla.c:
681 * Add a barbarian entry into the fcsinfo array.
682 * Add a "barbarian" entry to file character set keyword table,
684 * Add a "barbarian" entry to terminal character set keyword table,
686 * Add a translation table from Latin-1 to barbarian: yl1ba[].
687 * Add a translation table from barbarian to Latin-1: ybal1[].
688 * Add a translation function from Barbarian to ASCII: xbaas().
689 * Add a translation function from Barbarian to Latin-1: xbal1().
690 * Add a translation function from Latin-1 to Barbarian: xl1ba().
691 * etc etc for each transfer character set...
692 * Add translation function pointers to the xls and xlr tables.
694 Other translations involving Barbarian (e.g. from Barbarian to
695 Latin-Cyrillic) are performed through these tables and functions. See
696 ckuxla.h and ckuxla.c for extensive examples.
698 To add a new Transfer Character Set, e.g. Latin Alphabet 9 (for the
699 Euro symbol), again in the "old" character-set modules:
703 + Add a TC_xxxx definition and increase MAXTCSETS accordingly.
705 In ck?xla.h (since any transfer charset is also a file charset):
707 + Add an FC_xxxx definition and increase MAXFCSETS accordingly.
711 + Add a tcsinfo[] entry.
712 + Make a tcstab[] keyword table entry.
713 + Make an fcsinfo[] table entry.
714 + Make an fcstab[] keyword table entry.
715 + Make a tcstab[] keyword table entry.
716 + If necessary, make a langinfo[] table entry.
717 + Make entries in the function pointer arrays.
718 + Provide any needed functions.
720 As of C-Kermit 7.0, character sets are also handled in parallel by the
721 new (and very large) Unicode module, ckcuni.[ch]. Eventually we should
722 phase out the old way, described just above, and operate entirely in
723 (and through) Unicode. The advantages are many. The disadvantages are
724 size and performance. To add a character to the Unicode modules:
728 + (To be filled in...)
732 + (To be filled in...)
734 [ [74]Contents ] [ [75]C-Kermit ] [ [76]Kermit Home ]
735 ________________________________________________________________________
737 4.D. Group D: User Interface
739 This is the code that communicates with the user, gets her commands,
740 informs her of the results. It may be command-line oriented,
741 interactive prompting dialog, menus and arrow keys, windows and mice,
742 speech recognition, telepathy, etc. The one provided is command-and
743 prompt, with the ability to read commands from various sources: the
744 console keyboard, a file, or a macro definition. The user interface
745 has three major functions:
747 1. Sets the parameters for the file transfer and then starts it. This
748 is done by setting certain (many) global variables, such as the
749 protocol machine start state, the file specification, file type,
750 communication parameters, packet length, window size, character
752 2. Displays messages on the user's screen during the file transfer,
753 using the screen() function, which is called by the group-1
755 3. Executes any commands directly that do not require Kermit
756 protocol, such as the CONNECT command, local file management
757 commands, parameter-setting commands, FTP client commands, etc.
759 If you plan to imbed the [77]Group B, files into a program with a
760 different user interface, your interface must supply an appropriate
761 screen() function, plus a couple related ones like chkint() and
762 intmsg() for handling keyboard (or mouse, etc) interruptions during
763 file transfer. The best way to find out about this is to link all the
764 C-Kermit modules together except the ckuu*.o and ckucon.o modules, and
765 see which missing symbols turn up.
767 C-Kermit's character-oriented user interface (as opposed to the
768 Macintosh version's graphical user interface) consists of the
769 following modules. C-Kermit can be built with an interactive command
770 parser, a command-line-option-only parser, a graphical user interface,
771 or any combination, and it can even be built with no user interface at
772 all (in which case it runs as a remote-mode Kermit server).
776 The command parsing primitives used by the interactive command
777 parser to parse keywords, numbers, filenames, etc, and to give
778 help, complete fields, supply defaults, allow abbreviations and
779 editing, etc. This package is totally independent of Kermit,
780 but does depend on the [80]Group E functions.
783 Definitions of symbols used in Kermit's commands.
786 Kermit's interactive command parser, including the script
787 programming language: [82]ckuusr.c (includes top-level keyword
788 tables); [83]ckuus2.c (HELP command text); [84]ckuus3.c (most
789 of the SET command); [85]ckuus4.c (includes variables and
790 functions); ckuus[567].c (miscellaneous);
793 The command-line-option parser.
796 User interface functions common to both the interactive and
797 command-line parsers.
800 Version heralds for different implementations.
803 The (old, uucp-like) SCRIPT command
806 The DIAL command. Includes specific knowledge of many types of
809 Note that none of the above files is actually Unix-specific. Over time
810 they have proven to be portable among all platforms where C-Kermit is
811 built: Unix, VMS, AOS/VS, Amiga, OS-9, VOS, etc etc. Thus the third
812 letter should more properly be "c", but changing it would be too
816 The CONNECT command. Terminal connection, and in some cases
817 (Macintosh, Windows) also terminal emulation. NOTE: As of
818 C-Kermit 7.0, there are two different CONNECT modules for UNIX:
819 [91]ckucon.c -- the traditional, portable, fork()-based version
820 -- and [92]ckucns.c, a new version that uses select() rather
821 than forks so it can handle encryption. ckucns.c is the
822 preferred version for Unix; ckucon.c is not likely to keep pace
823 with it in terms of upgrades, etc. However, since select() is
824 not portable to every platform, ckucon.c will be kept
825 indefinitely for those platforms that can't use ckucns.c. NOTE:
826 SunLink X.25 support is available only in ckucon.c.
829 Modules having to do with authentication and encryption. Since
830 the relaxation of USA export laws, they are included with the
831 general source-code distribution. Secure C-Kermit binaries can
832 be built using special targets in the standard makefile.
833 However, secure prebuilt binaries may not be distributed.
835 For other implementations, the files may, and probably do, have
836 different names. For example, the Macintosh graphical user interface
837 filenames start with "ckm". Kermit 95 uses the ckucmd and ckuus*
838 modules, but has its own CONNECT command modules. And so on.
840 Here is a brief description of C-Kermit's "user interface interface",
841 from ckuusr.c. It is nowhere near complete; in particular, hundreds of
842 global variables are shared among the many modules. These should, some
843 day, be collected into classes or structures that can be passed around
844 as needed; not only for purity's sake, but also to allow for multiple
845 simultaneous communication sessions and or user interfaces. Our list
846 of things to do is endless, and reorganizing the source is almost
847 always at the bottom.
849 The ckuus*.c modules (like many of the ckc*.c modules) depend on the
850 existence of C library features like fopen, fgets, feof, (f)printf,
851 argv/argc, etc. Other functions that are likely to vary among
852 operating systems -- like setting terminal modes or interrupts -- are
853 invoked via calls to functions that are defined in the [93]Group E
854 platform-dependent modules, ck?[ft]io.c. The command line parser
855 processes any arguments found on the command line, as passed to main()
856 via argv/argc. The interactive parser uses the facilities of the cmd
857 package (developed for this program, but, in theory, usable by any
858 program). Any command parser may be substituted for this one. The only
859 requirements for the Kermit command parser are these:
861 1. Set parameters via global variables like duplex, speed, ttname,
862 etc. See [94]ckcmai.c for the declarations and descriptions of
864 2. If a command can be executed without the use of Kermit protocol,
865 then execute the command directly and set the sstate (start state)
866 variable to 0. Examples include SET commands, local directory
867 listings, the CONNECT command.
868 3. If a command requires the Kermit protocol, set the following
871 'x' (enter server mode) (none)
872 'r' (send a 'get' command) cmarg, cmarg2
873 'v' (enter receive mode) cmarg2
874 'g' (send a generic command) cmarg
875 's' (send files) nfils, cmarg & cmarg2 OR cmlist
876 'c' (send a remote host command) cmarg
878 cmlist is an array of pointers to strings.
879 cmarg, cmarg2 are pointers to strings.
880 nfils is an integer (hmmm, probably should be an unsigned long).
883 A filename string (possibly wild), or:
884 a pointer to a prefabricated generic command string, or:
885 a pointer to a host command string.
888 The name to send a single file under, or:
889 the name under which to store an incoming file; must not
891 If it's the name for receiving, a null value means to
892 store the file under the name it arrives with.
895 A list of nonwild filenames, such as passed via argv.
897 nfils is an integer, interpreted as follows:
898 -1: filespec (possibly wild) in cmarg, must be expanded
900 0: send from stdin (standard input).
901 >0: number of files to send, from cmlist.
903 The screen() function is used to update the screen during file
904 transfer. The tlog() function writes to a transaction log (if TLOG is
905 defined). The debug() function writes to a debugging log (if DEBUG is
906 defined). The intmsg() and chkint() functions provide the user i/o for
907 interrupting file transfers.
909 [ [95]Contents ] [ [96]C-Kermit ] [ [97]Kermit Home ]
910 ________________________________________________________________________
912 4.E. Group E: Platform-Dependent I/O
914 Platform-dependent function definitions. All the Kermit modules,
915 including the command package, call upon these functions, which are
916 designed to provide system-independent primitives for controlling and
917 manipulating devices and files. For Unix, these functions are defined
918 in the files [98]ckufio.c (files), [99]ckutio.c (communications), and
919 [100]ckusig.c (signal handling).
921 For VMS, the files are [101]ckvfio.c, ckvtio.c, and [102]ckusig.c (VMS
922 can use the same signal handling routines as Unix). It doesn't really
923 matter what the files are called, except for Kermit distribution
924 purposes (grouping related files together alphabetically), only that
925 each function is provided with the name indicated, observes the same
926 calling and return conventions, and has the same type.
928 The Group E modules contain both functions and global variables that
929 are accessed by modules in the other groups. These are now described.
931 (By the way, I got this list by linking all the C-Kermit modules
932 together except ckutio and ckufio. These are the symbols that ld
933 reported as undefined. But that was a long time ago, probably circa
936 4.E.1. Global Variables
939 Pointer to string containing command for deleting files.
940 Example: char *DELCMD = "rm -f "; (UNIX)
941 Example: char *DELCMD = "delete "; (VMS)
942 Note trailing space. Filename is concatenated to end of this
943 string. NOTE: DELCMD is used only in versions that do not
944 provide their own built-in DELETE command.
947 Pointer to string containing command for listing files when a
949 Example: char *DIRCMD = "/bin/ls -l "; (UNIX)
950 Example: char *DIRCMD = "directory "; (VMS)
951 Note trailing space. Filename is concatenated to end of this
952 string. NOTE: DIRCMD is used only in versions that do not
953 provide their own built-in DIRECTORY command.
956 Pointer to string containing command for listing files when a
957 filespec is not given. (currently not used, handled in another
959 Example: char *DIRCMD2 = "/bin/ls -ld *";
960 NOTE: DIRCMD2 is used only in versions that do not provide
961 their own built-in DIRECTORY command.
964 Pointer to string containing command to display current
966 Example: char *PWDCMD = "pwd ";
967 NOTE: PWDCMD is used only in versions that do not provide their
968 own built-in PWD command.
971 Pointer to command to display free disk space in current
973 Example: char *SPACMD = "df .";
974 NOTE: SPACMD is used only in versions that do not provide their
975 own built-in SPACE command.
978 Pointer to command to display free disk space in another
980 Example: char *SPACM2 = "df ";
981 Note trailing space. Device or directory name is added to this
982 string. NOTE: SPACMD2 is used only in versions that do not
983 provide their own built-in SPACE command.
986 Pointer to command for displaying the contents of a file.
987 Example: char *TYPCMD = "cat ";
988 Note trailing space. Device or directory name is added to this
989 string. NOTE: TYPCMD is used only in versions that do not
990 provide their own built-in TYPE command.
993 Pointer to command for displaying logged-in users.
994 Example: char *WHOCMD = "who ";
995 Note trailing space. Specific user name may be added to this
999 Flag for whether program is running in foreground (0) or
1000 background (nonzero). Background operation implies that screen
1001 output should not be done and that all errors should be fatal.
1004 Flag for who is to echo console typein:
1005 1: The program (system is not echoing).
1006 0: The OS, front end, terminal, etc (not this program).
1009 Pointer to string that names the computer and operating system.
1010 Example: char *ckxsys = " NeXT Mach 1.0";
1011 Tells what computer system ckxv applies to. In UNIX Kermit,
1012 this variable is also used to print the program herald, and in
1013 the SHOW VERSION command.
1016 Pointer to version/edit info of ck?tio.c module.
1017 Example: char *ckxv = "UNIX Communications Support, 6.0.169, 6
1019 Used by SHOW VERSION command.
1022 Like ckxsys, but briefer.
1023 Example: char *ckzsys = " 4.3 BSD";
1024 Tells what platform ckzv applies to. Used by the SHOW VERSION
1028 Pointer to version/edit info of ck?fio.c module.
1029 Example: char *ckzv = "UNIX File support, 6.0.113, 6 Sep 96";
1030 Used by SHOW VERSION command.
1033 Default flow control. 0 = none, 1 = Xon/Xoff, ... (see FLO_xxx
1034 symbols in ckcdeb.h)
1035 Set by Group E module. Used by [103]ckcmai.c to initialize flow
1039 Default location. 0 = remote, 1 = local. Set by Group E module.
1040 Used by ckcmai.c to initialize local variable. Used in various
1041 places in the user interface.
1044 Default parity. 0 = none, 'e' = even, 'o' = odd, 'm' = mark,
1045 's' = space. Set by Group E module. Used by ckcmai.c to
1046 initialize parity variable.
1049 Default communication device. Set by Group E module. Used in
1050 many places. This variable should be initialized the the symbol
1051 CTTNAM, which is defined in ckcdeb.h, e.g. as "/dev/tty" for
1052 UNIX, "TT:" for VMS, etc. Example: char *dftty = CTTNAM;
1055 Array of string pointers to filenames that matched the most
1056 recent wildcard match, i.e. the most recent call to zxpand().
1057 Used (at least) by command parsing package for partial filename
1061 Flag for whether to attempt to expand leading tildes in
1062 directory names (used in UNIX only, and then only when the
1063 symbol DTILDE is defined.
1066 The protocol being used to communicate over a network device.
1067 Values are defined in ckcnet.h. Example: NP_TELNET is network
1071 The maximum length for a filename, exclusive of any device or
1072 directory information, in the format of the host operating
1076 The maximum length for a fully specified filename, including
1077 device designator, directory name, network node name, etc, in
1078 the format of the host operating system, and including all
1082 File descriptor of the communication device. -1 if there is no
1083 open or usable connection, including when C-Kermit is in remote
1084 mode. Since this is not implemented everywhere, references to
1085 it are in #ifdef CK_TTYFD..#endif.
1087 [ [104]Contents ] [ [105]C-Kermit ] [ [106]Kermit Home ]
1088 ________________________________________________________________________
1092 These are divided into three categories: file-related functions (B.1),
1093 communication functions (B.2), and miscellaneous functions (B.3).
1095 4.E.2.1. File-Related Functions
1097 In most implementations, these are collected together into a module
1098 called ck?fio.c, where ? = "u" ([107]ckutio.c for Unix), "v"
1099 ([108]ckvtio.c for VMS), [109]etc. To be totally platform-independent,
1100 C-Kermit maintains its own file numbers, and provides the functions
1101 described in this section to deal with the files associated with them.
1102 The file numbers are referred to symbolically, and are defined as
1103 follows in ckcker.h:
1105 #define ZCTERM 0 /* Console terminal */
1106 #define ZSTDIO 1 /* Standard input/output */
1107 #define ZIFILE 2 /* Current input file for SEND command */
1108 #define ZOFILE 3 /* Current output file for RECEIVE command */
1109 #define ZDFILE 4 /* Current debugging log file */
1110 #define ZTFILE 5 /* Current transaction log file */
1111 #define ZPFILE 6 /* Current packet log file */
1112 #define ZSFILE 7 /* Current session log file */
1113 #define ZSYSFN 8 /* Input from a system function (pipe) */
1114 #define ZRFILE 9 /* Local file for READ command */ (NEW)
1115 #define ZWFILE 10 /* Local file for WRITE command */ (NEW)
1116 #define ZMFILE 11 /* Auxilliary file for internal use */ (NEW)
1117 #define ZNFILS 12 /* How many defined file numbers */
1119 In the descriptions below, fn refers to a filename, and n refers to
1120 one of these file numbers. Functions are of type int unless otherwise
1121 noted, and are listed mostly alphabetically.
1125 Checks the file number n. Returns:
1126 -1: File number n is out of range
1127 0: n is in range, but file is not open
1128 1: n in range and file is open
1131 iswild(filspec) char *filespec;
1132 Checks if the file specification is "wild", i.e. contains
1133 metacharacters or other notations intended to match multiple
1139 isdir(string) char *string;
1140 Checks if the string is the name of an existing directory. The
1141 idea is to check whether the string can be "cd'd" to, so in
1142 some cases (e.g. DOS) it might also indicate any file
1143 structured device, such as a disk drive (like A:). Other
1144 nonzero returns indicate system-dependent information; e.g. in
1145 VMS isdir("[.FOO]") returns 1 but isdir("FOO.DIR;1") returns 2
1146 to indicate the directory-file name is in a format that needs
1147 conversion before it can be combined with a filename. Returns:
1148 0: not a directory (including any kind of error)
1149 1: it is an existing directory
1152 zfcdat(name) char *name;
1153 Returns modification (preferably, otherwise creation) date/time
1154 of file whose name is given in the argument string. Return
1155 value is a pointer to a string of the form yyyymmdd hh:mm:ss,
1156 for example 19931231 23:59:59, which represents the local time
1157 (no timezone or daylight savings time finagling required).
1158 Returns the null string ("") on failure. The text pointed to by
1159 the string pointer might be in a static buffer, and so should
1160 be copied to a safe place by the caller before any subsequent
1161 calls to this function.
1164 zfnqfp(fn, buflen, buf) char * fn; int buflen; char * buf;
1165 Given the filename fn, the corresponding fully qualified,
1166 absolute filename is placed into the buffer buf, whose length
1167 is buflen. On failure returns a NULL pointer. On success
1168 returns a pointer to a struct zfnfp containing pointers to the
1169 full pathname and to just the filename, and an int giving the
1170 length of the full pathname. All references to this function in
1171 mainline code must be protected by #ifdef ZFNQFP..#endif,
1172 because it is not present in all of the ck*fio.c modules. So if
1173 you implement this function in a version that did not have it
1174 before, be sure to add #define ZFNQFP in the appropriate spot
1175 in ckcdeb.h or in the build-procedure CFLAGS.
1178 zcmpfn(s1,s2) char * s2, * s2;
1179 Compares two filenames to see if they refer to the same.
1180 Internally, the arguments can be converted to fully qualified
1181 pathnames, e.g. with zfnqfp(), realpath(), or somesuch. In Unix
1182 or other systems where symbolic links exist, the link should be
1183 resolved before making the comparison or looking at the inodes.
1185 0: Files are not identical.
1186 1: Files are identical.
1189 zfseek(pos) long pos;
1190 Positions the input pointer on the current input file to the
1191 given position. The pos argument is 0-based, the offset
1192 (distance in bytes) from beginning of the file. Needed for
1193 RESEND, PSEND, and other recovery operations. This function is
1194 not necessarily possible on all systems, e.g. record-oriented
1195 systems. It should only be used on binary files (i.e. files we
1196 are sending in binary mode) and stream-oriented file systems.
1202 zchdir(dirnam) char *dirnam;
1203 Changes current or default directory to the one given in
1210 Check to see if file with name fn is a regular, readable,
1211 existing file, suitable for Kermit to send -- not a directory,
1212 not a symbolic link, etc. Returns:
1213 -3: if file exists but is not accessible (e.g.
1215 -2: if file exists but is not of a readable type (e.g. a
1217 -1: on error (e.g. file does not exist, or fn is garbage);
1218 >=0: (length of file) if file exists and is readable.
1219 Also see isdir(), zgetfs().
1222 zchkpid(pid) unsigned long pid;
1224 1: If the given process ID (e.g. pid in UNIX) is valid and
1229 zgetfs(fn) char *fn;
1230 Gets the size of the given file, regardless of accessibility.
1231 Used for directory listings. Unlike zchki(), should return the
1232 size of any kind of file, even a directory. zgetfs() also
1233 should serve as a mini "get file info" function that can be
1234 used until we design a better one, by also setting some global
1236 int zgfs_link = 1/0 = file is (not) a symbolic link.
1237 int zgfs_dir = 1/0 = file is (not) a directory.
1238 char linkname[] = if zgfs_link != 0, name of file link points
1241 -1: on error (e.g. file does not exist, or fn is garbage);
1242 >=0: (length of file) if file exists and is readable.
1246 Checks to see if a file of the given name can be created.
1248 -1: if file cannot be created, or on any kind of error.
1249 0: if file can be created.
1252 zchkspa(fn,len) char *f; long len;
1253 Checks to see if there is sufficient space to store the file
1254 named fn, which is len bytes long. If you can't write a
1255 function to do this, then just make a dummy that always returns
1256 1; higher level code will recover from disk-full errors. The
1257 receiving Kermit uses this function to refuse an incoming file
1258 based on its size, via the attribute mechanism. Returns:
1260 0: if there is not enough space.
1261 1: if there is enough space.
1264 zchin(n,c) int n; int *c;
1265 Gets a character from file number n, return it in c (call with
1267 -1: on failure, including EOF.
1268 0: on success with character in c.
1271 zchout(n,c) int n; char c;
1272 Writes the character c to file number n. Returns:
1278 Closes file number n. Returns:
1283 zdelet(fn) char *name;
1284 Attempts to delete (remove, erase) the named file. Returns:
1286 1: if file was deleted successfully.
1290 Returns a pointer to the system-dependent numeric
1291 permissions/protection string for file f, or NULL upon failure.
1292 Used if CK_PERMS is defined.
1296 Returns a pointer to the system-dependent symbolic
1297 permissions/protection string for file f, or NULL upon failure.
1298 Used if CK_PERMS is defined. Example: In UNIX zgperm(f) might
1299 return "100770", but ziperm() might return "-rwxrwx---". In
1300 VMS, zgperm() would return a hexadecimal string, but ziperm()
1301 would return something like "(RWED,RWED,RE,)".
1305 Returns a pointer to the name of the current directory, folder,
1306 etc, or a NULL pointer if the current directory cannot be
1307 determined. If possible, the directory specification should be
1308 (a) fully specified, e.g. as a complete pathname, and (b) be
1309 suitable for appending a filename. Thus, for example, Unix
1310 directory names should end with '/'. VMS directory names should
1311 look like DEV:[NAME] (rather than, say, NAME.DIR;1).
1315 Returns a pointer to a string containing the user's home
1316 directory, or NULL upon error. Should be formatted like
1321 Fill buffer from input file. This function is used by the macro
1322 zminchar(), which is defined in ckcker.h. zminchar() manages
1323 its own buffer, and calls zinfill() to fill it whenever it
1324 becomes empty. It is used only for sending files, and reads
1325 characters only from file number ZIFILE. zinfill() returns -1
1326 upon end of file, -2 upon fatal error, and -3 upon timeout
1327 (e.g. when reading from a pipe); otherwise it returns the first
1328 character from the buffer it just read.
1332 Kills the current job, session, process, etc, logs out,
1333 disappears. Used by the Kermit server when it receives a BYE
1334 command. On failure, returns -1. On success, does not return at
1335 all! This function should not be called until all other steps
1336 have been taken to close files, etc.
1339 zstrip(fn,&fn2) char *fn1, **fn2;
1340 Strips device and directory, etc, from file specification fn,
1341 leaving only the filename (including "extension" or "filetype"
1342 -- the part after the dot). For example DUA0:[PROGRAMS]OOFA.C;3
1343 becomes OOFA.C, or /usr/fdc/oofa.c becomes oofa.c. Returns a
1344 pointer to result in fn2.
1347 zsetperm(char * file, unsigned int code)
1348 Set permissions of file to given system-dependent code. 0: On
1353 zsetroot(char * dir)
1354 Sets the root for the user's file access, like Unix chroot(),
1355 but does not require privilege. In Unix, this must be
1356 implemented entirely by Kermit's own file access routines.
1359 -1: Invalid argument
1362 -4: Access to given directory denied
1363 -5: New root not within old root
1366 zinroot(char * file)
1367 If no root is set (zsetroot()), returns 1.
1368 Otherwise, if given file is in the root, returns 1.
1369 Otherwise, returns 0.
1372 zltor(fn,fn2) char *fn1, *fn2;
1373 Local-To-Remote filename translation. OBSOLETE: replaced by
1374 nzltor() (q.v.). Translates the local filename fn into a format
1375 suitable for transmission to an arbitrary type of computer, and
1376 copies the result into the buffer pointed to by fn2.
1377 Translation may involve (a) stripping the device and/or
1378 directory/path name, (b) converting lowercase to uppercase, (c)
1379 removing spaces and strange characters, or converting them to
1380 some innocuous alphabetic character like X, (d) discarding or
1381 converting extra periods (there should not be more than one).
1382 Does its best. Returns no value. name2 is a pointer to a
1383 buffer, furnished by the caller, into which zltor() writes the
1384 resulting name. No length checking is done.
1388 nzltor(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
1389 convert,pathnames,max;
1390 Replaces zltor(). This new version handles pathnames and checks
1391 length. fn1 and fn2 are as in zltor(). This version is called
1392 unconditionally for each file, rather than only when filename
1393 conversion is enabled. Pathnames can have the following values:
1395 PATH_OFF: Pathname, if any, is to be stripped
1396 PATH_REL: The relative pathname is to be included
1397 PATH_ABS: The full pathname is to be included
1399 After handling pathnames, conversion is done to the result as
1400 in the zltor() description if convert != 0; if relative or
1401 absolute pathnames are included, they are converted to UNIX
1402 format, i.e. with slash (/) as the directory separator. The max
1403 parameter specifies the maximum size of fn2. If convert > 0,
1404 the regular conversions are done; if convert < 0, minimal
1405 conversions are done (we skip uppercasing the letters, we allow
1406 more than one period, etc; this can be used when we know our
1407 partner is UNIX or similar).
1412 nzxpand(fn,flags) char *fn; int flags;
1413 Replaces zxpand(), which is obsolete as of C-Kermit 7.0.
1415 fn = Pointer to filename or pattern.
1416 flags = option bits:
1417 flags & ZX_FILONLY Match regular files
1418 flags & ZX_DIRONLY Match directories
1419 flags & ZX_RECURSE Descend through directory tree
1420 flags & ZX_MATCHDOT Match "dot files"
1421 flags & ZX_NOBACKUP Don't match "backup files"
1422 flags & ZX_NOLINKS Don't follow symlinks.
1424 Returns the number of files that match fn, with data structures
1425 set up so the first file (if any) will be returned by the next
1426 znext() call. If ZX_FILONLY and ZX_DIRONLY are both set, or
1427 neither one is set, files and directories are matched. Notes:
1429 1. It is essential that the number returned by nzxpand() reflect
1430 the actual number of filenames that will be returned by
1431 znext() calls. In other words:
1432 for (n = nzxpand(string,flags); n > 0; n--) {
1434 printf("%s\n", buf);
1436 should print all the file names; no more, no less.
1437 2. In UNIX, DOS, OS-9, etc, where directories contain entries
1438 for themselves (.) and the superior directory (..), these
1439 should NOT be included in the list under any circumstances,
1440 including when ZX_MATCHDOT is set.
1441 3. Additional option bits might be added in the future, e.g. for
1442 sorting (sort by date/name/size, reverse/ascending, etc).
1443 Currently this is done only in higher level code (through a
1444 hack in which the nzxpand() exports its filename array, which
1445 is not portable because not all OS's can use this mechanism).
1448 zmail(addr,fn) char *addr, fn;
1449 Send the local, existing file fn as e-mail to the address addr.
1452 2: if mail delivered but temp file can't be deleted
1453 -2: if mail can't be delivered
1456 zmkdir(path) char *path;
1457 The path can be a file specification that might contain
1458 directory information, in which the filename is expected to be
1459 included, or an unambiguous directory specification (e.g. in
1460 UNIX it must end with "/"). This routine attempts to create any
1461 directories in the given path that don't already exist. Returns
1462 0 or greater success: no directories needed creation, or else
1463 all directories that needed creation were created successfully;
1464 the return code is the number of directories that were created.
1465 Returns -1 on failure to create any of the needed directories.
1468 zrmdir(path) char *path;
1469 Attempts to remove the given directory. Returns 0 on success,
1470 -1 on failure. The detailed semantics are open -- should it
1471 fail if the directory contains any files or subdirectories,
1472 etc. It is probably best for this routine to behave in whatever
1473 manner is customary on the underlying platform; e.g. in UNIX,
1474 VMS, DOS, etc, where directories can not be removed unless they
1478 znewn(fn,s) char *fn, **s;
1479 Transforms the name fn into a filename that is guaranteed to be
1480 unique. If the file fn does not exist, then the new name is the
1481 same as fn; Otherwise, it's different. this function does its
1482 best, returns no value. New name is created in caller's space.
1483 Call like this: znewn(old,&new);. The second parameter is a
1484 pointer to the new name. This pointer is set by znewn() to
1485 point to a static string in its own space, so be sure to the
1486 result to a safe place before calling this function again.
1490 Copies the next file name from a file list created by zxpand()
1491 into the string pointed to by fn (see zxpand). If no more
1492 files, then the null string is placed there. Returns 0 if there
1493 are no more filenames, with 0th element the array pointed to by
1494 fn set to NUL. If there is a filename, it is stored in the
1495 array pointed to by fn and a positive number is returned. NOTE:
1496 This is a change from earlier definitions of this function
1497 (pre-1999), which returned the number of files remaining; thus
1498 0 was the return value when returning the final file. However,
1499 no mainline code ever depended on the return value, so this
1500 change should be safe.
1503 zopeni(n,fn) int n; char *fn;
1504 Opens the file named fn for input as file number n. Returns:
1509 zopeno(n,fn,zz,fcb) int n; char *name; struct zattr *zz; struct
1511 Attempts to open the named file for output as file number n. zz
1512 is a Kermit file attribute structure as defined in ckcdeb.h,
1513 containing various information about the file, including its
1514 size, creation date, and so forth. This function should attempt
1515 to honor as many of these as possible. fcb is a "file control
1516 block" in the traditional sense, defined in ckcdeb.h,
1517 containing information relevant to complicated file systems
1518 like VMS (RMS), IBM MVS, etc, like blocksize, record length,
1519 organization, record format, carriage control, etc. Returns:
1525 Dumps a file output buffer. Used with the macro zmchout()
1526 defined in ckcker.h. Used only with file number ZOFILE, i.e.
1527 the file that is being received by Kermit during file transfer.
1533 zprint(p,fn) char *p, *f;
1534 Prints the file with name fn on a local printer, with options
1537 3: if file sent to printer but can't be deleted
1538 -3: if file can't be printed
1541 zrename(fn,fn2) char *fn, *fn2;
1542 Changes the name of file fn to fn2. If fn2 is the name of an
1543 existing directory, or a file-structured device, then file fn
1544 is moved to that directory or device, keeping its original
1545 name. If fn2 lacks a directory separator when passed to this
1546 function, an appropriate one is supplied. Returns:
1551 zcopy(source,dest) char * source, * dest;
1552 Copies the source file to the destination. One file only. No
1553 wildcards. The destination string may be a filename or a
1554 directory name. Returns:
1557 -2: source file is not a regular file.
1558 -3: source file not found.
1559 -4: permission denied.
1560 -5: source and destination are the same file.
1566 Call with: "yyyymmdd hh:mm:ss" GMT/UTC date-time. Returns
1567 pointer to local date-time string "yyyymmdd hh:mm:ss" on
1568 success, NULL on failure.
1571 zrtol(fn,fn2) char *fn, *fn2;
1572 Remote-To-Local filename translation. OBSOLETE: replaced by
1573 nzrtol(). Translates a "standard" filename to a local filename.
1574 For example, in Unix this function might convert an
1575 all-uppercase name to lowercase, but leave lower- or mix-case
1576 names alone. Does its best, returns no value. New name is in
1577 string pointed to by fn2. No length checking is done.
1581 nzrtol(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
1582 convert,pathnames,max;
1583 Replaces zrtol. Like zrtol but handles pathnames and checks
1584 length. See nzltor for detailed description of parameters.
1589 zsattr(xx) struct zattr *xx;
1590 Fills in a Kermit file attribute structure for the file which
1591 is to be sent, namely the currently open ZIFILE. Note that this
1592 is not a very good design, but we're stuck with it. Callers
1593 must ensure that zsattr() is called only on real files, not on
1594 pipes, internally generated file-like objects such as server
1595 REMOTE command responses, etc. Returns:
1597 0: on success with the structure filled in.
1598 If any string member is null, it should be ignored by the
1600 If any numeric member is -1, it should be ignored by the
1605 s contains to pointer to a command to be executed by the host
1606 computer's shell, command parser, or operating system. If the
1607 system allows the user to choose from a variety of command
1608 processors (shells), then this function should employ the
1609 user's preferred shell. If possible, the user's job
1610 (environment, process, etc) should be set up to catch keyboard
1611 interruption signals to allow the user to halt the system
1612 command and return to Kermit. The command must run in ordinary,
1613 unprivileged user mode. If possible, this function should
1614 return -1 on failure to start the command, or else it should
1615 return 1 if the command succeeded and 0 if it failed.
1619 zshcmd() and zsyscmd() should set this to the command's actual
1620 exit status code if possible.
1624 s contains to pointer to a command to be executed by the host
1625 computer's shell, command parser, or operating system. If the
1626 system allows the user to choose from a variety of command
1627 processors (shells), then this function should employ the
1628 system standard shell (e.g. /bin/sh for Unix), so that the
1629 results will always be the same for everybody. If possible, the
1630 user's job (environment, process, etc) should be set up to
1631 catch keyboard interruption signals to allow the user to halt
1632 the system command and return to Kermit. The command must run
1633 in ordinary, unprivileged user mode. If possible, this function
1634 should return -1 on failure to start the command, or else it
1635 should return 1 if the command succeeded and 0 if it failed.
1638 z_exec(s,args) char * s; char * args[];
1639 This one executes the command s (which is searched for using
1640 the system's normal searching mechanism, such as PATH in UNIX),
1641 with the given argument vector, which follows the conventions
1642 of UNIX argv[]: the name of the command pointed to by element
1643 0, the first arg by element 1, and so on. A null args[] pointer
1644 indicates the end of the arugment list. All open files must
1645 remain open so the exec'd process can use them. Returns only if
1649 zsinl(n,s,x) int n, x; char *s;
1650 Reads a line from file number n. Writes the line into the
1651 address s provided by the caller. Writing terminates when
1652 newline is read, but with newline discarded. Writing also
1653 terminates upon EOF or if length x is exhausted. Returns:
1654 -1: on EOF or error.
1658 zsout(n,s) int n; char *s;
1659 Writes the string s out to file number n. Returns:
1664 zsoutl(n,s) int n; char *s;
1665 Writes the string s out to file number n and adds a line
1666 (record) terminator (boundary) appropriate for the system and
1667 the file format. Returns:
1672 zsoutx(n,s,x) int n, x; char *s;
1673 Writes exactly x characters from string s to file number n. If
1674 s has fewer than x characters, then the entire string s is
1677 >= 0: on success, the number of characters actually written.
1680 zstime(fn,yy,x) char *fn; struct zattr *yy; int x;
1681 Sets the creation date (and other attributes) of an existing
1682 file, or compares a file's creation date with a given date.
1685 fn: pointer to name of existing file.
1686 yy: Pointer to a Kermit file attribute structure in which yy->date.val
1687 is a date of the form yyyymmdd hh:mm:ss, e.g. 19900208 13:00:00, which
1688 is to be used for setting or comparing the file date. Other attributes
1689 in the struct can also be set, such as the protection/permission (See
1690 [110]Appendix I), when it makes sense (e.g. "yy->lprotect.val" can be
1691 set if the remote system ID matches the local one).
1692 x: A function code: 0 means to set the file's creation date as given.
1693 1 means compare the date from the yy struct with the file's date.
1696 -1: on any kind of error.
1697 0: if x is 0 and the file date was set successfully.
1698 0: if x is 1 and date from attribute structure > file
1700 1: if x is 1 and date from attribute structure <= file
1704 zstrip(name,name2) char *name, **name2;
1705 Strips pathname from filename "name". Constructs the resulting
1706 string in a static buffer in its own space and returns a
1707 pointer to it in name2. Also strips device name, file version
1708 numbers, and other "non-name" material.
1712 Runs a system command so its output can be accessed as if it
1713 were file n. The command is run in ordinary, unprivileged user
1715 If n is ZSTDIO or ZCTERM, returns -1.
1716 If n is ZIFILE or ZRFILE, then Kermit reads from the command,
1717 otherwise Kermit writes to the command.
1718 Returns 0 on error, 1 on success.
1721 zxpand(fn) char *fn;
1722 OBSOLETE: Replaced by nzxpand(), q.v.
1727 Returns the number of files returned by the most recent
1728 nzxpand() call, and resets the list to the beginning so the
1729 next znext() call returns the first file. Returns -1 if zxpand
1730 has not yet been called. If this function is available,
1731 ZXREWIND should be defined; otherwise it should not be
1734 #endif /* ZXREWIND */
1737 xsystem(cmd) char *cmd;
1738 Executes the system command without redirecting any of its i/o,
1739 similar (well, identical) to system() in Unix. But before
1740 passing the command to the system, xsystem() ensures that all
1741 privileges are turned off, so that the system command executes
1742 in ordinary unprivileged user mode. If possible, xsystem()
1743 returns the return code of the command that was executed.
1745 4.E.2.2. IKSD Variables and Functions
1747 These must be implemented in any C-Kermit version that is to be
1748 installed as an Internet Kermit Service Daemon (IKSD). IKSD is
1749 expected to be started by the Internet Daemon (e.g. inetd) with its
1750 standard i/o redirected to the incoming connection.
1753 Nonzero if anonymous logins allowed.
1755 extern int inserver;
1756 Nonzero if started in IKSD mode.
1759 Nonzero if IKSD and user logged in anonymously.
1761 extern char * homdir;
1762 Pointer to user's home directory.
1764 extern char * anonroot;
1765 Pointer to file-system root for anonymous users.
1767 Existing functions must make "if (inserver && isguest)" checks for
1768 actions that would not be legal for guests: zdelete(), zrmdir(),
1769 zprint(), zmail(), etc.
1772 zvuser(name) char * name;
1773 Verifies that user "name" exists and is allowed to log in. If
1774 the name is "ftp" or "anonymous" and ckxanon != 0, a guest
1775 login is set up. Returns 0 if user not allowed to log in,
1776 nonzero if user may log in.
1779 zvpass(string) char * string;
1780 Verifies password of the user from the most recent zvuser()
1781 call. Returns nonzero if password is valid for user, 0 if it
1782 isn't. Makes any appropriate system log entries (IKSD logins,
1783 failed login attempts, etc). If password is valid, logs the
1784 user in as herself (if real user), or sets up restricted
1785 anonymous access if user is guest (e.g. changes file-system
1786 root to anonroot and sets isguest = 1).
1790 Begins any desired system logging of an IKSD session.
1794 Terminates an IKSD session. In most cases this is simply a
1795 wrapper for exit() or doexit(), with some system logging added.
1797 4.E.2.3. Privilege Functions
1799 These functions are used by C-Kermit to adapt itself to operating
1800 systems where the program can be made to run in a "privileged" mode,
1801 e.g. setuid or setgid in Unix. C-Kermit should NOT read and write
1802 files or start subprocesses as a privileged program. This would
1803 present a serious threat to system security. The security package has
1804 been installed to prevent such security breaches by turning off the
1805 program's special privileges at all times except when they are needed.
1807 In UNIX, the only need Kermit has for privileged status is access to
1808 the UUCP lockfile directory, in order to read, create, and destroy
1809 lockfiles, and to open communication devices that are normally
1810 protected against the user (see the [111]Unix C-Kermit Installation
1811 Instructions for discussion). Therefore, privileges should only be
1812 enabled for these operations and disabled at all other times. This
1813 relieves the programmer of the responsibility of putting expensive and
1814 unreliable access checks around every file access and subprocess
1817 Strictly speaking, these functions are not required in all C-Kermit
1818 implementations, because their use (so far, at least) is internal to
1819 the Group E modules. However, they should be included in all C-Kermit
1820 implementations for operating systems that support the notion of a
1821 privileged program (UNIX, RSTS/E, what others?).
1825 Determine whether the program is running in privileged status.
1826 If so, turn off the privileges, in such a way that they can be
1827 turned on again when needed. Called from sysinit() at program
1828 startup time. Returns:
1830 nonzero on failure, in which case the program should halt
1835 If the program is not privileged, this function does nothing.
1836 If the program is privileged, this function returns it to
1837 privileged status. priv_ini() must have been called first.
1844 Turns privileges off (if they are on) in such a way that they
1845 can be turned back on again. Returns:
1851 Turns privileges off in such a way that they cannot be turned
1858 Attempts to turns privileges off in such a way that they can be
1859 turned on again later. Then checks to make sure that they were
1860 really turned off. If they were not really turned off, then
1861 they are cancelled permanently. Returns:
1865 4.E.2.4. Console-Related Functions
1867 These relate to the program's "console", or controlling terminal, i.e.
1868 the terminal that the user is logged in on and types commands at, or
1869 on a PC or workstation, the actual keyboard and screen.
1872 conbin(esc) char esc;
1873 Puts the console into "binary" mode, so that Kermit's command
1874 parser can control echoing and other treatment of characters
1875 that the user types. esc is the character that will be used to
1876 get Kermit's attention during packet mode; puts this in a
1877 global place. Sets the ckxech variable. Returns:
1882 concb(esc) char esc;
1883 Put console in "cbreak" (single-character wakeup) mode. That
1884 is, ensure that each console character is available to the
1885 program immediately when the user types it. Otherwise just like
1892 Returns a number, 0 or greater, the number of characters
1893 waiting to be read from the console, i.e. the number of
1894 characters that the user has typed that have not been read yet
1899 Returns the speed ("baud rate") of the controlling terminal, if
1900 known, otherwise -1L.
1903 congks(timo) int timo;
1904 Get Keyboard Scancode. Reads a keyboard scan code from the
1905 physical console keyboard. If the timo parameter is greater
1906 than zero, then times out and returns -2 if no character
1907 appears within the given number of seconds. Upon any other kind
1908 of error, returns -1. Upon success returns a scan code, which
1909 may be any positive integer. For situations where scan codes
1910 cannot be read (for example, when an ASCII terminal is used as
1911 the job's controlling terminal), this function is identical to
1912 coninc(), i.e. it returns an 8-bit character value. congks() is
1913 for use with workstations whose keyboards have Alternate,
1914 Command, Option, and similar modifier keys, and Function keys
1915 that generate codes greater than 255.
1919 Console get modes. Gets the current console terminal modes and
1920 saves them so that conres() can restore them later. Returns 1
1921 if it got the modes OK, 0 if it did nothing (e.g. because
1922 Kermit is not connected with any terminal), -1 on error.
1925 coninc(timo) int timo;
1926 Console Input Character. Reads a character from the console. If
1927 the timo parameter is greater than zero, then coninc() times
1928 out and returns -2 if no character appears within the given
1929 number of seconds. Upon any other kind of error, returns -1.
1930 Upon success, returns the character itself, with a value in the
1931 range 0-255 decimal.
1934 conint(f,s) SIGTYP (*f)(), (*s)();
1935 Sets the console to generate an interrupt if the user types a
1936 keyboard interrupt character, and to transfer control the
1937 signal-handling function f. For systems with job control, s is
1938 the address of the function that suspends the job. Sets the
1939 global variable "backgrd" to zero if Kermit is running in the
1940 foreground, and to nonzero if Kermit is running in the
1941 background. See ckcdeb.h for the definition of SIGTYP. No
1946 Console no interrupts. Disable keyboard interrupts on the
1947 console. No return value.
1951 Writes character c to the console terminal. Returns:
1952 0 on failure, 1 on success.
1956 Writes string s to the console. Returns -1 on error, 0 or
1960 conola(s) char *s[]; {
1961 Writes an array of strings to the console. Returns -1 on error,
1962 0 or greater on success.
1966 Writes string s to the console, followed by the necessary line
1967 termination characters to put the console cursor at the
1968 beginning of the next line. Returns -1 on error, 0 or greater
1973 Restores the console terminal to the modes obtained by congm().
1974 Returns: -1 on error, 0 on success.
1977 conxo(x,s) int x; char *s;
1978 Write x characters from string s to the console. Returns 0 or
1979 greater on success, -1 on error.
1983 Returns a pointer to the designator of the console keyboard
1984 type. For example, on a PC, this function would return "88",
1985 "101", etc. Upon failure, returns a pointer to the empty
1988 4.E.2.5. Communications Functions
1990 The communication device is the device used for terminal emulation and
1991 file transfer. It may or may not be the same device as the console,
1992 and it may or may not be a terminal (serial-port) device; it could
1993 also be a network connection. For brevity, the communication device is
1994 referred to here as the "tty". When the communication device is the
1995 same as the console device, Kermit is said to be in remote mode. When
1996 the two devices are different, Kermit is in local mode.
2000 Returns the number of characters that have arrived at the
2001 communication device but have not yet been read by ttinc(),
2002 ttinl(), and friends. If communication input is buffered (and
2003 it should be), this is the sum of the number of unread
2004 characters in Kermit's buffer PLUS the number of unread
2005 characters in the operating system's internal buffer. The call
2006 must be nondestructive and nonblocking, and as inexpensive as
2008 0: or greater on success,
2009 0: in case of internal error,
2010 -1: or less when it determines the connection has been broken,
2011 or there is no connection.
2013 That is, a negative return from ttchk() should reliably
2014 indicate that there is no usable connection. Furthermore,
2015 ttchk() should be callable at any time to see if the connection
2016 is open. When the connection is open, every effort must be made
2017 to ensure that ttchk returns an accurate number of characters
2018 waiting to be read, rather than just 0 (no characters) or 1 (1
2019 or more characters), as would be the case when we use select().
2020 This aspect of ttchk's operation is critical to successful
2021 operation of sliding windows and streaming, but "nondestructive
2022 buffer peeking" is an obscure operating system feature, and so
2023 when it is not available, we have to do it ourselves by
2024 managing our own internal buffer at a level below ttinc(),
2025 ttinl(), etc, as in the UNIX version (non-FIONREAD case).
2027 An external global variable, clsondisc, if nonzero, means that
2028 if a serial connection drops (carrier on-to-off transition
2029 detected by ttchk()), the device should be closed and released
2034 Closes the communication device (tty or network). If there were
2035 any kind of exclusive access locks connected with the tty,
2036 these are released. If the tty has a modem connection, it is
2037 hung up. For true tty devices, the original tty device modes
2038 are restored. Returns:
2044 Flush communications input buffer. If any characters have
2045 arrived but have not yet been read, discard these characters.
2046 If communications input is buffered by Kermit (and it should
2047 be), this function flushes Kermit's buffer as well as the
2048 operating system's internal input buffer. Returns:
2054 Flush tty output buffer. If any characters have been written
2055 but not actually transmitted (e.g. because the system has been
2056 flow-controlled), remove them from the system's output buffer.
2057 (Note, this function is not actually used, but it is
2058 recommended that all C-Kermit programmers add it for future
2059 use, even if it is only a dummy function that returns 0
2064 Looks for the modem signals CTS, DSR, and CTS, and returns
2065 those that are on in as its return value, in a bit mask as
2066 described for ttwmdm, in which a bit is on (1) or off (0)
2067 according to whether the corresponding signal is on (asserted)
2068 or off (not asserted). Return values:
2070 -2: if the line does not have modem control
2072 >=0: on success, with bit mask containing the modem signals.
2076 Returns the current tty speed in BITS (not CHARACTERS) per
2077 second, or -1 if it is not known or if the tty is really a
2078 network, or upon any kind of error. On success, the speed
2079 returned is the actual number of bits per second, like 1200,
2084 Get terminal window size. Returns -1 on error, 0 if the window
2085 size can't be obtained, 1 if the window size has been
2086 successfully obtained. Upon success, the external global
2087 variables tt_rows and tt_cols are set to the number of screen
2088 rows and number of screen columns, respectively. As this
2089 function is not implemented in all ck*tio.c modules, calls to
2090 it must be wrapped in #ifdef CK_TTGWSIZ..#endif. NOTE: This
2091 function must be available to use the TELNET NAWS feature
2092 (Negotiate About Window Size) as well as Rlogin.
2096 Hang up the current tty device. For real tty devices, turn off
2097 DTR for about 1/3-1/2 second (or other length of time,
2098 depending on the system). If the tty is really a network
2099 connection, close it. Returns:
2101 0: if it does not even try to hang up.
2102 1: if it believes it hung up successfully.
2106 Turns off all pending timer interrupts.
2109 ttinc(timo) int timo; (function is old, return codes are new)
2110 Reads one character from the communication device. If timo is
2111 greater than zero, wait the given number of seconds and then
2112 time out if no character arrives, otherwise wait forever for a
2114 -3: internal error (e.g. tty modes set wrong)
2115 -2: communications disconnect
2116 -1: timeout or other error
2117 >=0: the character that was read.
2118 It is HIGHLY RECOMMENDED that ttinc() be internally buffered so
2119 that calls to it are relatively inexpensive. If it is possible
2120 to to implement ttinc() as a macro, all the better, for example
2123 #define ttinc(t) ( (--txbufn >= 0) ? txbuf[ttbufp++] : txbufr(t) )
2125 (see description of txbufr() below)
2128 ttinl(dest,max,timo,eol,start,turn) int max,timo,turn; CHAR
2130 ttinl() is Kermit's packet reader. Reads a packet from the
2131 communications device, or up to max characters, whichever
2132 occurs first. A line is a string of characters starting with
2133 the start character up to and including the character given in
2134 eol or until the length is exhausted, or, if turn != 0, until
2135 the line turnaround character (turn) is read. If turn is 0,
2136 ttinl() *should* use the packet length field to detect the end,
2137 to allow for the possibility that the eol character appears
2138 unprefixed in the packet data. (The turnaround character is for
2139 half-duplex linemode connections.)
2141 If timo is greater than zero, ttinl() times out if the eol
2142 character is not encountered within the given number of seconds
2145 The characters that were input are copied into "dest" with
2146 their parity bits stripped if parity is not none. The first
2147 character copied into dest should be the start character, and
2148 the last should be the final character of the packet (the last
2149 block check character). ttinl() should also absorb and discard
2150 the eol and turn characters, and any other characters that are
2151 waiting to be read, up until the next start character, so that
2152 subsequent calls to ttchk() will not succeed simply because
2153 there are some terminators still sitting in the buffer that
2154 ttinl() didn't read. This operation, if performed, MUST NOT
2155 BLOCK (so if it can't be performed in a guaranteed nonblocking
2158 On success, ttinl() returns the number of characters read.
2159 Optionally, ttinl() can sense the parity of incoming packets.
2160 If it does this, then it should set the global variable ttprty
2161 accordingly. ttinl() should be coded to be as efficient as
2162 possible, since it is at the "inner loop" of packet reception.
2164 -1: Timeout or other possibly correctable error.
2165 -2: Interrupted from keyboard.
2166 -3: Uncorrectable i/o error -- connection lost, configuration
2168 >=0: on success, the number of characters that were actually
2169 read and placed in the dest buffer, not counting the trailing
2174 Outputs the character c to the communication line. If the
2175 operation fails to complete within two seconds, this function
2176 returns -1. Otherwise it returns the number of characters
2177 actually written to the tty (0 or 1). This function should only
2178 be used for interactive, character-mode operations, like
2179 terminal connection, script execution, dialer i/o, where the
2180 overhead of the signals and alarms does not create a
2181 bottleneck. (THIS DESCRIPTION NEEDS IMPROVEMENT -- If the
2182 operation fails within a "certain amount of time"... which
2183 might be dependent on the communication method, speed, etc. In
2184 particular, flow-control deadlocks must be accounted for and
2185 broken out of to prevent the program from hanging indefinitely,
2189 ttol(s,n) int n; char *s;
2190 Kermit's packet writer. Writes the n characters of the string
2191 pointed to to by s. NOTE: It is ttol's responsibility to write
2192 ALL of the characters, not just some of them. Returns:
2193 -1: on a possibly correctable error (so it can be retried).
2194 -3: on a fatal error, e.g. connection lost.
2195 >=0: on success, the actual number of characters written (the
2196 specific number is not actually used for anything).
2199 ttopen(ttname,lcl,modem,timo) char *ttname; int *lcl, modem,
2201 Opens a tty device, if it is not already open. ttopen must
2202 check to make sure the SAME device is not already open; if it
2203 is, ttopen returns successfully without doing anything. If a
2204 DIFFERENT device is currently open, ttopen() must call ttclos()
2205 to close it before opening the new one.
2210 character string - device name or network host
2214 If called with lcl < 0, sets value of lcl as
2216 0: the terminal named by ttname is the job's
2217 controlling terminal.
2218 1: the terminal named by ttname is not the job's
2219 controlling terminal.
2220 If the device is already open, or if the requested
2221 device can't be opened, then lcl remains (and is
2225 Less than zero: this is the negative of the network
2226 type, and ttname is a network host name. Network
2227 types (from [112]ckcnet.h:
2229 NET_TCPB 1 TCP/IP Berkeley (socket) (implemented in [113]ckutio.c)
2230 NET_TCPA 2 TCP/IP AT&T (streams) (not yet implemented)
2231 NET_DEC 3 DECnet (not yet implemented)
2233 Zero or greater: ttname is a terminal device name.
2234 Zero means a direct connection (don't use modem
2235 signals). Positive means use modem signals
2236 depending on the current setting of ttcarr (see
2240 > 0: number of seconds to wait for open() to return
2242 <=0: no timer, wait forever (e.g. for incoming
2244 For real tty devices, ttopen() attempts to gain
2245 exclusive access to the tty device, for example in
2246 UNIX by creating a "lockfile" (in other operating
2247 systems, like VMS, exclusive access probably
2248 requires no special action).
2251 Copies its arguments and the tty file descriptor to
2252 global variables that are available to the other
2253 tty-related functions, with the lcl value altered as
2254 described above. Gets all parameters and settings
2255 associated with the line and puts them in a global area,
2256 so that they can be restored by ttres(), e.g. when the
2261 -5: if device is in use
2262 -4: if access to device is denied
2263 -3: if access to lock mechanism denied
2264 -2: upon timeout waiting for device to open
2268 ttpkt(speed,flow,parity) long speed; int flow, parity;
2269 Puts the currently open tty device into the appropriate modes
2270 for transmitting and receiving Kermit packets.
2275 if speed > -1, and the device is a true tty device,
2276 and Kermit is in local mode, ttpkt also sets the
2280 if in the range 0-3, ttpkt selects the
2281 corresponding type of flow control. Currently 0 is
2282 defined as no flow control, 1 is Xon/Xoff, and no
2283 other types are defined. If (and this is a horrible
2284 hack, but it goes back many years and will be hard
2285 to eradicate) flow is 4, then the appropriate tty
2286 modes are set for modem dialing, a special case in
2287 which we talk to a modem-controlled line without
2288 requiring carrier. If flow is 5, then we require
2292 This is simply copied into a global variable so
2293 that other functions (like ttinl, ttinc, etc) can
2297 Copies its arguments to global variables, flushes the
2298 terminal device input buffer.
2306 Enables the given type of flow control on the open serial
2307 communications device immediately. Arguments are the FLO_xxx
2308 values from ckcdeb.h, except FLO_DIAL, FLO_DIAX, or FLO_AUTO,
2309 which are not actual flow-control types. Returns 0 on success,
2315 Returns a pointer to an array of longs, or NULL on failure. On
2316 success, element 0 of the array contains number, n, indicating
2317 how many follow. Elements 1-n are serial speeds, expressed in
2318 bits per second, that are legal on this platform. The user
2319 interface may use this list to construct a menu, keyword table,
2322 #endif /* TTSPDLIST */
2326 Restores the tty device to the modes and settings that were in
2327 effect at the time it was opened (see ttopen). Returns:
2332 ttruncmd(string) char * string;
2333 Runs the given command on the local system, but redirects its
2334 input and output to the communication (SET LINE, SET PORT, or
2335 SET HOST) device. Returns:
2340 ttscarr(carrier) int carrier;
2341 Copies its argument to a variable that is global to the other
2342 tty-related functions, and then returns it. The values for
2343 carrier are defined in ckcdeb.h: CAR_ON, CAR_OFF, CAR_AUTO.
2344 ttopen(), ttpkt(), and ttvt() use this variable when deciding
2345 how to open the tty device and what modes to select. The
2348 CAR_OFF: Ignore carrier at all times.
2349 CAR_ON: Require carrier at all times, except when dialing. This means,
2350 for example, that ttopen() could hang forever waiting for carrier if
2352 CAR_AUTO: If the modem type is zero (i.e. the connection is direct),
2353 this is the same as CAR_OFF. If the modem type is positive, then heed
2354 carrier during CONNECT (ttvt mode), but ignore it at other times
2355 (packet mode, during SET LINE, etc). Compatible with pre-5A versions
2356 of C-Kermit. This should be the default carrier mode.
2358 Kermit's DIAL command ignores the carrier setting, but
2359 ttopen(), ttvt(), and ttpkt() all honor the carrier option in
2360 effect at the time they are called. None of this applies to
2361 remote mode (the tty device is the job's controlling terminal)
2362 or to network host connections (modem type is negative).
2366 Sends a BREAK signal on the tty device. On a real tty device,
2367 send a real BREAK lasting approximately 275 milliseconds. If
2368 this is not possible, simulate a BREAK by (for example)
2369 dropping down some very low baud rate, like 50, and sending a
2370 bunch of null characters. On a network connection, do the
2371 appropriate network protocol for BREAK. Returns:
2377 Like ttsndb(), but sends a "Long BREAK" (approx 1.5 seconds).
2378 For network connections, it is identical to ttsndb().
2379 Currently, this function is used only if CK_LBRK is defined (as
2380 it is for UNIX and VMS).
2383 ttsspd(cps) int cps;
2384 For serial devices only, set the device transmission speed to
2385 (note carefully) TEN TIMES the argument. The argument is in
2386 characters per second, but transmission speeds are in bits per
2387 second. cps are used rather than bps because high speeds like
2388 38400 are not expressible in a 16-bit int but longs cannot be
2389 used because keyword-table values are ints and not longs. If
2390 the argument is 7, then the bps is 75, not 70. If the argument
2391 is 888, this is a special code for 75/1200 split-speed
2392 operation (75 bps out, 1200 bps in). Returns:
2393 -1: on error, meaning the requested speed is not valid or
2395 >=0: on success (don't try to use this value for anything).
2398 ttvt(speed,flow) long speed; int flow;
2399 Puts the currently open tty device into the appropriate modes
2400 for terminal emulation. The arguments are interpreted as in
2401 ttpkt(). Side effects: ttvt() stores its arguments in global
2402 variables, and sets a flag that it has been called so that
2403 subsequent calls can be ignored so long as the arguments are
2404 the same as in the last effective call. Other functions, such
2405 as ttopen(), ttclose(), ttres(), ttvt(), etc, that change the
2406 tty device in any way must unset this flag. In UNIX Kermit,
2407 this flag is called tvtflg.
2410 ttwmdm(mdmsig,timo) int mdmsig, timo;
2411 Waits up to timo seconds for all of the given modem signals to
2412 appear. mdmsig is a bit mask, in which a bit is on (1) or off
2413 (0) according to whether the corresponding signal is to be
2414 waited for. These symbols are defined in ckcdeb.h:
2415 BM_CTS (bit 0) means wait for Clear To Send
2416 BM_DSR (bit 1) means wait for Data Set Ready
2417 BM_DCD (bit 2) means wait for Carrier Detect
2419 -3: Not implemented.
2420 -2: This line does not have modem control.
2421 -1: Timeout: time limit exceeded before all signals were
2426 ttxin(n,buf) int n; CHAR *buf;
2427 Reads x characters from the tty device into the specified buf,
2428 stripping parity if parity is not none. This call waits
2429 forever, there is no timeout. This function is designed to be
2430 called only when you know that at least x characters are
2431 waiting to be read (as determined, for example, by ttchk()).
2432 This function should use the same buffer as ttinc().
2435 txbufr(timo) int timo;
2436 Reads characters into the internal communications input buffer.
2437 timo is a timeout interval, in seconds. 0 means no timeout,
2438 wait forever. Called by ttinc() (and possibly ttxin() and
2439 ttinl()) when the communications input buffer is empty. The
2440 buffer should be called ttxbuf[], its length is defined by the
2441 symbol TXBUFL. The global variable txbufn is the number of
2442 characters available to be read from ttxbuf[], and txbufp is
2443 the index of the next character to be read. Should not be
2444 called if txbufn > 0, in which case the buffer does not need
2445 refilling. This routine returns:
2446 -2: Communications disconnect
2448 >=0: A character (0 - 255) On success, the first character that
2449 was read, with the variables txbufn and txbufp set
2450 appropriately for any remaining characters.
2451 NOTE: Currently this routine is used internally only by the
2452 UNIX and VMS versions. The aim is to make it available to all
2453 versions so there is one single coherent and efficient way of
2454 reading from the communications device or network.
2456 4.E.2.6. Miscellaneous system-dependent functions
2460 Returns a pointer, s, to the current date-and-time string in s.
2461 This string must be in the fixed-field format associated with
2462 the C runtime asctime() function, like: "Sun Sep 16 13:23:45
2463 1973\n" so that callers of this function can extract the
2464 different fields. The pointer value is filled in by ztime, and
2465 the data it points to is not safe, so should be copied to a
2466 safe place before use. ztime() has no return value. As a side
2467 effect, this routine can also fill in the following two
2468 external variables (which must be defined in the
2469 system-dependendent modules for each platform):
2470 long ztusec: Fraction of seconds of clock time, microseconds.
2471 long ztmsec: Fraction of seconds of clock time, milliseconds.
2472 If these variables are not set by zstime(), they remain at
2473 their initial value of -1L.
2477 Returns the current value of the elapsed time counter in
2478 seconds (see rtimer), or 0 on any kind of error.
2483 Returns the current value of the elapsed time counter in
2484 seconds, as a floating point number, capable of representing
2485 not only whole seconds, but also the fractional part, to the
2486 millisecond or microsecond level, whatever precision is
2487 available. Requires a function to get times at subsecond
2488 precision, as well as floating-point support. That's why it's
2491 #endif /* GFTIMER */
2495 Sleeps (pauses, does nothing) for m milliseconds (a millisecond
2496 is one thousandth of a second). Returns:
2502 Sets the elapsed time counter to zero. If you want to time how
2503 long an operation takes, call rtimer() when it starts and
2504 gtimer when it ends. rtimer() has no return value.
2509 Sets the elapsed time counter to zero. If you want to time how
2510 long an operation takes, call rftimer() when it starts and
2511 gftimer when it ends. rftimer() has no return value. Note:
2512 rftimer() is to be used with gftimer() and rtimer() is to be
2513 used with gtimer(). See the rftimer() description.
2515 #endif /* GFTIMER */
2519 Does whatever needs doing upon program start. In particular, if
2520 the program is running in any kind of privileged mode, turns
2521 off the privileges (see priv_ini()). Returns:
2527 Does whatever needs doing upon program exit. Returns:
2533 Suspends the Kermit process, puts it in the background so it
2534 can be continued ("foregrounded") later. Returns:
2535 -1: if this function is not supported.
2538 [ [114]Contents ] [ [115]C-Kermit ] [ [116]Kermit Home ]
2539 ________________________________________________________________________
2541 4.F. Group F: Network Support
2543 As of version 5A, C-Kermit includes support for several networks.
2544 Originally, this was just worked into the ttopen(), ttclos(), ttinc(),
2545 ttinl(), and similar routines in [117]ckutio.c. But this made it
2546 impossible to share this code with non-UNIX versions, like VMS,
2547 AOS/VS, OS/2, etc. So as of edit 168, network code has been separated
2548 out into its own module and header file, ckcnet.c and ckcnet.h:
2550 [118]ckcnet.h: Network-related symbol definitions.
2551 [119]ckcnet.c: Network i/o (TCP/IP, X.25, etc), shared by most
2553 [120]cklnet.c: Network i/o (TCP/IP, X.25, etc) specific to Stratus
2556 The routines and variables in these modules fall into two categories:
2558 1. Support for specific network packages like SunLink X.25 and TGV
2560 2. support for specific network virtual terminal protocols like CCITT
2561 X.3 and TCP/IP Telnet.
2563 Category (1) functions are analogs to the tt*() functions, and have
2564 names like netopen, netclos, nettinc, etc. Group A-D modules do not
2565 (and must not) know anything about these functions -- they continue to
2566 call the old Group E functions (ttopen, ttinc, etc). Category (2)
2567 functions are protocol specific and have names prefixed by a protocol
2568 identifier, like tn for telnet x25 for X.25.
2570 ckcnet.h contains prototypes for all these functions, as well as
2571 symbol definitions for network types, protocols, and network- and
2572 protocol- specific symbols, as well as #includes for the header files
2573 necessary for each network and protocol.
2575 The following functions are to be provided for networks that do not
2576 use normal system i/o (open, read, write, close):
2580 To be called from within ttopen() when a network connection is
2581 requested. Calling conventions and purpose same as Group E
2586 To be called from within ttclos() when a network connection is
2587 being closed. Calling conventions and purpose same as Group E
2592 To be called from within ttchk(). Calling conventions and
2593 purpose same as Group E ttchk().
2597 To be called from within ttflui(). Calling conventions and
2598 purpose same as Group E ttflui().
2602 To send a network break (attention) signal. Calling conventions
2603 and purpose same as Group E ttsndbrk().
2607 To get a character from the network. Calling conventions same
2608 as Group E ttsndbrk().
2612 Send a "character" (byte) to the network. Calling conventions
2613 same as Group E ttoc().
2617 Send a "line" (sequence of bytes) to the network. Calling
2618 conventions same as Group E ttol().
2620 Conceivably, some systems support network connections simply by
2621 letting you open a device of a certain name and letting you do i/o to
2622 it. Others (like the Berkeley sockets TCP/IP library on UNIX) require
2623 you to open the connection in a special way, but then do normal i/o
2624 (read, write). In such a case, you would use netopen(), but you would
2625 not use nettinc, nettoc, etc.
2627 VMS TCP/IP products have their own set of functions for all network
2628 operations, so in that case the full range of netxxx() functions is
2631 The technique is to put a test in each corresponding ttxxx() function
2632 to see if a network connection is active (or is being requested), test
2633 for which kind of network it is, and if necessary route the call to
2634 the corresponding netxxx() function. The netxxx() function must also
2635 contain code to test for the network type, which is available via the
2636 global variable ttnet.
2638 [ [121]Contents ] [ [122]C-Kermit ] [ [123]Kermit Home ]
2639 ______________________________________________________________________
2641 4.F.1. Telnet Protocol
2643 (This section needs a great deal of updating...)
2645 As of edit 195, Telnet protocol is split out into its own files, since
2646 it can be implemented in remote mode, which does not have a network
2649 [124]ckctel.h: Telnet protocol symbol definitions.
2650 [125]ckctel.c: Telnet protocol.
2652 The Telnet protocol is supported by the following variables and
2656 Nonzero if telnet protocol initialized, zero otherwise.
2660 Initialize the telnet protocol (send initial options).
2664 Send a telnet option.
2668 Receive and act on a telnet option from the remote.
2672 Send terminal type using telnet protocol.
2673 ______________________________________________________________________
2677 (To be filled in...)
2678 ______________________________________________________________________
2680 4.F.3. HTTP Protocol
2682 (To be filled in...)
2683 ______________________________________________________________________
2685 4.F.4. X.25 Networks
2687 These routines were written SunLink X.25 and have since been adapted
2688 to at least on one other: IBM AIXLink/X.25.
2692 Reads and prints X.25 diagnostics
2696 X.25 out of band signal handler
2700 Sends X.25 interrupt packet
2704 Resets X.25 virtual circuit
2708 Clear X.25 virtual circuit
2724 Reads n characters from X.25 circuit.
2728 Read a Kermit packet from X.25 circuit.
2730 [ [126]Contents ] [ [127]C-Kermit ] [ [128]Kermit Home ]
2731 ______________________________________________________________________
2733 4.F.5. Adding New Network Types
2735 Example: Adding support for IBM X.25 and Hewlett Packard X.25. First,
2736 add new network type symbols for each one. There are already some
2737 network types defined for other X.25 packages:
2739 NET_SX25 is the network-type ID for SunLink X.25.
2740 NET_VX25 is the network-type ID for VOS X.25.
2742 So first you should new symbols for the new network types, giving them
2743 the next numbers in the sequence, e.g.:
2745 #define NET_HX25 11 /* Hewlett-Packard X.25 */
2746 #define NET_IX25 12 /* IBM X.25 */
2748 This is in ckcnet.h.
2750 Then we need symbols to say that we are actually compiling in the code
2751 for these platforms. These would be defined on the cc command line:
2756 So we can build C-Kermit versions for AIX and HP-UX both with and
2757 without X.25 support (since not all AIX and IBM systems have the
2758 needed libraries, and so an executable that was linked with them might
2771 And then use ANYX25 for code that is common to all of them, and IBMX25
2772 or HPX25 for code specific to IBM or HP.
2774 It might also happen that some code can be shared between two or more
2775 of these, but not the others. Suppose, for example, that you write
2776 code that applies to both IBM and HP, but not Sun or VOS X.25. Then
2777 you add the following definition to ckcnet.h:
2787 #endif /* HPORIBMX25 */
2789 You can NOT use constructions like "#if defined (HPX25 || IBMX25)";
2790 they are not portable.
2792 [ [129]Contents ] [ [130]C-Kermit ] [ [131]Kermit Home ]
2793 ________________________________________________________________________
2795 4.G. Group G: Formatted Screen Support
2797 So far, this is used only for the fullscreen local-mode file transfer
2798 display. In the future, it might be extended to other uses. The
2799 fullscreen display code is in and around the routine screenc() in
2802 In the UNIX version, we use the curses library, plus one call from the
2803 termcap library. In other versions (OS/2, VMS, etc) we insert dummy
2804 routines that have the same names as curses routines. So far, there
2805 are two methods for simulating curses routines:
2807 1. In VMS, we use the Screen Management Library (SMG), and insert
2808 stubs to convert curses calls into SMG calls.
2809 2. In OS/2, we use the MYCURSES code, in which the stub routines
2810 actually emit the appropriate escape sequences themselves.
2812 Here are the stub routines:
2815 tgetent(char *buf, char *term)
2816 Arguments are ignored. Returns 1 if the user has a supported
2817 terminal type, 0 otherwise. Sets a global variable (for
2818 example, "isvt52" or "isdasher") to indicate the terminal type.
2821 move(int row, int col)
2822 Sends the escape sequence to position the cursor at the
2823 indicated row and column. The numbers are 0-based, e.g. the
2824 home position is 0,0.
2828 Sends the escape sequence to clear the screen.
2832 Sends the escape sequence to clear from the current cursor
2833 position to the end of the line.
2835 In the MYCURSES case, code must be added to each of the last three
2836 routines to emit the appropriate escape sequences for a new terminal
2839 clearok(curscr), wrefresh()
2840 In real curses, these two calls are required to refresh the
2841 screen, for example after it was fractured by a broadcast
2842 message. These are useful only if the underlying screen
2843 management service keeps a copy of the entire screen, as curses
2844 and SMG do. C-Kermit does not do this itself.
2846 [ [133]Contents ] [ [134]C-Kermit ] [ [135]Kermit Home ]
2847 ________________________________________________________________________
2849 4.H. Group H: Pseudoterminal Support
2851 (To be filled in...)
2852 ________________________________________________________________________
2854 4.I. Group I: Security
2856 (To be filled in...)
2858 [ [136]Contents ] [ [137]C-Kermit ] [ [138]Kermit Home ]
2859 ________________________________________________________________________
2861 APPENDIX I. FILE PERMISSIONS
2863 I.1. Format of System-Dependent File Permissions in A-Packets
2865 The format of this field (the "," attribute) is interpreted according
2866 to the System ID ("." Attribute).
2868 For UNIX (System ID = U1), it's the familiar 3-digit octal number, the
2869 low-order 9 bits of the filemode: Owner, Group, World, e.g. 660 =
2870 read/write access for owner and group, none for world, recorded as a
2871 3-digit octal string. High-order UNIX permission bits are not
2874 For VMS (System ID = D7), it's a 4-digit hex string, representing the
2875 16-bit file protection WGOS fields (World,Group,Owner,System), in that
2876 order (which is the reverse of how they're shown in a directory
2877 listing); in each field, Bit 0 = Read, 1 = Write, 2 = Execute, 3 =
2878 Delete. A bit value of 0 means permission is granted, 1 means
2879 permission is denied. Sample:
2881 r-01-00-^A/!FWERMIT.EXE'"
2882 s-01-00-^AE!Y/amd/watsun/w/fdc/new/wermit.exe.DV
2883 r-02-01-^A]"A."D7""B8#119980101 18:14:05!#8531&872960,$A20B-!7(#512@ #.Y
2886 A VMS directory listing shows the file's protection as (E,RWED,RED,RE)
2887 which really means (S=E,O=RWED,G=RED,W=RE), which is reverse order
2888 from the internal storage, so (RE,RED,RWED,E). Now translate each
2889 letter to its corresponding bit:
2891 RE=0101, RED=1101, RWED=1111, E=0010
2893 Now reverse the bits:
2895 RE=1010, RED=0010, RWED=0000, E=1101
2897 This gives the 16-bit quantity:
2901 This is the internal representation of the VMS file permission; in
2906 as shown in the sample packet above.
2908 The VMS format probably would also apply to RSX or any other FILES-11
2911 I.2. Handling of Generic Protection
2913 To be used when the two systems are different (and/or do not recognize
2914 or understand each other's local protection codes).
2916 First of all, the book is wrong. This should not be the World
2917 protection, but the Owner protection. The other fields should be set
2918 according to system defaults (e.g. UNIX umask, VMS default protection,
2919 etc), except that no non-Owner field should give more permissions than
2922 [ [139]Top ] [ [140]Contents ] [ [141]C-Kermit Home ] [ [142]Kermit
2924 _________________________________________________________________
2927 C-Kermit Program Logic Manual / [143]The Kermit Project /
2928 [144]Columbia University / [145]kermit@columbia.edu / 10 April 2004
2932 1. http://www.columbia.edu/kermit/
2933 2. http://www.columbia.edu/
2934 3. http://www.columbia.edu/kermit/ckcplm.html
2935 4. http://www.columbia.edu/kermit/ckermit.html
2936 5. http://www.columbia.edu/kermit/index.html
2937 6. http://www.columbia.edu/kermit/ckcplm.html#x1
2938 7. http://www.columbia.edu/kermit/ckcplm.html#x2
2939 8. http://www.columbia.edu/kermit/ckcplm.html#x3
2940 9. http://www.columbia.edu/kermit/ckcplm.html#x4
2941 10. http://www.columbia.edu/kermit/ckcplm.html#x4.A
2942 11. http://www.columbia.edu/kermit/ckcplm.html#x4.B
2943 12. http://www.columbia.edu/kermit/ckcplm.html#x4.C
2944 13. http://www.columbia.edu/kermit/ckcplm.html#x4.D
2945 14. http://www.columbia.edu/kermit/ckcplm.html#x4.E
2946 15. http://www.columbia.edu/kermit/ckcplm.html#x4.F
2947 16. http://www.columbia.edu/kermit/ckcplm.html#x4.G
2948 17. http://www.columbia.edu/kermit/ckcplm.html#x4.H
2949 18. http://www.columbia.edu/kermit/ckcplm.html#x4.I
2950 19. http://www.columbia.edu/kermit/ckcplm.html#xa1
2951 20. http://www.columbia.edu/kermit/ckcplm.html#contents
2952 21. http://www.columbia.edu/kermit/ckcplm.html#contents
2953 22. http://www.columbia.edu/kermit/ckermit.html
2954 23. http://www.columbia.edu/kermit/index.html
2955 24. ftp://kermit.columbia.edu/kermit/c-kermit/ckcpro.w
2956 25. http://www.columbia.edu/kermit/ckcplm.html#contents
2957 26. http://www.columbia.edu/kermit/ckermit.html
2958 27. http://www.columbia.edu/kermit/index.html
2959 28. http://www.columbia.edu/kermit/ckcplm.html#x3.2
2960 29. http://www.columbia.edu/kermit/ckcplm.html#contents
2961 30. http://www.columbia.edu/kermit/ckermit.html
2962 31. http://www.columbia.edu/kermit/index.html
2963 32. http://www.columbia.edu/kermit/ckcplm.html#x4.A
2964 33. http://www.columbia.edu/kermit/ckcplm.html#contents
2965 34. http://www.columbia.edu/kermit/ckermit.html
2966 35. http://www.columbia.edu/kermit/index.html
2967 36. http://www.columbia.edu/kermit/ckcplm.html#contents
2968 37. http://www.columbia.edu/kermit/ckermit.html
2969 38. http://www.columbia.edu/kermit/index.html
2970 39. http://www.columbia.edu/kermit/ckcplm.html#contents
2971 40. http://www.columbia.edu/kermit/ckermit.html
2972 41. http://www.columbia.edu/kermit/index.html
2973 42. ftp://kermit.columbia.edu/kermit/c-kermit/ckclib.h
2974 43. ftp://kermit.columbia.edu/kermit/c-kermit/ckclib.c
2975 44. http://www.columbia.edu/kermit/ckcplm.html#x3.1
2976 45. http://www.columbia.edu/kermit/ckcplm.html#contents
2977 46. http://www.columbia.edu/kermit/ckermit.html
2978 47. http://www.columbia.edu/kermit/index.html
2979 48. ftp://kermit.columbia.edu/kermit/c-kermit/ckcsym.h
2980 49. ftp://kermit.columbia.edu/kermit/c-kermit/ckcasc.h
2981 50. ftp://kermit.columbia.edu/kermit/c-kermit/ckcsig.h
2982 51. ftp://kermit.columbia.edu/kermit/c-kermit/ckcdeb.h
2983 52. ftp://kermit.columbia.edu/kermit/c-kermit/ckcker.h
2984 53. ftp://kermit.columbia.edu/kermit/c-kermit/ckcxla.h
2985 54. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
2986 55. ftp://kermit.columbia.edu/kermit/c-kermit/ckcpro.w
2987 56. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfns.c
2988 57. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfn2.c
2989 58. ftp://kermit.columbia.edu/kermit/c-kermit/ckcfn3.c
2990 59. http://www.columbia.edu/kermit/ckcplm.html#x4.B
2991 60. http://www.columbia.edu/kermit/ckcplm.html#x4.E
2992 61. http://www.columbia.edu/kermit/ckcplm.html#x4.D
2993 62. http://www.columbia.edu/kermit/ckcplm.html#contents
2994 63. http://www.columbia.edu/kermit/ckermit.html
2995 64. http://www.columbia.edu/kermit/index.html
2996 65. http://www.columbia.edu/kermit/ckcplm.html#x4.B
2997 66. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.c
2998 67. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.h
2999 68. ftp://kermit.columbia.edu/kermit/c-kermit/ckcxla.h
3000 69. ftp://kermit.columbia.edu/kermit/c-kermit/ckuxla.h
3001 70. ftp://kermit.columbia.edu/kermit/c-kermit/ckmxla.h
3002 71. ftp://kermit.columbia.edu/kermit/c-kermit/ck?xla
3003 72. ftp://kermit.columbia.edu/kermit/c-kermit/ckcuni.h
3004 73. ftp://kermit.columbia.edu/kermit/c-kermit/ckcuni.c
3005 74. http://www.columbia.edu/kermit/ckcplm.html#contents
3006 75. http://www.columbia.edu/kermit/ckermit.html
3007 76. http://www.columbia.edu/kermit/index.html
3008 77. http://www.columbia.edu/kermit/ckcplm.html#x4.B
3009 78. ftp://kermit.columbia.edu/kermit/c-kermit/ckucmd.h
3010 79. ftp://kermit.columbia.edu/kermit/c-kermit/ckucmd.c
3011 80. http://www.columbia.edu/kermit/ckcplm.html#x4.E
3012 81. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusr.h
3013 82. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusr.c
3014 83. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus2.c
3015 84. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus3.c
3016 85. ftp://kermit.columbia.edu/kermit/c-kermit/ckuus4.c
3017 86. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusy.c
3018 87. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusx.c
3019 88. ftp://kermit.columbia.edu/kermit/c-kermit/ckuver.h
3020 89. ftp://kermit.columbia.edu/kermit/c-kermit/ckuscr.c
3021 90. ftp://kermit.columbia.edu/kermit/c-kermit/ckudia.c
3022 91. ftp://kermit.columbia.edu/kermit/c-kermit/ckucon.c
3023 92. ftp://kermit.columbia.edu/kermit/c-kermit/ckucns.c
3024 93. http://www.columbia.edu/kermit/ckcplm.html#x4.E
3025 94. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
3026 95. http://www.columbia.edu/kermit/ckcplm.html#contents
3027 96. http://www.columbia.edu/kermit/ckermit.html
3028 97. http://www.columbia.edu/kermit/index.html
3029 98. ftp://kermit.columbia.edu/kermit/c-kermit/ckufio.c
3030 99. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3031 100. ftp://kermit.columbia.edu/kermit/c-kermit/ckusig.c
3032 101. ftp://kermit.columbia.edu/kermit/c-kermit/ckvfio.c
3033 102. ftp://kermit.columbia.edu/kermit/c-kermit/ckusig.c
3034 103. ftp://kermit.columbia.edu/kermit/c-kermit/ckcmai.c
3035 104. http://www.columbia.edu/kermit/ckcplm.html#contents
3036 105. http://www.columbia.edu/kermit/ckermit.html
3037 106. http://www.columbia.edu/kermit/index.html
3038 107. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3039 108. ftp://kermit.columbia.edu/kermit/c-kermit/ckvtio.c
3040 109. http://www.columbia.edu/kermit/ckcplm.html#x2
3041 110. http://www.columbia.edu/kermit/ckcplm.html#xa1
3042 111. http://www.columbia.edu/kermit/ckuins.html
3043 112. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.h
3044 113. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3045 114. http://www.columbia.edu/kermit/ckcplm.html#contents
3046 115. http://www.columbia.edu/kermit/ckermit.html
3047 116. http://www.columbia.edu/kermit/index.html
3048 117. ftp://kermit.columbia.edu/kermit/c-kermit/ckutio.c
3049 118. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.h
3050 119. ftp://kermit.columbia.edu/kermit/c-kermit/ckcnet.c
3051 120. ftp://kermit.columbia.edu/kermit/c-kermit/cklnet.c
3052 121. http://www.columbia.edu/kermit/ckcplm.html#contents
3053 122. http://www.columbia.edu/kermit/ckermit.html
3054 123. http://www.columbia.edu/kermit/index.html
3055 124. ftp://kermit.columbia.edu/kermit/c-kermit/ckctel.h
3056 125. ftp://kermit.columbia.edu/kermit/c-kermit/ckctel.c
3057 126. http://www.columbia.edu/kermit/ckcplm.html#contents
3058 127. http://www.columbia.edu/kermit/ckermit.html
3059 128. http://www.columbia.edu/kermit/index.html
3060 129. http://www.columbia.edu/kermit/ckcplm.html#contents
3061 130. http://www.columbia.edu/kermit/ckermit.html
3062 131. http://www.columbia.edu/kermit/index.html
3063 132. ftp://kermit.columbia.edu/kermit/c-kermit/ckuusx.c
3064 133. http://www.columbia.edu/kermit/ckcplm.html#contents
3065 134. http://www.columbia.edu/kermit/ckermit.html
3066 135. http://www.columbia.edu/kermit/index.html
3067 136. http://www.columbia.edu/kermit/ckcplm.html#contents
3068 137. http://www.columbia.edu/kermit/ckermit.html
3069 138. http://www.columbia.edu/kermit/index.html
3070 139. http://www.columbia.edu/kermit/ckcplm.html#top
3071 140. http://www.columbia.edu/kermit/ckcplm.html#contents
3072 141. http://www.columbia.edu/kermit/ckermit.html
3073 142. http://www.columbia.edu/kermit/index.html
3074 143. http://www.columbia.edu/kermit/index.html
3075 144. http://www.columbia.edu/
3076 145. mailto:kermit@columbia.edu