C-Kermit Program Logic Manual

Frank da Cruz
The Kermit Project
Columbia University

As of: C-Kermit 8.0.209, 17 March 2003
This page last updated: Sun Mar 23 19:25:30 2003 (New York USA Time)

IF YOU ARE READING A PLAIN-TEXT version of this document, note that this file is a plain-text dump of a Web page. You can visit the original (and possibly more up-to-date) Web page here:

  http://www.columbia.edu/kermit/ckcplm.html

[ C-Kermit Home ] [ Kermit Home ]

---

CONTENTS

  1. INTRODUCTION
  2. FILES
  3. SOURCE CODE PORTABILITY AND STYLE
  4. MODULES
     4.A. Group A: Library Routines
     4.B. Group B: Kermit File Transfer
     4.C. Group C: Character-Set Conversion
     4.D. Group D: User Interface
     4.E. Group E: Platform-Dependent I/O
     4.F. Group F: Network Support
     4.G. Group G: Formatted Screen Support
     4.H. Group H: Pseudoterminal Support
     4.I. Group I: Security
  I. APPENDIX I: FILE PERMISSIONS

---

1. INTRODUCTION

This file describes the relationship among the modules and functions of C-Kermit 5A and later, and other programming considerations. C-Kermit is designed to be portable to any kind of computer that has a C compiler. The source code is broken into many files that are grouped according to their function, as shown in the Contents.

C-Kermit has seen constant development since 1985. Throughout its history, there has been a neverending tug-of-war among:

1. Functionality: adding new features, fixing bugs, improving performance.
2. Adding support for new platforms.
3. "Buzzword 1.0 compliance".

The latter category is the most frustrating, since it generally involves massive changes just to keep the software doing what it did before in some new setting: e.g. the K&R-to-ANSIC conversion (which had to be done, of course, without breaking K&R); Y2K (not a big deal in our case); the many and varied UNIX and other API "standards"; IPv6.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

2. FILES

a	General descriptive material and documentation (text)
b	BOO file encoders and decoders (obsolete)
c	All platforms with C compilers (*)
d	Data General AOS/VS
e	Reserved for "ckermit" files, like ckermit.ini, ckermit2.txt
f	(reserved)
g	(reserved)
h	(reserved)
i	Commodore Amiga (Intuition)
j	(unused)
k	(unused)
l	Stratus VOS
m	Macintosh with Mac OS 1-9
n	Microsoft Windows NT/2000/XP
o	OS/2 and/or Microsoft Windows 9x/ME/NT/2000/XP
p	Plan 9 from Bell Labs
q	(reserved)
r	DEC PDP-11 with RSTS/E (never used, open for reassigment)
s	Atari ST GEMDOS (last supported in version 5A(189))
t	DEC PDP-11 with RT-11 (never used, open for reassigment)
u	Unix-based operating systems (*)
v	VMS and OpenVMS
w	Wart (Lex-like preprocessor, platform independent)
x	(reserved)
y	(reserved)
z	(reserved)
0-3	(reserved)
4	IBM AS/400
5-8	(reserved)
9	Microware OS-9
_	Encryption modules

(*) In fact there is little distinction between the ckc*.* and cku*.* categories. It would make more sense for all cku*.* modules to be ckc*.* ones, except ckufio.c, ckutio.c, ckucon.c, ckucns.c, and ckupty.c, which truly are specific to Unix. The rest (ckuus*.c, ckucmd.c, etc) are quite portable.

One hint before proceeding: functions are scattered all over the ckc*.c and cku*.c modules, where function size has begun to take precedence over the desirability of grouping related functions together, the aim being to keep any particular module from growing disproportionately large. The easiest way (in UNIX) to find out in what source file a given function is defined is like this (where the desired function is foo()...):

  grep ^foo\( ck*.c

This works because the coding convention has been to make function names always start on the left margin with their contents indented, for example:

static char *
foo(x,y) int x, y; {
    ...
}

Also note the style for bracket placement. This allows bracket-matching text editors (such as EMACS) to help you make sure you know which opening bracket a closing bracket matches, particularly when the opening bracket is above the visible screen, and it also makes it easy to find the end of a function (search for '}' on the left margin).

Of course EMACS tags work nicely with this format too:

  $ cd kermit-source-directory
  $ etags ck[cu]*.c
  $ emacs
  Esc-X Visit-Tags-Table<CR><CR>

(but remember that the source file for ckcpro.c is ckcpro.w!)

Also:

• Tabs should be set every 8 spaces, as on a VT100.
• All lines must no more than 79 characters wide after tab expansion.
• Note the distinction between physical tabs (ASCII 9) and the indentation conventions, which are: 4 for block contents, 2 for most other stuff (obviously this is not a portability issue, just style).

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

3. SOURCE CODE PORTABILITY AND STYLE

• Many of them are related to feature selection and program size, and so need to be there anyway.

• Those that treat compiler, library, platform, header-file, and similar differences have built up over time as hundreds of people all over the world adapted C-Kermit to their particular environments and sent back their changes. There might be more politically-correct ways to achieve portability, but this one is natural and proven. The basic idea is to introduce changes that can be selected by defining a symbol, which, if not defined, leaves the program exactly as it was before the changes.

• Although it might be possible to "clean up" the "#ifdef mess", nobody has access to all the hundreds of platforms served by the #ifdefs to check the results.

And to answer the second-most-oft-repeated question: "Why don't you just use GNU autoconfig / automake / autowhatever instead of hard-coding all those #ifdefs?" Answers:

• The GNU tools are not available on all the platforms where C-Kermit must be built and I wouldn't necessarily trust them if they were.

• Each platform is a moving target, so the tools themselves would need to updated before Kermit could be updated.

• It would only add another layer of complexity to an already complex process.

• Conversion at this point would not be practical unless there was a way to test the results on all the hundreds of platforms where C-Kermit is supposed to build.

When writing code for the system-indendent C-Kermit modules, please stick to the following coding conventions to ensure portability to the widest possible variety of C preprocessors, compilers, and linkers, as well as certain network and/or email transports. The same holds true for many of the "system dependent" modules too; particularly the Unix ones, since they must be buildable by a wide variety of compilers and linkers, new and old.

This list does not purport to be comprehensive, and although some items on it might seem far-fetched, they would not be listed unless I had encountered them somewhere, some time. I wish I had kept better records so I could cite specific platforms and compilers.

• Try to keep variable and function names unique within 6 characters, especially if they are used across modules, since 6 is the maximum for some old linkers (actually, this goes back to TOPS-10 and -20 and other old DEC OS's where C-Kermit never ran anyway; a more realistic maximum is probably somewhere between 8 and 16). We know for certain that VAX C has a 31-character max because it complains -- others might not complain, but just silently truncate, thus folding two or more routines/variables into one.

• Keep preprocessor symbols unique within 8 characters; that's the max for some preprocessors (sorry, I can't give a specific example, but in 1988 or thereabouts, I had to change character-set symbols like TC_LATIN1 and TC_LATIN2 to TC_1LATIN and TC_2LATIN because the digits were being truncated and ignored on a platform where I actually had to build C-Kermit 5A; unfortunately I didn't note which platform -- maybe some early Ultrix version?)

• Don't create preprocessor symbols, or variable or function names, that start with underscore (_). These are usually reserved for internal use by the compiler and header files.

• Don't put #include directives inside functions or { blocks }.

• Don't use the #if or #elif preprocessor constructions, only use #ifdef, #ifndef, #define, #undef, and #endif.

• Put tokens after #endif in comment brackets, e.g. #endif /* FOO */.

• Don't indent preprocessor statements - # must always be first char on line.

• Don't put whitespace after # in preprocessor statements.

• Don't use #pragma, even within #ifdefs -- it makes some preprocessors give up.

• Same goes for #module, #if, etc - #ifdefs do NOT protect them.

• Don't use logical operators in preprocessor constructions.

• Avoid #ifdefs inside argument list to function calls (I can't remember why this one is here, but probably needn't be; we do this all the time).

• Always cast strlen() in expressions to int:
  if ((int)strlen(foo) < x)...

• Any variable whose value might exceed 16383 should be declared as long, or if that is not possible, then as unsigned.

• Avoid typedefs; they might be portable but they are very confusing and there's no way to test for their presence or absence at compile time. Use preprocessor symbols instead if possible; at least you can test their definitions.

• Unsigned long is not portable; use a preprocessor symbol (Kermit uses ULONG for this).

• Long long is not portable. If you really need it, be creative.

• Similarly 1234LL is not portable, nor almost any other constant modifier other than L.

• Unsigned char is not portable, use CHAR (a preprocessor symbol defined in the Kermit header files) and always take precautions against character signage (more about this below).

• Don't use initializers with automatic arrays or structs: it's not portable.

• Don't use big automatic arrays or structs in functions that might be called recursively; some platforms have fixed-size stacks (e.g. Windows 9x: 256K) and recursive functions crash with stack overflow. Even when there is not a compiler limitation, this causes memory to be consumed without bound, and can end up filling swap space.

• Don't assume that struct assignment performs a copy, or that it even exists.

• Don't use sizeof to get the size of an array; someone might come along later and and change it from static to malloc'd. Always use a symbol to refer to the array's size.

• Don't put prototypes for static functions into header files that are used by modules that don't contain that function; the link step can fail with unresolved references (e.g. on AOS/VS).

• Avoid the construction *++p (the order of evaluation varies; it shouldn't but at least one compiler had a bug that made me include this item).

• Don't use triple assignments, like a = b = c = 0; (or quadruple, etc). Some compilers generate bad code for these, or crash, etc (some version of DEC C as I recall).

• Some compilers don't allow structure members to have the same names as other identifiers. Try to give structure members unique names.

• Don't assume anything about order of evaluation in boolean expressions, or that they will stop early if a required condition is not true, e.g.:

    if (i > 0 && p[i-1] == blah)
  

  can still dump core if i == 0 (hopefully this is not true of any modern compiler, but I would not have said this if it did not actually happen somewhere).

• Don't have a switch() statement with no cases (e.g. because of #ifdefs); this is a fatal error in some compilers.

• Don't put lots of code in a switch case; move it out to a separate function; some compilers run out of memory when presented with a huge switch() statement -- it's not the number of cases that matters; it's the overall amount of code.

• Some compilers might also limit the number of switch() cases, e.g. to 254.

• Don't put anything between "switch() {" and "case:" -- switch blocks are not like other blocks.

• Don't jump into or out of switches.

• Don't make character-string constants longer than about 250 bytes. Longer strings should be broken up into arrays of strings.

• Don't write into character-string constants (obviously). Even when you know you are not writing past the end; the compiler or linker might have put them into read-only and/or shared memory, and/or coalesced multiple equal constants so if you change one you change them all.

• Don't depend on '\r' being carriage return.

• Don't depend on '\n' being linefeed or for that matter any SINGLE character.

• Don't depend on '\r' and '\n' being different (e.g. as separate switch() cases).

• In other words, don't use \n or \r to stand for specific characters; use \012 and \015 instead.

• Don't code for "buzzword 1.0 compliance", unless "buzzword" is K&R and "1.0" is the first edition.

• Don't use or depend on anything_t (size_t, pid_t, etc), except time_t, without #ifdef protection (time_t is the only one I've found that is accepted everywhere). This is a tough one because the same function might require (say) a size_t arg on one platform, whereas size_t is unheard of on another; or worse, it might require a totally different data type, like int or long or some other typedef'd thing. It has often proved necessary to define a symbol to stand for the type of a particular argument to a particular library or system function to get around this problem.

• Don't use or depend on internationalization ("i18n") features, wchar_t, locales, etc, in portable code; they are not portable. Anyway, locales are not the right model for Kermit's multi-character-set support. Kermit does all character-set conversion itself and does not use any external libraries or functions.

• In particular, don't use any library functions that deal with wide characters or Unicode in any form. These are not only nonportable, but a constantly shifting target (e.g. the ones in glibc).

• Don't make any assumption about signal handler type. It can be void, int, long, or anything else. Always declare signal handlers as SIGTYP (see definition in ckcdeb.h and augment it if necessary) and always use SIGRETURN at exit points from signal handlers.

• Signals should always be re-armed to be used again (this barely scratches the surface -- the differences between BSD/V7 and System V and POSIX signal handling are numerous, and some platforms do not even support signals, alarms, or longjmps correctly or at all -- avoid all of this if you can).

• On the other hand, don't assume that signals are disarmed after being raised. In some platforms you have to re-arm them, in others they stay armed.

• Don't call malloc() and friends from a signal handler; don't do anything but setting integer global variables in a signal handler.

• malloc() does not initialize allocated memory -- it never said it did. Don't expect it to be all 0's.

• Did You Know: malloc() can succeed and the program can still dump core later when it attempts to use the malloc'd memory? (This happens when allocation is deferred until use and swap space is full.)

• memset(), memmove(), and memcpy() are not portable, don't use them without protecting them in ifdefs (we have USE_MEMCPY for this). bzero()/bcopy() too, except we're guaranteed to have bzero()/bcopy() when using the sockets library (not really). See examples in the source.

• Don't assume that strncpy() stops on the first null byte -- most versions always copy the number of bytes given in arg 3, padding out with 0's and overwriting whatever was there before. Use C-Kermit ckstrncpy() if you want predictable non-padding behavior, guaranteed NUL-termination, and a useful return code.

• DID YOU KNOW.. that some versions of inet_blah() routines return IP addresses in network byte order, while others return them local machine byte order? So passing them to ntohs() or whatever is not always the right thing to do.

• Don't use ANSI-format function declarations without #ifdef CK_ANSIC, and always provide an #else for the non-ANSI case.

• Use the Kermit _PROTOTYP() macro for declaring function prototypes; it works in both the ANSI and non-ANSI cases.

• Don't depend on any other ANSI preprocessor features like "pasting" -- they are often missing or nonoperational.

• Don't assume any C++ syntax or semantics.

• Don't use // as a comment introducer. C is not C++.

• Don't declare a string as "char foo[]" in one module and "extern char * foo" in another, or vice-versa: this causes core dumps.

• With compiler makers falling all over themselves trying to outdo each other in ANSI strictness, it has become increasingly necessary to cast EVERYTHING. This is increasingly true for char vs unsigned char. We need to use unsigned chars if we want to deal with 8-bit character sets, but most character- and string-oriented APIs want (signed) char arguments, so explicit casts are necessary. It would be nice if every compiler had a -funsigned-char option (as gcc does), but they don't.

• a[x], where x is an unsigned char, can produce a wild memory reference if x, when promoted to an int, becomes negative. Cast it to (unsigned), even though it ALREADY IS unsigned.

• Be careful how you declare functions that have char or long arguments; for ANSI compilers you MUST use ANSI declarations to avoid promotion problems, but you can't use ANSI declarations with non-ANSI compilers. Thus declarations of such functions must be hideously entwined in #ifdefs. Example: latter:

    int                          /*  Put character in server command buffer  */
    #ifdef CK_ANSIC
    putsrv(char c)
    #else
    putsrv(c) char c;
    #endif /* CK_ANSIC */
    /* putsrv */ {
        *srvptr++ = c;
        *srvptr = '\0';           /* Make sure buffer is null-terminated */
        return(0);
    }
  

• Be careful how you return characters from functions that return int values -- "getc-like functions" -- in the ANSI world. Unless you explicitly cast the return value to (unsigned), it is likely to be "promoted" to an int and have its sign extended.

• At least one compiler (the one on DEC OSF/1 1.3) treats "/*" and "*/" within string constants as comment begin and end. No amount of #ifdefs will get around this one. You simply can't put these sequences in a string constant, e.g. "/usr/local/doc/*.*".

• Avoid putting multiple macro references on a single line, e.g.:

    putchar(BS); putchar(SP); putchar(BS)
  

This overflows the CPP output buffer of more than a few C preprocessors (this happened, for example, with SunOS 4.1 cc, which evidently has a 1K macro expansion buffer).

C-Kermit needs constant adjustment to new OS and compiler releases. Every new OS release shuffles header files or their contents, or prototypes, or data types, or levels of ANSI strictness, etc. Every time you make an adjustment to remove a new compilation error, BE VERY CAREFUL to #ifdef it on a symbol unique to the new configuration so that the previous configuration (and all other configurations on all other platforms) remain as before.

Assume nothing. Don't assume header files are where they are supposed to be, that they contain what you think they contain, that they define specific symbols to have certain values -- or define them at all! Don't assume system header files protect themselves against multiple inclusion. Don't assume that particular system or library calls are available, or that the arguments are what you think they are -- order, data type, passed by reference vs value, etc. Be conservative when attempting to write portable code. Avoid all advanced features.

If you see something that does not make sense, don't assume it's a mistake -- it might be there for a reason, and changing it or removing is likely to cause compilation, linking, or runtime failures sometime, somewhere. Some huge percentage of the code, especially in the platform-dependent modules, is workarounds for compiler, linker, or API bugs.

But finally... feel free to violate any or all of these rules in platform-specific modules for environments in which the rules are certain not to apply. For example, in VMS-specific code, it is OK to use #if, because VAX C, DEC C, and VMS GCC all support it.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

3.1. Memory Leaks

This problem is partially addressed by the strn...() routines, which should always be used in preference to their str...() equivalents (except when the copy operation has already been prechecked, or there is a good reason for not using them, e.g. the sometimes undesirable side effect of strncpy() zeroing the remainder of the buffer). The most gaping whole, however, is sprintf(), which performs no length checking on its destination buffer, and is not easy to replace. Although snprintf() routines are starting to appear, they are not yet widespread, and certainly not universal, nor are they especially portable, or even full-featured.

For these reasons, we have started to build up our own little library of C Library replacements, ckclib.[ch]. These are safe and highly portable primitives for memory management and string manipulation, such as:

ckstrncpy()

Like strncpy but returns a useful value, doesn't zero buffer.

ckitoa()

Opposite of atoi()

ckltoa()

Opposite of atol()

ckctoa()

Returns character as string

ckmakmsg()

Used with ck?to?() as a safe sprintf() replacement for up to 4 items

ckmakxmsg()

Like ckmakmsg() but accepts up to 12 items

More about library functions in Section 4.A.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

3.2. The "char" vs "unsigned char" Dilemma

Some modern compilers (e.g. IBM, DEC, Microsoft) have options that say "make all chars be unsigned" (e.g. GCC "-funsigned-char") and we use them when they are available. Other compilers don't have this option, and at the same time, are becoming increasingly strict about type mismatches, and spew out torrents of warnings when we use a CHAR where a char is expected, or vice versa. We fix these one by one using casts, and the code becomes increasingly ugly. But there remains a serious problem, namely that certain library and kernel functions have arguments that are declared as signed chars (or pointers to them), whereas our character data is unsigned. Fine, we can can use casts here too -- but who knows what happens inside these routines.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4. MODULES

On another axis, C-Kermit can be in any of several major states:

Command State

Reading and writing from the job's controlling terminal or "console". In this mode, all i/o is handled by the Group E conxxx() (console i/o) routines.

Protocol State

Reading and writing from the communicatons device. In this mode, all i/o is handled by the Group E ttxxx() (terminal i/o) routines.

Terminal State

Reading from the keyboard with conxxx() routines and writing to the communications device with ttxxx() routines AND vice-versa.

When in local mode, the console and communications device are distinct. During file transfer, Kermit may put up a file-transfer display on the console and sample the console for interruption signals.

When in remote mode, the console and communications device are the same, and therefore there can be no file-transfer display on the console or interruptions from it (except for "in-band" interruptions such as ^C^C^C).

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.A. Group A: Library Functions

(To be filled in... For now, see Section 3.1 and the comments in ckclib.c.)

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.B. Group B: Kermit File Transfer

ckcsym.h

For use by C compilers that don't allow -D on the command line.

ckcasc.h

ASCII character symbol definitions.

ckcsig.h

System-independent signal-handling definitions and prototypes.

ckcdeb.h

Originally, debugging definitions. Now this file also contains all definitions and prototypes that are shared by all modules in all groups.

ckcker.h

Kermit protocol symbol definitions.

ckcxla.h

Character-set-related symbol definitions (see next section).

ckcmai.c

The main program. This module contains the declarations of all the protocol-related global variables that are shared among the other modules.

ckcpro.w

The protocol module itself, written in "wart", a lex-like preprocessor that is distributed with Kermit under the name CKWART.C.

ckcfns.c, ckcfn2.c, ckcfn3.c

The protocol support functions used by the protocol module.

Group B modules may call upon functions from Group E, but not from Group D modules (with the single exception that the main program invokes the user interface, which is in Group D). (This last assertion is really only a conjecture.)

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.C. Group C: Character-Set Conversion

ckcxla.h

Character-set definitions usable by all versions of C-Kermit.

ck?xla.h

Character-set definitions for computer "?", e.g. ckuxla.h for UNIX, ckmxla.h for Macintosh.

ck?xla

Character-set translation tables and functions for computer "?", For example, CKUXLA.C for UNIX, CKMXLA.C for Macintosh. So far, these are the only two such modules. The UNIX module is used for all versions of C-Kermit except the Macintosh version.

ckcuni.h

Unicode definitions

ckcuni.c

Unicode module

Here's how to add a new file character set in the original (non-Unicode modules). Assuming it is based on the Roman (Latin) alphabet. Let's call it "Barbarian". First, in ck?xla.h, add a definition for FC_BARBA (8 chars maximum length) and increase MAXFCSETS by 1. Then, in ck?xla.c:

• Add a barbarian entry into the fcsinfo array.
• Add a "barbarian" entry to file character set keyword table, fcstab.
• Add a "barbarian" entry to terminal character set keyword table, ttcstab.
• Add a translation table from Latin-1 to barbarian: yl1ba[].
• Add a translation table from barbarian to Latin-1: ybal1[].
• Add a translation function from Barbarian to ASCII: xbaas().
• Add a translation function from Barbarian to Latin-1: xbal1().
• Add a translation function from Latin-1 to Barbarian: xl1ba().
• etc etc for each transfer character set...
• Add translation function pointers to the xls and xlr tables.

Other translations involving Barbarian (e.g. from Barbarian to Latin-Cyrillic) are performed through these tables and functions. See ckuxla.h and ckuxla.c for extensive examples.

To add a new Transfer Character Set, e.g. Latin Alphabet 9 (for the Euro symbol), again in the "old" character-set modules:

In ckcxla.h:

• Add a TC_xxxx definition and increase MAXTCSETS accordingly.

In ck?xla.h (since any transfer charset is also a file charset):

• Add an FC_xxxx definition and increase MAXFCSETS accordingly.

In ck?xla.c:

• Add a tcsinfo[] entry.
• Make a tcstab[] keyword table entry.
• Make an fcsinfo[] table entry.
• Make an fcstab[] keyword table entry.
• Make a tcstab[] keyword table entry.
• If necessary, make a langinfo[] table entry.
• Make entries in the function pointer arrays.
• Provide any needed functions.

As of C-Kermit 7.0, character sets are also handled in parallel by the new (and very large) Unicode module, ckcuni.[ch]. Eventually we should phase out the old way, described just above, and operate entirely in (and through) Unicode. The advantages are many. The disadvantages are size and performance. To add a character to the Unicode modules:

In ckcuni.h:

• (To be filled in...)

In ckcuni.c:

• (To be filled in...)

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.D. Group D: User Interface

1. Sets the parameters for the file transfer and then starts it. This is done by setting certain (many) global variables, such as the protocol machine start state, the file specification, file type, communication parameters, packet length, window size, character set, etc.

2. Displays messages on the user's screen during the file transfer, using the screen() function, which is called by the group-1 modules.

3. Executes any commands directly that do not require Kermit protocol, such as the CONNECT command, local file management commands, parameter-setting commands, FTP client commands, etc.

If you plan to imbed the Group B, files into a program with a different user interface, your interface must supply an appropriate screen() function, plus a couple related ones like chkint() and intmsg() for handling keyboard (or mouse, etc) interruptions during file transfer. The best way to find out about this is to link all the C-Kermit modules together except the ckuu*.o and ckucon.o modules, and see which missing symbols turn up.

C-Kermit's character-oriented user interface (as opposed to the Macintosh version's graphical user interface) consists of the following modules. C-Kermit can be built with an interactive command parser, a command-line-option-only parser, a graphical user interface, or any combination, and it can even be built with no user interface at all (in which case it runs as a remote-mode Kermit server).

ckucmd.h

ckucmd.c

The command parsing primitives used by the interactive command parser to parse keywords, numbers, filenames, etc, and to give help, complete fields, supply defaults, allow abbreviations and editing, etc. This package is totally independent of Kermit, but does depend on the Group E functions.

ckuusr.h

Definitions of symbols used in Kermit's commands.

ckuus*.c

Kermit's interactive command parser, including the script programming language: ckuusr.c (includes top-level keyword tables); ckuus2.c (HELP command text); ckuus3.c (most of the SET command); ckuus4.c (includes variables and functions); ckuus[567].c (miscellaneous);

ckuusy.c

The command-line-option parser.

ckuusx.c

User interface functions common to both the interactive and command-line parsers.

ckuver.h

Version heralds for different implementations.

ckuscr.c

The (old, uucp-like) SCRIPT command

ckudia.c

The DIAL command. Includes specific knowledge of many types of modems.

Note that none of the above files is actually Unix-specific. Over time they have proven to be portable among all platforms where C-Kermit is built: Unix, VMS, AOS/VS, Amiga, OS-9, VOS, etc etc. Thus the third letter should more properly be "c", but changing it would be too confusing.

ck?con.c, ckucns.c

The CONNECT command. Terminal connection, and in some cases (Macintosh, Windows) also terminal emulation. NOTE: As of C-Kermit 7.0, there are two different CONNECT modules for UNIX: ckucon.c -- the traditional, portable, fork()-based version -- and ckucns.c, a new version that uses select() rather than forks so it can handle encryption. ckucns.c is the preferred version for Unix; ckucon.c is not likely to keep pace with it in terms of upgrades, etc. However, since select() is not portable to every platform, ckucon.c will be kept indefinitely for those platforms that can't use ckucns.c. NOTE: SunLink X.25 support is available only in ckucon.c.

ck_*.*, ckuat*.*

Modules having to do with authentication and encryption. Since the relaxation of USA export laws, they are included with the general source-code distribution. Secure C-Kermit binaries can be built using special targets in the standard makefile. However, secure prebuilt binaries may not be distributed.

For other implementations, the files may, and probably do, have different names. For example, the Macintosh graphical user interface filenames start with "ckm". Kermit 95 uses the ckucmd and ckuus* modules, but has its own CONNECT command modules. And so on.

Here is a brief description of C-Kermit's "user interface interface", from ckuusr.c. It is nowhere near complete; in particular, hundreds of global variables are shared among the many modules. These should, some day, be collected into classes or structures that can be passed around as needed; not only for purity's sake, but also to allow for multiple simultaneous communication sessions and or user interfaces. Our list of things to do is endless, and reorganizing the source is almost always at the bottom.

The ckuus*.c modules (like many of the ckc*.c modules) depend on the existence of C library features like fopen, fgets, feof, (f)printf, argv/argc, etc. Other functions that are likely to vary among operating systems -- like setting terminal modes or interrupts -- are invoked via calls to functions that are defined in the Group E platform-dependent modules, ck?[ft]io.c. The command line parser processes any arguments found on the command line, as passed to main() via argv/argc. The interactive parser uses the facilities of the cmd package (developed for this program, but, in theory, usable by any program). Any command parser may be substituted for this one. The only requirements for the Kermit command parser are these:

1. Set parameters via global variables like duplex, speed, ttname, etc. See ckcmai.c for the declarations and descriptions of these variables.

2. If a command can be executed without the use of Kermit protocol, then execute the command directly and set the sstate (start state) variable to 0. Examples include SET commands, local directory listings, the CONNECT command.

3. If a command requires the Kermit protocol, set the following variables:

    sstate                             string data
      'x' (enter server mode)            (none)
      'r' (send a 'get' command)         cmarg, cmarg2
      'v' (enter receive mode)           cmarg2
      'g' (send a generic command)       cmarg
      's' (send files)                   nfils, cmarg & cmarg2 OR cmlist
      'c' (send a remote host command)   cmarg
   
   

   cmlist is an array of pointers to strings.
   cmarg, cmarg2 are pointers to strings.
   nfils is an integer (hmmm, probably should be an unsigned long).

   cmarg can be:

   A filename string (possibly wild), or:
   a pointer to a prefabricated generic command string, or:
   a pointer to a host command string.

   cmarg2 is:

   The name to send a single file under, or:
   the name under which to store an incoming file; must not be wild.
   If it's the name for receiving, a null value means to store the file under the name it arrives with.

   cmlist is:

   A list of nonwild filenames, such as passed via argv.

   nfils is an integer, interpreted as follows:

   -1: filespec (possibly wild) in cmarg, must be expanded internally.
   0: send from stdin (standard input).
   >0: number of files to send, from cmlist.

The screen() function is used to update the screen during file transfer. The tlog() function writes to a transaction log (if TLOG is defined). The debug() function writes to a debugging log (if DEBUG is defined). The intmsg() and chkint() functions provide the user i/o for interrupting file transfers.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.E. Group E: Platform-Dependent I/O

For VMS, the files are ckvfio.c, ckvtio.c, and ckusig.c (VMS can use the same signal handling routines as Unix). It doesn't really matter what the files are called, except for Kermit distribution purposes (grouping related files together alphabetically), only that each function is provided with the name indicated, observes the same calling and return conventions, and has the same type.

The Group E modules contain both functions and global variables that are accessed by modules in the other groups. These are now described.

(By the way, I got this list by linking all the C-Kermit modules together except ckutio and ckufio. These are the symbols that ld reported as undefined. But that was a long time ago, probably circa Version 6.)

4.E.1. Global Variables

char *DELCMD;

Pointer to string containing command for deleting files.
Example: char *DELCMD = "rm -f "; (UNIX)
Example: char *DELCMD = "delete "; (VMS)
Note trailing space. Filename is concatenated to end of this string. NOTE: DELCMD is used only in versions that do not provide their own built-in DELETE command.

char *DIRCMD;

Pointer to string containing command for listing files when a filespec is given.
Example: char *DIRCMD = "/bin/ls -l "; (UNIX)
Example: char *DIRCMD = "directory "; (VMS)
Note trailing space. Filename is concatenated to end of this string. NOTE: DIRCMD is used only in versions that do not provide their own built-in DIRECTORY command.

char *DIRCM2;

Pointer to string containing command for listing files when a filespec is not given. (currently not used, handled in another way.)
Example: char *DIRCMD2 = "/bin/ls -ld *";
NOTE: DIRCMD2 is used only in versions that do not provide their own built-in DIRECTORY command.

char *PWDCMD;

Pointer to string containing command to display current directory.
Example: char *PWDCMD = "pwd ";
NOTE: PWDCMD is used only in versions that do not provide their own built-in PWD command.

char *SPACMD;

Pointer to command to display free disk space in current device/directory.
Example: char *SPACMD = "df .";
NOTE: SPACMD is used only in versions that do not provide their own built-in SPACE command.

char *SPACM2;

Pointer to command to display free disk space in another device/directory.
Example: char *SPACM2 = "df ";
Note trailing space. Device or directory name is added to this string. NOTE: SPACMD2 is used only in versions that do not provide their own built-in SPACE command.

char *TYPCMD;

Pointer to command for displaying the contents of a file.
Example: char *TYPCMD = "cat ";
Note trailing space. Device or directory name is added to this string. NOTE: TYPCMD is used only in versions that do not provide their own built-in TYPE command.

char *WHOCMD;

Pointer to command for displaying logged-in users.
Example: char *WHOCMD = "who ";
Note trailing space. Specific user name may be added to this string.

int backgrd = 0;

Flag for whether program is running in foreground (0) or background (nonzero). Background operation implies that screen output should not be done and that all errors should be fatal.

int ckxech;

Flag for who is to echo console typein:
1: The program (system is not echoing).
0: The OS, front end, terminal, etc (not this program).

char *ckxsys;

Pointer to string that names the computer and operating system.
Example: char *ckxsys = " NeXT Mach 1.0";
Tells what computer system ckxv applies to. In UNIX Kermit, this variable is also used to print the program herald, and in the SHOW VERSION command.

char *ckxv;

Pointer to version/edit info of ck?tio.c module.
Example: char *ckxv = "UNIX Communications Support, 6.0.169, 6 Sep 96";
Used by SHOW VERSION command.

char *ckzsys;

Like ckxsys, but briefer.
Example: char *ckzsys = " 4.3 BSD";
Tells what platform ckzv applies to. Used by the SHOW VERSION command.

char *ckzv;

Pointer to version/edit info of ck?fio.c module.
Example: char *ckzv = "UNIX File support, 6.0.113, 6 Sep 96";
Used by SHOW VERSION command.

int dfflow;

Default flow control. 0 = none, 1 = Xon/Xoff, ... (see FLO_xxx symbols in ckcdeb.h)
Set by Group E module. Used by ckcmai.c to initialize flow control variable.

int dfloc;

Default location. 0 = remote, 1 = local. Set by Group E module. Used by ckcmai.c to initialize local variable. Used in various places in the user interface.

int dfprty;

Default parity. 0 = none, 'e' = even, 'o' = odd, 'm' = mark, 's' = space. Set by Group E module. Used by ckcmai.c to initialize parity variable.

char *dftty;

Default communication device. Set by Group E module. Used in many places. This variable should be initialized the the symbol CTTNAM, which is defined in ckcdeb.h, e.g. as "/dev/tty" for UNIX, "TT:" for VMS, etc. Example: char *dftty = CTTNAM;

char *mtchs[];

Array of string pointers to filenames that matched the most recent wildcard match, i.e. the most recent call to zxpand(). Used (at least) by command parsing package for partial filename completion.

int tilde_expand;

Flag for whether to attempt to expand leading tildes in directory names (used in UNIX only, and then only when the symbol DTILDE is defined.

int ttnproto;

The protocol being used to communicate over a network device. Values are defined in ckcnet.h. Example: NP_TELNET is network protocol "telnet".

int maxnam;

The maximum length for a filename, exclusive of any device or directory information, in the format of the host operating system.

int maxpath;

The maximum length for a fully specified filename, including device designator, directory name, network node name, etc, in the format of the host operating system, and including all punctuation.

int ttyfd;

File descriptor of the communication device. -1 if there is no open or usable connection, including when C-Kermit is in remote mode. Since this is not implemented everywhere, references to it are in #ifdef CK_TTYFD..#endif.

[ Contents ] [ C-Kermit ] [ Kermit Home ]

---

4.E.2. Functions

4.E.2.1. File-Related Functions

  #define ZCTERM      0           /* Console terminal */
  #define ZSTDIO      1           /* Standard input/output */
  #define ZIFILE      2           /* Current input file for SEND command */
  #define ZOFILE      3           /* Current output file for RECEIVE command */
  #define ZDFILE      4           /* Current debugging log file */
  #define ZTFILE      5           /* Current transaction log file */
  #define ZPFILE      6           /* Current packet log file */
  #define ZSFILE      7           /* Current session log file */
  #define ZSYSFN      8           /* Input from a system function (pipe) */
  #define ZRFILE      9           /* Local file for READ command */  (NEW)
  #define ZWFILE     10           /* Local file for WRITE command */ (NEW)
  #define ZMFILE     11           /* Auxilliary file for internal use */ (NEW)
  #define ZNFILS     12           /* How many defined file numbers */

In the descriptions below, fn refers to a filename, and n refers to one of these file numbers. Functions are of type int unless otherwise noted, and are listed mostly alphabetically.

int
chkfn(n) int n;

Checks the file number n. Returns:
 -1: File number n is out of range
  0: n is in range, but file is not open
  1: n in range and file is open

int
iswild(filspec) char *filespec;

Checks if the file specification is "wild", i.e. contains metacharacters or other notations intended to match multiple filenames. Returns:
  0: not wild
  1: wild.

int
isdir(string) char *string;

Checks if the string is the name of an existing directory. The idea is to check whether the string can be "cd'd" to, so in some cases (e.g. DOS) it might also indicate any file structured device, such as a disk drive (like A:). Other nonzero returns indicate system-dependent information; e.g. in VMS isdir("[.FOO]") returns 1 but isdir("FOO.DIR;1") returns 2 to indicate the directory-file name is in a format that needs conversion before it can be combined with a filename. Returns:
  0: not a directory (including any kind of error)
  1: it is an existing directory

char *
zfcdat(name) char *name;

Returns modification (preferably, otherwise creation) date/time of file whose name is given in the argument string. Return value is a pointer to a string of the form yyyymmdd hh:mm:ss, for example 19931231 23:59:59, which represents the local time (no timezone or daylight savings time finagling required). Returns the null string ("") on failure. The text pointed to by the string pointer might be in a static buffer, and so should be copied to a safe place by the caller before any subsequent calls to this function.

struct zfnfp *
zfnqfp(fn, buflen, buf) char * fn; int buflen; char * buf;

Given the filename fn, the corresponding fully qualified, absolute filename is placed into the buffer buf, whose length is buflen. On failure returns a NULL pointer. On success returns a pointer to a struct zfnfp containing pointers to the full pathname and to just the filename, and an int giving the length of the full pathname. All references to this function in mainline code must be protected by #ifdef ZFNQFP..#endif, because it is not present in all of the ck*fio.c modules. So if you implement this function in a version that did not have it before, be sure to add #define ZFNQFP in the appropriate spot in ckcdeb.h or in the build-procedure CFLAGS.

int
zcmpfn(s1,s2) char * s2, * s2;

Compares two filenames to see if they refer to the same. Internally, the arguments can be converted to fully qualified pathnames, e.g. with zfnqfp(), realpath(), or somesuch. In Unix or other systems where symbolic links exist, the link should be resolved before making the comparison or looking at the inodes. Returns:
  0: Files are not identical.
  1: Files are identical.

int
zfseek(pos) long pos;

Positions the input pointer on the current input file to the given position. The pos argument is 0-based, the offset (distance in bytes) from beginning of the file. Needed for RESEND, PSEND, and other recovery operations. This function is not necessarily possible on all systems, e.g. record-oriented systems. It should only be used on binary files (i.e. files we are sending in binary mode) and stream-oriented file systems. Returns:
 -1: on failure.
  0: On success.

int
zchdir(dirnam) char *dirnam;

Changes current or default directory to the one given in dirnam. Returns:
  0: On failure.
  1: on success.

long
zchki(fn) char *fn;

Check to see if file with name fn is a regular, readable, existing file, suitable for Kermit to send -- not a directory, not a symbolic link, etc. Returns:
 -3: if file exists but is not accessible (e.g. read-protected);
 -2: if file exists but is not of a readable type (e.g. a directory);
 -1: on error (e.g. file does not exist, or fn is garbage);
>=0: (length of file) if file exists and is readable.
Also see isdir(), zgetfs().

int
zchkpid(pid) unsigned long pid;

Returns:
  1: If the given process ID (e.g. pid in UNIX) is valid and active
  0: otherwise.

long
zgetfs(fn) char *fn;

Gets the size of the given file, regardless of accessibility. Used for directory listings. Unlike zchki(), should return the size of any kind of file, even a directory. zgetfs() also should serve as a mini "get file info" function that can be used until we design a better one, by also setting some global variables:
  int zgfs_link   = 1/0 = file is (not) a symbolic link.
  int zgfs_dir    = 1/0 = file is (not) a directory.
  char linkname[] = if zgfs_link != 0, name of file link points to.
Returns:
 -1: on error (e.g. file does not exist, or fn is garbage);
>=0: (length of file) if file exists and is readable.

int
zchko(fn) char *fn;

Checks to see if a file of the given name can be created. Returns:
 -1: if file cannot be created, or on any kind of error.
  0: if file can be created.

int
zchkspa(fn,len) char *f; long len;

Checks to see if there is sufficient space to store the file named fn, which is len bytes long. If you can't write a function to do this, then just make a dummy that always returns 1; higher level code will recover from disk-full errors. The receiving Kermit uses this function to refuse an incoming file based on its size, via the attribute mechanism. Returns:
 -1: on error.
  0: if there is not enough space.
  1: if there is enough space.

int
zchin(n,c) int n; int *c;

Gets a character from file number n, return it in c (call with &c). Returns:
 -1: on failure, including EOF.
  0: on success with character in c.

int
zchout(n,c) int n; char c;

Writes the character c to file number n. Returns:
 -1: on error.
  0: on success.

int
zclose(n) int n;

Closes file number n. Returns:
 -1: on error.
  1: on success.

int
zdelet(fn) char *name;

Attempts to delete (remove, erase) the named file. Returns:
 -1: on error.
  1: if file was deleted successfully.

char *
zgperm(char * f)

Returns a pointer to the system-dependent numeric permissions/protection string for file f, or NULL upon failure. Used if CK_PERMS is defined.

char *
ziperm(char * f)

Returns a pointer to the system-dependent symbolic permissions/protection string for file f, or NULL upon failure. Used if CK_PERMS is defined. Example: In UNIX zgperm(f) might return "100770", but ziperm() might return "-rwxrwx---". In VMS, zgperm() would return a hexadecimal string, but ziperm() would return something like "(RWED,RWED,RE,)".

char *
zgtdir()

Returns a pointer to the name of the current directory, folder, etc, or a NULL pointer if the current directory cannot be determined. If possible, the directory specification should be (a) fully specified, e.g. as a complete pathname, and (b) be suitable for appending a filename. Thus, for example, Unix directory names should end with '/'. VMS directory names should look like DEV:[NAME] (rather than, say, NAME.DIR;1).

char *
zhome()

Returns a pointer to a string containing the user's home directory, or NULL upon error. Should be formatted like zgtdir() (q.v.).

int
zinfill()

Fill buffer from input file. This function is used by the macro zminchar(), which is defined in ckcker.h. zminchar() manages its own buffer, and calls zinfill() to fill it whenever it becomes empty. It is used only for sending files, and reads characters only from file number ZIFILE. zinfill() returns -1 upon end of file, -2 upon fatal error, and -3 upon timeout (e.g. when reading from a pipe); otherwise it returns the first character from the buffer it just read.

int
zkself()

Kills the current job, session, process, etc, logs out, disappears. Used by the Kermit server when it receives a BYE command. On failure, returns -1. On success, does not return at all! This function should not be called until all other steps have been taken to close files, etc.

VOID
zstrip(fn,&fn2) char *fn1, **fn2;

Strips device and directory, etc, from file specification fn, leaving only the filename (including "extension" or "filetype" -- the part after the dot). For example DUA0:[PROGRAMS]OOFA.C;3 becomes OOFA.C, or /usr/fdc/oofa.c becomes oofa.c. Returns a pointer to result in fn2.

int
zsetperm(char * file, unsigned int code)

Set permissions of file to given system-dependent code.   0: On failure.
  1: on success.

int
zsetroot(char * dir)

Sets the root for the user's file access, like Unix chroot(), but does not require privilege. In Unix, this must be implemented entirely by Kermit's own file access routines. Returns:
  1: Success
 -1: Invalid argument
 -2:
 -3: Internal error
 -4: Access to given directory denied
 -5: New root not within old root

int
zinroot(char * file)

If no root is set (zsetroot()), returns 1.
Otherwise, if given file is in the root, returns 1.
Otherwise, returns 0.

VOID
zltor(fn,fn2) char *fn1, *fn2;

Local-To-Remote filename translation. OBSOLETE: replaced by nzltor() (q.v.). Translates the local filename fn into a format suitable for transmission to an arbitrary type of computer, and copies the result into the buffer pointed to by fn2. Translation may involve (a) stripping the device and/or directory/path name, (b) converting lowercase to uppercase, (c) removing spaces and strange characters, or converting them to some innocuous alphabetic character like X, (d) discarding or converting extra periods (there should not be more than one). Does its best. Returns no value. name2 is a pointer to a buffer, furnished by the caller, into which zltor() writes the resulting name. No length checking is done.

#ifdef NZLTOR
VOID
nzltor(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int convert,pathnames,max;

Replaces zltor(). This new version handles pathnames and checks length. fn1 and fn2 are as in zltor(). This version is called unconditionally for each file, rather than only when filename conversion is enabled. Pathnames can have the following values:

  PATH_OFF: Pathname, if any, is to be stripped
  PATH_REL: The relative pathname is to be included
  PATH_ABS: The full pathname is to be included

After handling pathnames, conversion is done to the result as in the zltor() description if convert != 0; if relative or absolute pathnames are included, they are converted to UNIX format, i.e. with slash (/) as the directory separator. The max parameter specifies the maximum size of fn2. If convert > 0, the regular conversions are done; if convert < 0, minimal conversions are done (we skip uppercasing the letters, we allow more than one period, etc; this can be used when we know our partner is UNIX or similar).

#endif /* NZLTOR */

int
nzxpand(fn,flags) char *fn; int flags;

Replaces zxpand(), which is obsolete as of C-Kermit 7.0.
Call with:
  fn = Pointer to filename or pattern.
  flags = option bits:
    flags & ZX_FILONLY  Match regular files
    flags & ZX_DIRONLY  Match directories
    flags & ZX_RECURSE  Descend through directory tree
    flags & ZX_MATCHDOT Match "dot files"
    flags & ZX_NOBACKUP Don't match "backup files"
    flags & ZX_NOLINKS  Don't follow symlinks.

Returns the number of files that match fn, with data structures set up so the first file (if any) will be returned by the next znext() call. If ZX_FILONLY and ZX_DIRONLY are both set, or neither one is set, files and directories are matched. Notes:

1. It is essential that the number returned by nzxpand() reflect the actual number of filenames that will be returned by znext() calls. In other words:

     for (n = nzxpand(string,flags); n > 0; n--) {
         znext(buf);
         printf("%s\n", buf);
     }
   

   should print all the file names; no more, no less.

2. In UNIX, DOS, OS-9, etc, where directories contain entries for themselves (.) and the superior directory (..), these should NOT be included in the list under any circumstances, including when ZX_MATCHDOT is set.

3. Additional option bits might be added in the future, e.g. for sorting (sort by date/name/size, reverse/ascending, etc). Currently this is done only in higher level code (through a hack in which the nzxpand() exports its filename array, which is not portable because not all OS's can use this mechanism).

int
zmail(addr,fn) char *addr, fn;

Send the local, existing file fn as e-mail to the address addr. Returns:
  0: on success
  2: if mail delivered but temp file can't be deleted
 -2: if mail can't be delivered

int
zmkdir(path) char *path;

The path can be a file specification that might contain directory information, in which the filename is expected to be included, or an unambiguous directory specification (e.g. in UNIX it must end with "/"). This routine attempts to create any directories in the given path that don't already exist. Returns 0 or greater success: no directories needed creation, or else all directories that needed creation were created successfully; the return code is the number of directories that were created. Returns -1 on failure to create any of the needed directories.

int
zrmdir(path) char *path;

Attempts to remove the given directory. Returns 0 on success, -1 on failure. The detailed semantics are open -- should it fail if the directory contains any files or subdirectories, etc. It is probably best for this routine to behave in whatever manner is customary on the underlying platform; e.g. in UNIX, VMS, DOS, etc, where directories can not be removed unless they are empty.

VOID
znewn(fn,s) char *fn, **s;

Transforms the name fn into a filename that is guaranteed to be unique. If the file fn does not exist, then the new name is the same as fn; Otherwise, it's different. this function does its best, returns no value. New name is created in caller's space. Call like this: znewn(old,&new);. The second parameter is a pointer to the new name. This pointer is set by znewn() to point to a static string in its own space, so be sure to the result to a safe place before calling this function again.

int
znext(fn) char *fn;

Copies the next file name from a file list created by zxpand() into the string pointed to by fn (see zxpand). If no more files, then the null string is placed there. Returns 0 if there are no more filenames, with 0th element the array pointed to by fn set to NUL. If there is a filename, it is stored in the array pointed to by fn and a positive number is returned. NOTE: This is a change from earlier definitions of this function (pre-1999), which returned the number of files remaining; thus 0 was the return value when returning the final file. However, no mainline code ever depended on the return value, so this change should be safe.

int
zopeni(n,fn) int n; char *fn;

Opens the file named fn for input as file number n. Returns:
  0: on failure.
  1: on success.

int
zopeno(n,fn,zz,fcb) int n; char *name; struct zattr *zz; struct filinfo *fcb;

Attempts to open the named file for output as file number n. zz is a Kermit file attribute structure as defined in ckcdeb.h, containing various information about the file, including its size, creation date, and so forth. This function should attempt to honor as many of these as possible. fcb is a "file control block" in the traditional sense, defined in ckcdeb.h, containing information relevant to complicated file systems like VMS (RMS), IBM MVS, etc, like blocksize, record length, organization, record format, carriage control, etc. Returns:
  0: on failure.
  1: on success.

int
zoutdump()

Dumps a file output buffer. Used with the macro zmchout() defined in ckcker.h. Used only with file number ZOFILE, i.e. the file that is being received by Kermit during file transfer. Returns:
 -1: on failure.
  0: on success.

int
zprint(p,fn) char *p, *f;

Prints the file with name fn on a local printer, with options p. Returns:
  0: on success
  3: if file sent to printer but can't be deleted
 -3: if file can't be printed

int
zrename(fn,fn2) char *fn, *fn2;

Changes the name of file fn to fn2. If fn2 is the name of an existing directory, or a file-structured device, then file fn is moved to that directory or device, keeping its original name. If fn2 lacks a directory separator when passed to this function, an appropriate one is supplied. Returns:
 -1: on failure.
  0: on success.

int
zcopy(source,dest) char * source, * dest;

Copies the source file to the destination. One file only. No wildcards. The destination string may be a filename or a directory name. Returns:
  0: on success.
 <0: on failure:
  -2: source file is not a regular file.
  -3: source file not found.
  -4: permission denied.
  -5: source and destination are the same file.
  -6: i/o error.
  -1: other error.

char *
zlocaltime(char *)

Call with: "yyyymmdd hh:mm:ss" GMT/UTC date-time. Returns pointer to local date-time string "yyyymmdd hh:mm:ss" on success, NULL on failure.

VOID
zrtol(fn,fn2) char *fn, *fn2;

Remote-To-Local filename translation. OBSOLETE: replaced by nzrtol(). Translates a "standard" filename to a local filename. For example, in Unix this function might convert an all-uppercase name to lowercase, but leave lower- or mix-case names alone. Does its best, returns no value. New name is in string pointed to by fn2. No length checking is done.

#ifdef NZLTOR

int
nzrtol(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int convert,pathnames,max;

Replaces zrtol. Like zrtol but handles pathnames and checks length. See nzltor for detailed description of parameters.

#endif /* NZLTOR */

int
zsattr(xx) struct zattr *xx;

Fills in a Kermit file attribute structure for the file which is to be sent, namely the currently open ZIFILE. Note that this is not a very good design, but we're stuck with it. Callers must ensure that zsattr() is called only on real files, not on pipes, internally generated file-like objects such as server REMOTE command responses, etc. Returns:
 -1: on failure.
  0: on success with the structure filled in.
If any string member is null, it should be ignored by the caller.
If any numeric member is -1, it should be ignored by the caller.

int
zshcmd(s) char *s;

s contains to pointer to a command to be executed by the host computer's shell, command parser, or operating system. If the system allows the user to choose from a variety of command processors (shells), then this function should employ the user's preferred shell. If possible, the user's job (environment, process, etc) should be set up to catch keyboard interruption signals to allow the user to halt the system command and return to Kermit. The command must run in ordinary, unprivileged user mode. If possible, this function should return -1 on failure to start the command, or else it should return 1 if the command succeeded and 0 if it failed.

int
pexitstatus

zshcmd() and zsyscmd() should set this to the command's actual exit status code if possible.

int
zsyscmd(s) char *s;

s contains to pointer to a command to be executed by the host computer's shell, command parser, or operating system. If the system allows the user to choose from a variety of command processors (shells), then this function should employ the system standard shell (e.g. /bin/sh for Unix), so that the results will always be the same for everybody. If possible, the user's job (environment, process, etc) should be set up to catch keyboard interruption signals to allow the user to halt the system command and return to Kermit. The command must run in ordinary, unprivileged user mode. If possible, this function should return -1 on failure to start the command, or else it should return 1 if the command succeeded and 0 if it failed.

VOID
z_exec(s,args) char * s; char * args[];

This one executes the command s (which is searched for using the system's normal searching mechanism, such as PATH in UNIX), with the given argument vector, which follows the conventions of UNIX argv[]: the name of the command pointed to by element 0, the first arg by element 1, and so on. A null args[] pointer indicates the end of the arugment list. All open files must remain open so the exec'd process can use them. Returns only if unsuccessful.

int
zsinl(n,s,x) int n, x; char *s;

Reads a line from file number n. Writes the line into the address s provided by the caller. Writing terminates when newline is read, but with newline discarded. Writing also terminates upon EOF or if length x is exhausted. Returns:
 -1: on EOF or error.
  0: on success.

int
zsout(n,s) int n; char *s;

Writes the string s out to file number n. Returns:
 -1: on failure.
  0: on success.

int
zsoutl(n,s) int n; char *s;

Writes the string s out to file number n and adds a line (record) terminator (boundary) appropriate for the system and the file format. Returns:
 -1: on failure.
  0: on success.

int
zsoutx(n,s,x) int n, x; char *s;

Writes exactly x characters from string s to file number n. If s has fewer than x characters, then the entire string s is written. Returns:
 -1: on failure.
>= 0: on success, the number of characters actually written.

int
zstime(fn,yy,x) char *fn; struct zattr *yy; int x;

Sets the creation date (and other attributes) of an existing file, or compares a file's creation date with a given date. Call with:

fn:	pointer to name of existing file.
yy:	Pointer to a Kermit file attribute structure in which yy->date.val is a date of the form yyyymmdd hh:mm:ss, e.g. 19900208 13:00:00, which is to be used for setting or comparing the file date. Other attributes in the struct can also be set, such as the protection/permission (See Appendix I), when it makes sense (e.g. "yy->lprotect.val" can be set if the remote system ID matches the local one).
x:	A function code: 0 means to set the file's creation date as given. 1 means compare the date from the yy struct with the file's date.

Returns:
 -1: on any kind of error.
  0: if x is 0 and the file date was set successfully.
  0: if x is 1 and date from attribute structure > file creation date.
  1: if x is 1 and date from attribute structure <= file creation date.

VOID
zstrip(name,name2) char *name, **name2;

Strips pathname from filename "name". Constructs the resulting string in a static buffer in its own space and returns a pointer to it in name2. Also strips device name, file version numbers, and other "non-name" material.

int
zxcmd(n,s) char *s;

Runs a system command so its output can be accessed as if it were file n. The command is run in ordinary, unprivileged user mode.
If n is ZSTDIO or ZCTERM, returns -1.
If n is ZIFILE or ZRFILE, then Kermit reads from the command, otherwise Kermit writes to the command.
Returns 0 on error, 1 on success.

int
zxpand(fn) char *fn;

OBSOLETE: Replaced by nzxpand(), q.v.

#ifdef ZXREWIND

int
zxrewind()

Returns the number of files returned by the most recent nzxpand() call, and resets the list to the beginning so the next znext() call returns the first file. Returns -1 if zxpand has not yet been called. If this function is available, ZXREWIND should be defined; otherwise it should not be referenced.

#endif /* ZXREWIND */

int
xsystem(cmd) char *cmd;

Executes the system command without redirecting any of its i/o, similar (well, identical) to system() in Unix. But before passing the command to the system, xsystem() ensures that all privileges are turned off, so that the system command executes in ordinary unprivileged user mode. If possible, xsystem() returns the return code of the command that was executed.

  NET_SX25 is the network-type ID for SunLink X.25.
  NET_VX25 is the network-type ID for VOS X.25.

#define NET_HX25 11			/* Hewlett-Packard X.25 */
#define NET_IX25 12			/* IBM X.25 */

  -DIBMX25  (for IBM)
  -DHPX25   (for HP)

#ifdef IBMX25
#define ANYX25
#endif /* IBMX25 */

#ifdef HPX25
#define ANYX25
#endif /* HPX25 */

#ifndef HPORIBMX25
#ifdef HPX25
#define HPORIBMX25
#else
#ifdef IBMX25
#define HPORIBMX25
#endif /* IBMX25 */
#endif /* HPX25 */
#endif /* HPORIBMX25 */

  r-01-00-^A/!FWERMIT.EXE'"
  s-01-00-^AE!Y/amd/watsun/w/fdc/new/wermit.exe.DV
  r-02-01-^A]"A."D7""B8#119980101 18:14:05!#8531&872960,$A20B-!7(#512@ #.Y
  s-02-01-^A%"Y.5!

  RE=0101, RED=1101, RWED=1111, E=0010

  RE=1010, RED=0010, RWED=0000, E=1101

  1010001000001101

  A20B