Frank da Cruz
The Kermit Project
Columbia University
As of C-Kermit version:
8.0.209 17 March 2003
This file last updated:
Sun Mar 23 19:33:46 2003
(New York City 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/ckuins.html
OVERVIEW
WARNING: This document contains notes that have been accumulating since the early 1980s. Many of the products and Unix versions mentioned here have not been heard of in a long while, but that does not necessarily mean they are not still running in some obscure nook.
This file contains Unix-specific information. A lot of it. Unlike most other packages, C-Kermit tries very hard to be portable to every Unix variety (and every release of each one) known to exist, including many that are quite old, as well as to other platforms like VMS, AOS/VS, VOS, OS-9, the BeBox, the Amiga, etc.
Since C-Kermit gets so deeply into the file system, i/o system, and other areas that differ radically from one Unix platform to the next, this means that a lot can go wrong when you try to install C-Kermit on (for example) a new release of a particular variety of Unix, in which certain things might have changed that C-Kermit depended upon.
This file concentrates on installation. For a description of general configuration options for C-Kermit, please read the Configurations Options document. For troubleshooting after installation, see the General Hints and Tips and Unix-Specific Hints and Tips documents. The latter, in particular, contains lots of information on lots of specific Unix platforms. If you want to work on the source code, see the C-Kermit Program Logic Manual
You may install C-Kermit:
If your Unix computer is on the Internet and it has a C compiler, here's how to download, build, and install C-Kermit directly from the "tarballs" or Zip archives:
For secure installations, see Sections 5 and 16.
Various Unix varieties -- Linux, Solaris, AIX, etc -- now incorporate the idea of "install packages", and many users expect to find all new applications in this format. A selection of install packages might be available for any given release of C-Kermit, but there is a tradeoff between convenience and safety. Unix presents several notable problems to the builder of install packages:
Item (b) is discussed at length in Sections 10 and 11 of this document, but the package-related aspects are also given here. The basic problem is that Unix dialout devices and the UUCP "lock files" that regulate contention for them (described in Section 10) are usually protected against "world". Therefore, the install procedure must either run as root in order to give the Kermit binary the required permissions, group, and/or owner, or else the dialout devices and associated directories must be open for group or world reading and writing. Otherwise, the Kermit program just installed WILL NOT WORK for dialing out.
Thus, a well-crafted installation procedure should present the options and allow the installer to choose the method, if any, for regulating access to the dialout devices:
It should go without saying, of course, that any binaries that are to be included in an install package should be built fresh on the exact platform (e.g. Red Hat 8.0 on Intel) for which the package is targeted; prebuilt binaries (next section) from other sites are likely to have library mismatches. CLICK HERE for more about building C-Kermit install packages.
The Kermit Project does not have the resources or the expertise to make install packages for every platform. Most install packages, therefore, are contributed by others, and they do not necessarily follow the guidelines given above. Pay attention to what they do.
If you are an end user who has obtained a C-Kermit install package for a particular platform, you should be aware that some additional steps might needed if you want to use Kermit to dial out. Read Section 10 for details.
Hundreds of prebuilt C-Kermit binaries are available on the CDROM in the BINARY tree [NOTE: The C-Kermit CDROM is still for version 7.0], and at our ftp site in the kermit/bin area (with names starting with "ck"), also accessible on the C-Kermit website. To install a prebuilt binary:
But first... Please heed the following cautions:
Therefore, it is better to build your own binary from source code (next section) if you can. But since it is increasingly for Unix systems (not to mention VMS and other OS's) to be delivered without C compilers, it is often impractical. In such cases, try the most appropriate prebuilt binary or binaries, and if none of them work, contact us and we'll see what we can do to help.
Also see: Section 8 and Section 9.
C-Kermit is designed to be built and used on as many platforms as possible: Unix and non-Unix, old and new (and ancient), ANSI C and K&R. The Unix version does not use or depend on any external tools for building except the "make" utility, the C compiler, and the linker. It does not use any automated configuration tools such as configure, autoconf, automake, libtool, etc. Everything in C-Kermit has been built by hand based on direct experience or reports or contributions from users of each platform.
The C-Kermit makefile contains the rules for building the program for each of the hundreds of different kinds of Unix systems that C-Kermit attempts to support. It covers all Unix variations since about 1980 -- pretty much everything after Unix V6. Separate makefiles are used for Plan 9 and 2.x BSD.
Prerequisites:
Plus:
mount redhat cdrom goto RedHat/RPMS rpm -ivh ncurses-devel*.rpm or to have the exact name ls ncurse* and load as rpm -ivh filename then leave the cdrom and unmount it.
bos.adt.base bos.adt.include bos.adt.lib bos.adt.libm bos.adt.utils
from the first installation CD.
The makefile might need to be renamed from ckuker.mak to makefile. Directions:
NOTE: steps (c) through (e) can be accomplished using the makefile 'install' target as described in Section 5.4.
cd directory-where-kermit-binary-is ln -s kermit telnet
If you want C-Kermit to be the default Telnet client, make sure the directory in which you created the symlink is in the PATH ahead of the where the regular Telnet client is.
Also see: C-Kermit Configuration Options
SECTION CONTENTS
4.1. The Unix Makefile 4.2. The C-Kermit Initialization File 4.3. The 2.x BSD Makefile 4.4. The Plan 9 Makefile 4.5. Makefile Failures
(Also see the Configurations Options document, Section 8).
Lots of new features have been added in versions 7.0 and 8.0 that require access to new symbols, APIs, libraries, etc, and this will no doubt cause problems in compiling, linking, or execution on platforms where 6.0 and earlier built without incident. This section contains what we know as of the date of this file.
The first category concerns the new Kermit Service Daemon (IKSD; see the IKSD Administrator's Guide for details):
These days most Unix systems take advantage of shadow password files or Plugable Authentication Modules (PAM). If your system uses shadow passwords you must add -DCK_SHADOW to the CFLAGS list. If your system requires PAM you must add -DCK_PAM to the CFLAGS and -lpam -ldl to LIBS.
If you encounter difficulties with any of the above, and you are not interested in running C-Kermit as an IKSD, then simply add NOIKSD to CFLAGS and rebuild. Example:
make sco286 (get lots of errors) make clean make sco286 "KFLAGS=-DNOIKSD"
Some non-IKSD things to watch out for:
make xxx "KFLAGS=-DMAINTYPE=blah
(where blah is int, long, or whatever). If the complaint is "Attempt to return a value from a function of type void" then add -DMAINISVOID:
make xxx "KFLAGS=-DMAINISVOID=blah
"ckutio.c", line 11994: incomplete struct/union/enum tm: _tm "ckutio.c", line 11995: error: cannot dereference non-pointer type "ckutio.c", line 11995: error: assignment type mismatch "ckutio.c", line 11997: warning: using out of scope declaration: localtime "ckutio.c", line 11997: error: unknown operand size: op "=" "ckutio.c", line 11997: error: assignment type mismatch "ckutio.c", line 11998: error: undefined struct/union member: tm_year "ckutio.c", line 12000: error: undefined struct/union member: tm_mon "ckutio.c", line 12001: error: undefined struct/union member: tm_mday "ckutio.c", line 12002: error: undefined struct/union member: tm_hour "ckutio.c", line 12003: error: undefined struct/union member: tm_min "ckutio.c", line 12004: error: undefined struct/union member: tm_sec
are due to failure to include the appropriate time.h header files. Unix platforms generally have one or more of the following: <time.h>, <sys/time.h>, and <sys/timeb.h>. Any combination of these might be required. Defaults are set up for each makefile target. The defaults can be corrected on the CC command line by adding the appropriate definition from the following list to CFLAGS:
-DTIMEH Include <time.h> -DNOTIMEH Don't include <time.h> -DSYSTIMEH Include <sys/time.h> -DNOSYSTIMEH Don't include <sys/time.h> -DSYSTIMEBH Include <sys/timeb.h> -DNOSYSTIMEBH Don't include <sys/timeb.h>
Note that <sys/timeb.h> is relatively scarce in the System V and POSIX environments; the only platform of recent vintage where it was/is used is OSF/1 and its derivatives (Digital Unix and Tru64 Unix).
-DTPUTSARGTYPE=char -DTPUTSFNTYPE=int -DTPUTSARGTYPE=int -DTPUTSFNTYPE=void
Until the warnings go away, except maybe "ck_outc: return with a value in a function returning void", and in that case also add -DTPUTSISVOID.
Other difficulties are generally of the "where is curses.h and what is it called this week?" variety (most easily solved by making symlinks in the include and lib directories), or overzealous complaints regarding type mismatches in function calls because of the totally needless and silly signed versus unsigned char conflict (*), etc. In any case, please send any compilation or linking warnings or errors to the author, preferably along with fixes.
IMPORTANT: If you find any of these hints necessary for a particular make target (or you hit upon others not listed here), PLEASE SEND A REPORT TO:
kermit-support@columbia.edu
If your distribution does not contain a file with the name "makefile" or "Makefile", then rename the file called ckuker.mak to makefile:
mv ckuker.mak makefile
Then type "make xxx", where xxx is the platform you want to build C-Kermit for. These are listed in the comments at the top of the makefile. For example, to build C-Kermit for Linux, type:
make linux
Here are some typical examples:
Target Description linux Linux, any version on any hardware platform openbsd OpenBSD, any version on any hardware platform aix43 AIX 4.3 aix43g AIX 4.3, built with gcc solaris9 Solaris 9 solaris9g Solaris 9 built with gcc hpux1100 HP-UX 11-point-anything
The makefile is quite long, and at least two versions of Unix, SCO Xenix/286 and 2.x BSD, cannot cope with its length. An attempt to "make sco286" gives the message "Make: Cannot alloc mem for env.. Stop". Solution: edit away some or all of the nonrelevant material from the makefile. (A separate version of the makefile is provided for BSD 2.x: ckubs2.mak but C-Kermit 8.0 can't be built for BSD 2.x -- it has simply grown too large.)
Some make programs reportedly cannot handle continued lines (lines ending in backslash (\)). If you have a problem with the makefile, try editing the makefile to join the continued lines (remove the backslashes and the following linefeed).
Other makefile troubles may occur because tabs in the makefile have somehow been converted to spaces. Spaces and tabs are distinct in Unix makefiles.
Similarly, carriage returns might have been added to the end of each line, which also proves confusing to most Unix versions of make.
Check to see if there are comments about your particular version in its makefile target itself. In a text editor such as EMACS or VI, search for the make entry name followed by a colon, e.g. "linux:" (if you really are building C-Kermit for Linux, do this now).
Check to see if there are comments about your particular version in the ckubwr.txt file (CLICK HERE for the Web version).
If you have trouble with building ckwart.c, or running the resulting wart preprocessor program on ckcpro.w:
wart: ckwart.$(EXT)
$(CC) -static -o wart ckwart.$(EXT) $(LIBS)
If your compiler supports a compile-time option to treat ALL chars (and char *'s, etc) as unsigned, by all means use it -- and send me email to let me know what it is (I already know about gcc -funsigned-char).
To add compilation options (which are explained later in this document) to your makefile target without editing the makefile, include "KFLAGS=..." on the make command line, for example:
make linux KFLAGS=-DNODEBUG make bsd "KFLAGS=-DKANJI -DNODEBUG -DNOTLOG -DDYNAMIC -UTCPSOCKET"
Multiple options must be separated by spaces. Quotes are necessary if the KFLAGS= clause includes spaces. The KFLAGS are added to the end of the CFLAGS that are defined in the selected makefile target. For example, the "bsd" entry includes -DBSD4 -DTCPSOCKET, so the second example above compiles Kermit with the following options:
-DBSD4 -DTCPSOCKET -DKANJI -DNODEBUG -DNOTLOG -DDYNAMIC -UTCPSOCKET
(Notice how "-UTCPSOCKET" is used to negate the effect of the "-DTCPSOCKET" option that is included in the makefile target.)
WARNING: Be careful with KFLAGS. If you build C-Kermit, change some files, and then run make again using the same make entry but specifying different KFLAGS than last time, make won't detect it and you could easily wind up with inconsistent object modules, e.g. some of them built with a certain option, others not. When in doubt, "make clean" first to make sure all your object files are consistent. Similarly, if you change CFLAGS, LIBS, or any other items in the makefile, or you rebuild using a different makefile target, "make clean" first.
If you create a new makefile target, use static linking if possible. Even though this makes your C-Kermit binary bigger, the resulting binary will be more portable. Dynamically linked binaries tend to run only on the exact configuration and version where they were built; on others, invocation tends to fail with a message like:
Can't find shared library "libc.so.2.1"
(This section is obsolete.) Read Section 5 about the initialization file.
This section is obsolete. C-Kermit 6.0 was the last release that could be built on PDP-11 based BSD versions.
Use the separate makefile ckpker.mk. NOTE: The Plan 9 version of C-Kermit 8.0 has not yet been built. There should be no impediment to building it. However, even when built successfully, certain key features are missing, notably TCP/IP networking.
First, be sure the source files are stored on your current disk and directory with the right names (in lowercase). Second, make sure that the makefile itself does not contain any lines with leading spaces: indented lines must all start with horizontal TAB, and no spaces.
Then make sure that your Unix PATH is defined to find the appropriate compiler for your makefile target. For example, on SunOS systems, "make sunos41" builds C-Kermit for the BSD environment, and assumes that /usr/ucb/cc will be used for compilation and linking. If your PATH has /usr/5bin ahead of /usr/ucb, you can have problems at compile or link time (a commonly reported symptom is the inability to find "ftime" during linking). Fix such problems by redefining your Unix PATH, or by specifying the appropriate "cc" in CC= and CC2= statements in your makefile target.
During edits 166-167, considerable effort went into making C-Kermit compilable by ANSI C compilers. This includes prototyping all of C-Kermit's functions, and including the ANSI-defined system header files for system and library functions, as defined in K&R, second edition: <string.h>, <stdlib.h>, <unistd.h> (except in NeXTSTEP this is <libc.h>), and <sys/stdtypes.h>. If you get warnings about any of these header files not being found, or about argument mismatches involving pid_t, uid_t, or gid_t, look in ckcdeb.h and make amendments. C-Kermit assumes it is being compiled by an ANSI-compliant C compiler if __STDC__ is defined, normally defined by the compiler itself. You can force ANSI compilation without defining __STDC__ (which some compilers won't let you define) by including -DCK_ANSIC on the cc command line.
On the other hand, if your compiler defines __STDC__ but still complains about the syntax of Kermit's function prototypes, you can disable the ANSI-style function prototyping by including -DNOANSI on the command line.
For SCO OpenServer, UNIX, ODT, and XENIX compilations, be sure to pick the most appropriate makefile target, and be sure you have installed an SCO development system that is keyed to your exact SCO operating system release, down to the minor version (like 2.3.1).
Also note that SCO distributes some of its libraries in encrypted form, and they must be decrypted before C-Kermit can be linked with them. If not, you might see a message like:
ld: file /usr/lib/libsocket.a is of unknown type: magic number = 6365
To decrypt, you must supply a key (password) that came with your license. Call SCO for further info.
If your compiler uses something other than int for the pid (process id) data type, put -DPID_T=pid_t or whatever in your CFLAGS.
If you get complaints about unknown data types uid_t and gid_t, put -DUID_T=xxx -DGID_T=yyy in your CFLAGS, where xxx and yyy are the appropriate types.
If your compilation fails because of conflicting or duplicate declarations for sys_errlist, add -DUSE_STRERROR or -DNDSYSERRLIST to CFLAGS.
If your compilation dies because getpwnam() is being redeclared (or because of "conflicting types for getwpnam"), add -DNDGPWNAM to your CFLAGS. If that doesn't work, then add -DDCGPWNAM to your CFLAGS (see ckufio.c around line 440).
If the compiler complains about the declaration of getpwnam() during an ANSI C compilation, remove the declaration from ckufio.c or change the argument in the prototype from (char *) to (const char *).
If you get complaints that getpwuid() is being called with an improper type, put -DPWID_T=xx in your CFLAGS.
If you get compile-time warnings that t_brkc or t_eofc (tchars structure members, used in BSD-based versions) are undefined, or structure-member- related warnings that might be traced to this fact, add -DNOBRKC to CFLAGS.
If you get a linker message to the effect that _setreuid or _setregid is not defined, add -DNOSETREU to CFLAGS, or add -DCKTYP_H=blah to CFLAGS to make C-Kermit read the right <types.h>-kind-of-file to pick up these definitions.
If you get a message that _popen is undefined, add -DNOPOPEN to CFLAGS.
If you get a complaint at compile time about an illegal pointer-integer combination in ckufio.c involving popen(), or at link time that _popen is an undefined symbol, add the declaration "FILE *popen();" to the function zxcmd() in ckufio.c (this declaration is supposed to be in <stdio.h>). If making this change does not help, then apparently your Unix does not have the popen() function, so you should add -DNOPOPEN to your make entry, in which case certain functions involving "file" i/o to the standard input and output of subprocesses will not be available.
If your linker complains that _getcwd is undefined, you can add a getcwd() function to ckufio.c, or add it to your libc.a library using ar:
#include <stdio.h>
char *
getcwd(buf,size) char *buf; int size; {
#ifndef NOPOPEN
#ifdef DCLPOPEN
FILE *popen();
#endif
FILE *pfp;
if (!buf) return(NULL);
if (!(pfp = popen("pwd","r"))) return(NULL);
fgets(buf,size-2,pfp);
pclose(pfp);
buf[strlen(buf)-1] = '\0';
return((char *)buf);
#else
buf[0] = '\0';
return(NULL);
#endif /* NOPOPEN */
}
#ifdef NOPOPEN
FILE *popen(s,t) char *s,*t; {
return(NULL);
}
#endif /* NOPOPEN */
If you get complaints about NPROC having an invalid value, add a valid definition for it (depends on your system), as in the cray entry.
If you get some symbol that's multiply defined, it probably means that a variable name used by Kermit is also used in one of your system libraries that Kermit is linked with. For example, under PC/IX some library has a variable or function called "data", and the variable "data" is also used extensively by Kermit. Rather than edit the Kermit source files, just put a -D in the make entry CFLAGS to change the Kermit symbol at compile time. In this example, it might be -Ddata=xdata.
Some symbol is defined in your system's header files, but it produces conflicts with, or undesired results from, Kermit. Try undefining the symbol in the makefile target's CFLAGS, for example -UFIONREAD.
Some well-known symbol is missing from your system header files. Try defining in the makefile target's CFLAGS, for example -DFREAD=1.
You get many warnings about pointer mismatches. This probably means that Kermit is assuming an int type for signal() when it should be void, or vice-versa. Try adding -DSIG_I (for integer signal()) or -DSIG_V (for void) to CFLAGS. Or just include KFLAGS=-DSIG_V (or whatever) in your "make" command, for example:
make bsd KFLAGS=-DSIG_V
You get many messages about variables that are declared and/or set but never used. It is difficult to avoid these because of all the conditional compilation in the program. Ignore these messages.
Some of C-Kermit's modules are so large, or contain so many character string constants, or are so offensive in some other way, that some C compilers give up and refuse to compile them. This is usually because the -O (optimize) option is included in the make entry. If this happens to you, you can (a) remove the -O option from the make entry, which will turn off the optimizer for ALL modules; or (b) compile the offending module(s) by hand, including all the switches from make entry except for -O, and then give the appropriate "make" command again; or (c) increase the value of the -Olimit option, if your compiler supports this option; or (d) change the makefile target to first compile each offending module explicitly without optimization, then compile the others normally (with optimization), for example:
#Fortune 32:16, For:Pro 2.1 (mostly like 4.1bsd) ft21: @echo 'Making C-Kermit $(CKVER) for Fortune 32:16 For:Pro 2.1...' $(MAKE) ckuusx.$(EXT) "CFLAGS= -DNODEBUG -DBSD4 -DFT21 -DNOFILEH \ -SYM 800 \ -DDYNAMIC -DNOSETBUF -DCK_CURSES $(KFLAGS) -DPID_T=short" $(MAKE) ckuxla.$(EXT) "CFLAGS= -DNODEBUG -DBSD4 -DFT21 -DNOFILEH \ -SYM 800 \ -DDYNAMIC -DNOSETBUF -DCK_CURSES $(KFLAGS) -DPID_T=short" $(MAKE) ckudia.$(EXT) "CFLAGS= -DNODEBUG -DBSD4 -DFT21 -DNOFILEH \ -SYM 800 \ -DDYNAMIC -DNOSETBUF -DCK_CURSES $(KFLAGS) -DPID_T=short" $(MAKE) wermit "CFLAGS= -O -DNODEBUG -DBSD4 -DFT21 -DNOFILEH -SYM 800 \ -DDYNAMIC -DNOSETBUF -DCK_CURSES $(KFLAGS) -DPID_T=short" \ "LNKFLAGS= -n -s" "LIBS= -lcurses -ltermcap -lv -lnet"
As an extreme example, some compilers (e.g. gcc on the DG AViiON) have been known to dump core when trying to compile ckwart.c with optimization. So just do this one "by hand":
cc -o wart ckwart.c
or:
touch ckcpro.c
and then give the "make" command again.
Speaking of wart, it is unavoidable that some picky compilers might generate "statement unreachable" messages when compiling ckcpro.c. Unreachable statements can be generated by the wart program, which generates ckcpro.c automatically from ckcpro.w, which translates lex-like state/input constructions into a big switch/case construction.
Some function in Kermit wreaks havoc when it is called. Change all invocations of the function into a macro that evaluates to the appropriate return code that would have been returned by the function had it been called and failed, for example: -Dzkself()=0. Obviously not a good idea if the function is really needed.
If you have just installed SunOS 4.1.2 or 4.1.3, you might find that C-Kermit (and any other C program) fails to link because of unresolved references from within libc. This is because of a mistake in Sun's /usr/lib/shlib.etc files for building the new libc. Change the libc Makefile so that the "ld" lines have "-ldl" at the end. Change the README file to say "mv xccs.multibyte. xccs.multibyte.o" and follow that instruction.
SECTION CONTENTS
5.1. The C-Kermit Initialization File 5.2. Text Files 5.3. Installing the Kermit Files 5.4. The Makefile Install Target
The C-Kermit executable does not need any external files to run. Unlike, say, the cu program, which on most platforms is useless unless you (as root) edit the /usr/spool/uucp/Systems and /usr/spool/uucp/Devices files to supply whatever obscure and undocumented syntax is required to match some supposedly user-friendly mnemonic to the real pathname of whatever device you want to use, Kermit runs on its own without needing any external configuration files, and lets you refer to device (and network hosts and services) by their own natural undisguised names.
Nevertheless, a number of external files can be installed along with the C-Kermit executable if you wish. These include configuration and customization files that are read by Kermit as well as documentation files to be read by people. All of this material is (a) optional, and (b) available on the Kermit website:
http://www.columbia.edu/kermit/
and usually in a more pleasant form, perhaps also with updated content. So if your computer is on the Internet, there is no need to install anything but the Kermit executable if users know how to find the Kermit website (and if they don't, Kermit's "help" command tells them).
The standard initialization file is quite long (more than 600 lines) and requires noticeable processing time (the slower the computer, the more noticeable), yet few people actually use the services directory, whose definition takes up most of its bulk. Meanwhile, in C-Kermit 8.0, many of the remaining functions of the standard initialization file are now built in; for example, the FAST, CAUTIOUS, and ROBUST commands.
More to the point, many of the settings that could be made only in the initialization and customization files can now be picked up from environment variables. The first group identifies initialization and directory files:
The next group is related to dialing modems:
The final group includes well-known environment variables that are also used by Kermit:
Does this mean the initialization file can be abolished? I think so. Here's why:
In fact, you can put any number of kerbang scripts in your PATH to start up C-Kermit in different ways, to have it adopt certain settings, make particular connections, execute complicated scripts, whatever you want.
If your computer already has an older version of C-Kermit installed, you should rename it (e.g. to "kermit6" or "kermit7") so in case you have any trouble with the new version, the old one is still available.
In most cases, you need to be root to install C-Kermit, if only to gain write access to directories in which the binary and manual page are to be copied. The C-Kermit binary should be installed in a directory that is in the users' PATH, but that is not likely to be overwritten when you install a new version of the operating system. A good candidate would be the /usr/local/bin/ directory, but the specific choice is site dependent. Example (assuming the appropriate Kermit binary is stored in your current directory as "wermit", e.g. because you just built it from source and that's the name the makefile gave it):
mv wermit /usr/local/bin/kermit chmod 755 /usr/local/bin/kermit
or (only after you finish reading this section!) simply:
make install
IMPORTANT: IF C-KERMIT IS TO BE USED FOR DIALING OUT, you must also do something to give it access to the dialout devices and lockfile directories. The 'install' target does not attempt to set Kermit's owner, group, and permissions to allow dialing out. This requires privileges, open eyes, and human decision-making. Please read Sections 10 and 11 below, make the necessary decisions, and then implement them by hand as described in those sections.
You should also install the man page, which is called ckuker.nr, in the man page directory for local commands, such as /usr/man/man1/, renamed appropriately, e.g. to kermit.1. This is also taken care of by "make install".
Optionally, the text files listed in the previous section can be placed in a publicly readable directory. Suggested directory names are:
/usr/local/doc/kermit/ /usr/local/lib/kermit/ /usr/share/lib/kermit/ /opt/kermit/doc/
(or any of these without the "/kermit"). Upon startup, C-Kermit checks the following environment variables whose purpose is to specify the directory where the C-Kermit text files are, in the following order:
K_INFO_DIRECTORY K_INFO_DIR
If either of these is defined, C-Kermit checks for the existence of the ckubwr.txt file (Unix C-Kermit Hints and Tips). If not found, it checks the directories listed above (both with and without the "/kermit") plus several others to see if they contain the ckubwr.txt file. If found, various C-Kermit messages can refer the user to this directory.
Finally, if you want to put the source code files somewhere for people to look at, you can do that too.
Here are the parameters you need to know:
This section is obsolete. We don't distribute C-Kermit on diskettes any more because (a)there is no demand, and (b) it no longer fits.If you received a DOS-format diskette containing a binary executable C-Kermit program plus supporting text files, be sure to chmod +x the executable before attempting to run it.
In version 5A(190) and later, all the text files on the C-Kermit DOS-format diskettes are in Unix format: LF at the end of each line rather than CRLF. This means that no conversions are necessary when copying to your Unix file system, and that all the files on the diskette, text and binary, can be copied together. The following comments apply to the DOS-format diskettes furnished with version 5A(189) and earlier or to other DOS-format diskettes you might have obtained from other sources.
If you have received C-Kermit on MS-DOS format diskettes (such as those distributed by Columbia University), you should make sure that your DOS-to-Unix conversion utility (such as "dosread") both: (1) changes line terminators in all files from carriage-return linefeed (CRLF) to just linefeed (LF) (such as "dosread -a") and remove any Ctrl-Z's, and (2) that all filenames are converted from uppercase to lowercase. If these conversions were not done, you can use the following shell script on your Unix system to do them:
---(cut here)--- #!/bin/sh # # Shell script to convert C-Kermit DOS-format files into Unix format. # Lowercases the filenames, strips out carriage returns and Ctrl-Z's. # x=$1 # the name of the source directory y=$2 # the name of the target directory if [ $# -lt 2 ]; then echo "usage: $0 source-directory target-directory" exit 1 fi if cd $1 ; then echo "Converting files from $1 to $2" else echo "$0: cannot cd to $1" exit 1 fi for i in *; do j=`echo $i | tr 'A-Z' 'a-z'` echo $x/$i =\> $y/$j tr -d '\015\032' < $i > $y/$j done ---(cut here)---
Cut out this shell script, save it as "convert.sh" (or any other name you prefer), then "chmod +x convert.sh". Then, create a new, empty directory to put the converted files in, and then "convert.sh /xxx /yyy" where /xxx is the name of the directory where the PC-format files are, and /yyy is the name of the new, empty directory. The converted files will appear in the new directory.
First some quick checks for problems that can be easily corrected by recompiling with different options:
Here is a more thorough checklist can use to tell whether your version of C-Kermit was built correctly for your Unix system, with hints on how to fix or work around problems:
$ touch thisisafilewithaveryveryveryveryveryveryveryverylooooooooongname
(you might need to make it longer than this, perhaps as long as 257 or even 1025 characters).
Check with ls to see if your version of Unix truncated the name. Now start C-Kermit and type "send thisis<ESC>". Does Kermit complete the name, showing the same name as ls did? If not, wrong filesystem. Read on.
send foo dir1/dir2/dir3/foo
Check to make sure that dir1/dir2/dir3/foo was created in Computer A's current directory (i.e. that three levels of directories were created).
(And please send back any added code, so that others can benefit from it and it can be carried forward into future releases.)
Also see: C-Kermit Configuration Options
SECTION CONTENTS
9.1 Standards
9.1.1. POSIX
9.1.2. ANSI C
9.1.3. Other Standards
9.2. Library Issues
9.3. Unix File System Peculiarities
9.4. Hardware Flow Control
9.5. Terminal Speeds
9.6. Millisecond Sleeps
9.7. Nondestructive Input Buffer Peeking
9.8. Other System-Dependent Features
9.9. Terminal Interruption
There are several major varieties of Unix: Bell Laboratories Seventh Edition, AT&T System V, Berkeley Standard Distribution (BSD), and POSIX. Each has many, many subvarieties and descendents, and there are also hybrids that exhibit symptoms of two or more varieties, plus special quirks of their own.
Seventh edition versions of C-Kermit include the compile-time option -DV7 in the CFLAGS string in the makefile target. Various V7-based implementations are also supported: -DCOHERENT, -DMINIX, etc.
AT&T-based versions of Unix Kermit include the compile-time option -DATTSV (standing for AT∓T Unix System V). This applies to System III and to System V up to and including Release 2. For System V Release 3, the flag -DSVR3 should be used instead (which also implies -DATTSV). This is because the data type of signal() and several other functions was changed between SVR2 and SVR3. For System V Release 4, include -DSVR4 because of changes in UUCP lockfile conventions; this also implies -DSVR3 and -DATTSV.
For BSD, the flag -BSDxx must be included, where xx is the BSD version number, for example BSD4 (for version 4.2 or later, using only 4.2 features), -DBSD41 (for BSD 4.1 only), -DBSD43 (for 4.3), -DBSD29 (BSD 2.9 for DEC PDP-11s). -DBSD44 is for 4.4BSD, which is the basis of FreeBSD, NetBSD, OpenBSD, BSDI, and Mac OS X, and which contains many POSIX features, and has little relation to 4.3BSD and earlier.
For POSIX, include the flag -DPOSIX. POSIX defines a whole new set of terminal i/o functions that are not found in traditional AT&T or Berkeley implementations, and also defines the symbol _POSIX_SOURCE, which is used in many system and library header files, mainly to disable non-POSIX (i.e. useful) features.
Note (circa 1997): In order to enable serial speeds higher than 38400 bps, it is generally necessary to add -DPOSIX (among other things), since the older terminal APIs can not accommodate the new speeds -- out o' bits. But this often also means wholesale conversion to POSIX APIs. In general, just try adding -DPOSIX and then see what goes wrong. Be wary of features disappearing: when _POSIX_SOURCE is defined, all sorts of things that were perfectly OK before suddenly become politically incorrect -- like reading modem signals, doing hardware flow control, etc. POSIX was evidently not designed with serial communication in mind!
Case in point: In UnixWare 7.0, #define'ing POSIX causes strictness clauses in the header files to take effect. These prevent <sys/time.h> from defining the timeval and timezone structs, which are needed for all sorts of things (like select()). Thus, if we want the high serial speeds, we have to circumvent the POSIX clauses.
Similarly in SCO OpenServer R5.0.4 where, again, we must use the POSIX APIs to get at serial speeds higher than 38400, but then doing so removes hardware flow control -- just when we need it most! In cases like this, dirty tricks are the only recourse (search for SCO_OSR504 in ckutio.c for examples).
For reasons like this, Unix implementations tend to be neither pure AT&T nor pure BSD nor pure POSIX, but a mixture of two or more of these, with "compatibility features" allowing different varieties of programs to be built on the same computer. In general, Kermit tries not to mix and match but to keep a consistent repertoire throughout. However, there are certain Unix implementations that only work when you mix and match. For example, the Silicon Graphics IRIX operating system (prior to version 3.3) is an AT&T Unix but with a BSD file system. The only way you can build Kermit successfully for this configuration is to include -DSVR3 plus the special option -DLONGFN, meaning "pretend I was built with -DBSDxx when it's time to compile file-related code". See the "iris" makefile target.
SUBSECTION CONTENTS
9.1.1. POSIX 9.1.2. ANSI C 9.1.3. Other Standards
In edits 166-167 (1988-89), C-Kermit was heavily modified to try to keep abreast of new standards while still remaining compatible with old versions of C and Unix. There are two new standards of interest: ANSI C (as described in Kernighan and Ritchie, "The C Programming Language", Second Edition, Prentice Hall, 1988) and POSIX.1 (IEEE Standard 1003.1 and ISO/IEC 9945-1, 1990, "Portable Operating System Interface"). These two standards have nothing to do with each other: you can build C-Kermit with a non-ANSI compiler for a POSIX system, or for a non-POSIX system with with an ANSI compiler.
Computer systems that claim some degree of POSIX compliance have made some attempt to put their header files in the right places and give them the right names, and to provide system library functions with the right names and calling conventions. Within the header files, POSIX-compliant functions are supposed to be within #ifdef _POSIX_SOURCE..#endif conditionals, and non-POSIX items are not within these conditionals.
If Kermit is built with neither -D_POSIX_SOURCE nor -DPOSIX, the functions and header files of the selected version of Unix (or VMS, etc) are used according to the CFLAGS Kermit was built with.
If Kermit is built with -D_POSIX_SOURCE but not -DPOSIX, then one of the -DBSD or -DATTSV flags (or one that implies them) must also be defined, but it still uses only the POSIX features in the system header files. This allows C-Kermit to be built on BSD or AT&T systems that have some degree of POSIX compliance, but still use BSD or AT&T specific features.
The dilimma is this: it is often necessary to define _POSIX_SOURCE to get at new or modern features, such as high serial speeds and the APIs to deal with them. But defining _POSIX_SOURCE also hides other APIs that Kermit needs, for example the ones dealing with modem signals (others are listed just below). Thus all sorts of hideous contortions are often required to get a full set of features.
The POSIX standard does not define anything about uucp lockfiles. "make posix" uses NO (repeat, NO) lockfile conventions. If your POSIX-compliant Unix version uses a lockfile convention such as HDBUUCP (see below), use the "posix" entry, but include the appropriate lockfile option in your KFLAGS on the "make" command line, for example:
make posix "KFLAGS=-DHDBUUCP"
POSIX.1 also lacks certain other features that Kermit needs. For example:
So at this point, there cannot be one single fully functional POSIX form of C-Kermit unless it also has "extensions", as do Linux, QNX, etc.
More on POSIX (quoting from a newsgroup posting by Dave Butenhof):
Standards tend to look at themselves as "enabling". So POSIX standards say that, in order to use POSIX functions, a program must define some macro that will put the development environment in "POSIX mode". For the ancient POSIX 1003.1-1990, the symbol is _POSIX_SOURCE. For recent revisions, it's _POSIX_C_SOURCE with an appropriate value. POSIX 1003.1-1996 says that, to use its features in a portable manner, you must define _POSIX_C_SOURCE=199506L before including any header files.But for Solaris, or Digital Unix, the picture is different. POSIX is one important but small part of the universe. Yet POSIX unconditionally and unambiguously REQUIRES that, when _POSIX_C_SOURCE=199506L, ALL of the functions and definitions required by the standard, and NO others (except in specific restricted namespaces, specifically "_" followed by an uppercase letter or "__" followed by a lowercase letter) shall be visible. That kinda puts a cramp on BSD and SVID support, because those require names that are not in the "protected" POSIX namespaces. It's ILLEGAL to make those symbols visible, unless you've done something else that's beyond the scope of POSIX to allow the system to infer that you didn't really mean it.
In most cases, you should just compile, with no standards-related macros defined. The system will make available every interface and definition that isn't incompatible with the "main stream". There may indeed be cases where two standards cross, and you really can't use both together. But, in general, they play nicely together as long as you don't do anything rash -- like telling the system that it's not allowed to let them.
In the area of threads, both Solaris and Digital Unix support incompatible thread APIs. We have POSIX and DCE, they have POSIX and UI. The nasty areas are in the _r routines and in some aspects of signal behavior. You cannot compile a single source file that uses both semantics. That's life. It sounds as if Solaris defaults to the UI variants, but allows you to define this _POSIX_THREAD_SEMANTICS to get around it. We default to POSIX, and allow you to define _PTHREAD_USE_D4 (automatically defined by the cc "-threads" switch) to select the DCE thread variants. That default, because you're operating outside of any individual standard, is really just a marketing decision.
The major difference between ANSI C and earlier C compilers is function prototyping. ANSI C allows function arguments to be checked for type agreement, and (when possible) type coercion in the event of a mismatch. For this to work, functions and their arguments must be declared before they are called. The form for function declarations is different in ANSI C and non-ANSI C (ANSI C also accepts the earlier form, but then does not do type checking).
As of edit 167, C-Kermit tries to take full advantage of ANSI C features, especially function prototyping. This removes many bugs introduced by differing data types used or returned by the same functions on different computers. ANSI C features are automatically enabled when the symbol __STDC__ is defined. Most ANSI C compilers, such as GNU CC and the new DEC C compiler define this symbol internally.
On the downside, ANSI C compilation increases the administrative/bureacratic burden, spewing out countless unneeded warnings about mismatched types, especially when we are dealing with signed and unsigned characters, requiring casts everywhere to shut up the mindless complaints -- there is no use for signed chars in Kermit (or probably anywhere else). Some compilers, mercifully, include a "treat all chars as unsigned" option, and when available it should be used -- not only to stop the warnings, but also to avoid unhelpful sign extension on high-bit characters.
To force use of ANSI C prototypes, include -DCK_ANSIC on the cc command line. To disable the use of ANSI prototypes, include -DNOANSI.
As the years go by, standards with-which-all-must-comply continue to pile up: AES, XPG2, XPG3, XPG4, FIPS 151-2, successive generations of POSIX, OSF/1, X/Open, Spec 1170, UNIX95, Open Group UNIX98, ISO/IEC 9945 parts 1-4, ISO 9899, 88Open, OS 99, Single Unix Specification (SUS, IEEE 1003.1-2001, not to mention "mature standards" like V7, 4.2/4.3BSD, System V R3 and R4 (SVID2 and SVID3), 4.4BSD (the basis for BSDI, OpenBSD, NetBSD, FreeBSD, Mac OS X etc), /usr/group, plus assorted seismic pronouncements of the neverending series of ephemeral corporate consortia, not to mention the libc-vs-glibc turmoil in the Linux arena and who knows what else.
None of these standards simplifies life for portable applications like C-Kermit -- each one is simply one more environment to support (or circumvent, as in many cases these standards do more harm than good by denying access to facilities we need, e.g. as noted in above in 9.1.1).
On most modern platforms, applications are -- and often must be -- dynamically linked. This has numerous advantages (smaller executables, ability to patch a library and thereby patch all applications that use it, etc), but also causes some headaches: most commonly, the library ID built into the executable at link time does not match the ID of the corresponding library on the target system, and so the loader refuses to let the application run.
This problem only gets worse over time. In the Linux and *BSD world, we also have totally different libraries (each with their own names and numbering systems) that cover the same territory; for example, curses vs ncurses, libc versus glibc. Combinations proliferate and any given Unix computer might have any combination. For this reason it is becoming increasingly difficult to produce a "Linux binary" for a given architecture (e.g. PC or Alpha). There has to be a separate binary for (at least) every combination of curses vs ncurses and libc vs glibc.
In such cases, the best advice is for every user to build C-Kermit from source code on the system where it will run. Too bad most commercial Unix vendors have stopped including C compilers with the operating system!
Normally, including a BSD, System-V, POSIX, or DIRENT flag in the make entry selects the right file system code. But some versions of Unix are inconsistent in this regard, and building in the normal way either gives compiler or linker errors, or results in problems at runtime, typically failure to properly expand wildcard file specifications when you do something like "send *.*", or failure to recognize long filenames, as in "send filewithaveryveryveryveryverylongname".
C-Kermit is supposed to know about all the various styles of Unix file systems, but it has to be told which one to use when you build it, usually in the makefile target CFLAGS as shown below, but you might also have to add something like -I/usr/include/bsd to CFLAGS, or something like -lbsd to LIBS.
C-Kermit gives you the following CFLAGS switches to adapt to your file system's peculiarities:
-DDIRENT - #include <dirent.h> -DSDIRENT - #include <sys/dirent.h> -DNDIR - #include <ndir.h> -DXNDIR - #include <sys/ndir.h> -DRTU - #include "/usr/lib/ndir.h", only if NDIR and XNDIR not defined. -DSYSUTIMH - #include <sys/utime.h> for setting file creation dates. -DUTIMEH - #include <utime.h> for setting file creation dates.
(Note, RTU should only be used for Masscomp RTU systems, because it also selects certain other RTU-specific features.)
If none of these is defined, then <sys/dir.h> is used. IMPORTANT: If your system has the file /usr/include/dirent.h then be sure to add -DDIRENT to your makefile target's CFLAGS. "dirent" should be used in preference to any of the others, because it supports all the features of your file system, and the others probably don't.
Having selected the appropriate directory header file, you might also need to tell Kermit how to declare the routines and variables it needs to read the directory. This happens most commonly on AT&T System-V based UNIXes, particularly System V R3 and earlier, that provide long file and directory names (longer than 14 characters). Examples include certain releases of HP-UX, DIAB DNIX, older versions of Silicon Graphics IRIX, and perhaps also MIPS. In this case, try adding -DLONGFN to your makefile target.
Another problem child is <sys/file.h>. Most Unix C-Kermit versions need to #include this file from within ckufio.c and ckutio.c, but some not only do not need to include it, but MUST not include it because (a) it doesn't exist, or (b) it has already been included by some other header file and it doesn't protect itself against multiple inclusion, or (c) some other reason that prevents successful compilation. If you have compilation problems that seem to stem from including this file, then add the following switch to CFLAGS in your makefile target:
-DNOFILEH
There are a few odd cases where <sys/file.h> must be included in one of the cku[ft]io.c files, but not the other. In that case, add the aforementioned switch, but go into the file that needs <sys/file.h> and add something like this:
#ifdef XXX /* (where XXX is a symbol unique to your system) */ #undef NOFILEH #endif /* XXX */
before the section that includes <sys/file.h>.
Kermit's SEND command expands wildcard characters "?" and "*" itself. Before version 5A, commands like "send *" would send all regular (non-directory) files, including "hidden files" (whose names start with "."). In version 5A, the default behavior is to match like the Bourne shell or the ls command, and not include files whose names start with dot. Such files can still be sent if the dot is included explicitly in the SEND command: "send .oofa, send .*". To change back to the old way and let leading wildcard characters match dot files, include the following in your CFLAGS:
-DMATCHDOT
(In C-Kermit 6.0, there is also a command to control this at runtime.)
Complaints about data-type mismatches:
File creation dates: C-Kermit attempts to set the creation date/time of an incoming file according to the date/time given in the file's attribute packet, if any. If you find that the dates are set incorrectly, you might need to build Kermit with the -DSYSUTIMEH flag, to tell it to include <sys/utime.h>. If that doesn't help, look at the code in zstrdt() in ckufio.c.
Hardware flow control is a problematic concept in many popular Unix implementations. Often it is lacking altogether, and when available, the application program interface (API) to it is inconsistent from system to system. Here are some examples:
-DTERMIOX
to your CFLAGS. If the file is in /usr/include/sys instead, add:
-DSTERMIOX
Note that the presence of this file does not guarantee that RTS/CTS will actually work -- that depends on the device-driver implementation (reportedly, many Unix versions treat hardware-flow-control related ioctl's as no-ops).
See the routine tthflow() in ckutio.c for details. If you find that your system offers hardware flow control selection under program control, you can add this capability to C-Kermit as follows:
To illustrate the difficulties with RTS/CTS, here is a tale from Jamie Watson <jw@adasoft.ch>, who added the RTS/CTS code for the RS/6000, about his attempts to do the same for DEC ULTRIX:
"The number and type of hardware signals available to/from a serial port vary between different machines and different types of serial interfaces on each machine. This means that, for example, there are virtually no hardware signals in or out available on the DECsystem 3000/3100 series; on the DECsystem 5000/2xx series all modem signals in/out are present on both built-in serial ports; on the DECsystem 5100 some ports have all signals and some only have some; and so on... It looks to me as if this pretty well rules out any attempt to use hardware flow control on these platforms, even if we could figure out how to do it. The confusion on the user level about whether or not it should work for any given platform or port would be tremendous. And then it isn't clear how to use the hardware signals even in the cases where the device supports them."
The allowable speeds for the SET SPEED command are defined in ckcdeb.h. If your system supports speeds that are not listed in "set speed ?", you can add definitions for them to ckcdeb.h.
Then if the speed you are adding is one that was never used before in Kermit, such as 921600, you'll also need to add the appropriate keywords to spdtab[] in ckuus3.c, and the corresponding case to ttsspd() in ckutio.c.
There is no standard for millisecond sleeps, but at least five different functions have appeared in various Unix versions that can be used for this purpose: nap() (mostly in System V), usleep() (found at least in SunOS and NeXT OS), select() (found in 4.2BSD and later, and part of any TCP/IP sockets library), nanosleep(), and sginap(). If you have any of these available, pick one (in this order of preference, if you have more than one):
-DSELECT: Include this in CFLAGS if your system has the select() function. -DNAP: Include this in CFLAGS if your system has the nap() function. -USLEEP: Include this in CFLAGS if your system has the usleep() function.
NOTE: The nap() function is assumed to be a function that puts the process to sleep for the given number of milliseconds. If your system's nap() function does something else or uses some other units of time (like the NCR Tower 32, which uses clock-ticks), do not include -DNAP.
Reportedly, all versions of System V R4 for Intel-based computers, and possibly also SVR3.2, include nap() as a kernel call, but it's not in the library. To include code to use it via syscall(3112,x), without having to include Xenix compatibility features, include the following compile-time option:
-DNAPHACK
Some AT&T Unix versions have no way to check if input is waiting on a tty device, but this is a very important feature for Kermit. Without it, sliding windows might not work very well (or at all), and you also have to type your escape character to get Kermit's attention in order to interrupt a local-mode file transfer. If your system offers an FIONREAD ioctl, the build procedure should pick that up automatically and use it, which is ideal.
If your system lacks FIONREAD but has a select() function, this can be used instead. If the build procedure fails to include it (SHOW FEATURES will list SELECT), then you can add it to your CFLAGS:
-DSELECT
Conversely, if the build procedure tries to use select() when it really is not there, add:
-DNOSELECT
Note: select() is not part of System V nor of POSIX, but it has been added to various System-V- and POSIX-based systems as an extension.
Some System-V variations (SCO Xenix/UNIX/ODT and DIAB DNIX) include a rdchk() function that can be used for buffer peeking. It returns 0 if no characters are waiting and 1 if characters are waiting (but unlike FIONREAD, it does not tell the actual number). If your system has rdchk(), add:
-DRDCHK: Include this in CFLAGS if your system has the rdchk() function.
Otherwise, if your version of Unix has the poll() function (and the /usr/include/poll.h file) -- which appears to be a standard part of System V going back to at least SVR3, include:
-DCK_POLL
Systems with <termios.h> might have the symbol IEXTEN defined. This is used to turn "extended features" in the tty device driver on and off, such as Ctrl-O to toggle output flushing, Ctrl-V to quote input characters, etc.
In most Unix implementations, it should be turned off during Kermit operation, so if ckutio.c finds this symbol, it uses it. This is necessary, at least, on BSDI. On some systems, however, IEXTEN is either misdefined or misimplemented. The symptom is that CR, when typed to the command processor, is echoed as LF, rather than CRLF. This happens (at least) on Convex/OS 9.1. The solution is to add the following symbol to the makefile target's CFLACS:
-DNOIEXTEN
However, in at least one Unix implementation, QNX 4.21, IEXTEN must be set before hardware flow control can be used.
In edits 177 and earlier, workstation users noticed a "slow screen writing" phenomenon during interactive command parsing. This was traced to a setbuf() call in ckutio.c that made console (stdout) writes unbuffered. This setbuf() call has been there forever, and could not be removed without some risk. Kermit's operation was tested on the NeXT in edit 178 with the setbuf() call removed, and the slow-writing symptom was cured, and everything else (command parsing, proper wakeup on ?, ESC, Ctrl-U, and other editing characters, terminal emulation, remote-mode and local-mode file transfer, etc) seemed to work as well as or better than before. In subsequent edits, this change was made to many other versions too, with no apparent ill effects. To remove the setbuf() call for your version of Kermit, add:
-DNOSETBUF
Later reports indicate that adding -DNOSETBUF has other beneficial effects, like cutting down on swapping when Kermit is run on workstations with small memories. But BEWARE: on certain small Unix systems, notably the AT&T 6300 and 3B1 (the very same ones that benefit from NOSETBUF), NOSETBUF seems to conflict with CK_CURSES. The program builds and runs OK, but after once using the curses display, echoing is messed up. In this case, we use a System-V specific variation in the curses code, using newterm() to prevent System V from altering the buffering. See makefile entries for AT&T 6300 and 3B1.
The Unix version of C-Kermit includes code to switch to file descriptor zero (stdin) for remote-mode file transfer. This code is necessary to prevent Kermit from giving the impression that it is "idle" during file transfers, which, at some sites, can result in the job being logged out in the middle of an active file transfer by idle-job monitors.
However, this feature can interfere with certain setups; for example, there is a package which substitutes a pty/tty pair for /dev/tty and sets file descriptor 0 to be read-only, preventing Kermit from sending packets. Or... When a Unix shell is invoked under the PICK environment, file descriptor 0 is inoperative.
To remove this feature and allow Kermit to work in such environments, add the compile-time option:
-DNOFDZERO
On some versions of Unix, earlier releases of C-Kermit were reported to render a tty device unusable after a hangup operation. Examples include IBM AIX on the RT PC and RS/6000. A typical symptom of this phenomenon is that the DIAL command doesn't work, but CONNECTing to the device and dialing manually do work. A further test is to SET DIAL HANGUP OFF, which should make dialing work once by skipping the pre-dial hangup. However, after the connection is broken, it can't be used any more: subsequent attempts to DIAL the same device don't work. The cure is usually to close and reopen the device as part of the hangup operation. To do this, include the following compile-time option:
-DCLSOPN
Similarly, there is a section of code in ttopen(), which does another close(open()) to force the O_NDELAY mode change. On some systems, the close(open()) is required to make the mode change take effect, and apparently on most others it does no harm. But reportedly on at least one System V R4 implementation, and on SCO Xenix 3.2, the close(open()) operation hangs if the device lacks carrier, EVEN THOUGH the CLOCAL characteristic has just been set to avoid this very problem. If this happens to you, add this to your CFLAGS:
-DNOCOTFMC
or, equivalently, in your KFLAGS on the make command line. It stands for NO Close(Open()) To Force Mode Change.
C-Kermit renames files when you give a RENAME command and also according to the current SET FILE COLLISION option when receiving files. The normal Unix way to rename a file is via two system calls: link() and unlink(). But this leaves open a window of vulnerability. Some Unix systems also offer an atomic rename(oldname,newname) function. If your version of Unix has this function, add the following to your CFLAGS:
-DRENAME
C-Kermit predefines the RENAME for several Unix versions in ckcdeb.h (SVR4, SUNOS41, BSD44, AIXRS, etc). You can tell if rename() is being used if the SHOW FEATURES command includes RENAME in the compiler options list. If the predefined RENAME symbol causes trouble, then add NORENAME to your CFLAGS. Trouble includes:
If rename() is not used, then Kermit uses link()/unlink(), which is equivalent except it is not atomic: there is a tiny interval in which some other process might "do something" to one of the files or links.
Some Unix systems (Olivetti X/OS, Amdahl UTS/V, ICL SVR3, etc) define the S_ISREG and S_ISDIR macros incorrectly. This is compensated for automatically in ckufio.c. Other systems might have this same problem. If you get a compile-time error message regarding S_ISREG and/or S_ISDIR, add the following to your CFLAGS:
-DISDIRBUG
Finally, here's a symbol you should NEVER define:
-DCOMMENT
It's used for commenting out blocks of code. If for some reason you find that your compiler has COMMENT defined, then add -UCOMMENT to CFLAGS or KFLAGS! Similarly, some header files have been known to define COMMENT, in which case you must add "#undef COMMENT" to each C-Kermit source module, after all the #includes.
When C-Kermit enters interactive command mode, it sets a Control-C (terminal keyboard interrupt = SIGINT) trap to allow it to return to the command prompt whenever the user types Control-C (or whatever is assigned to be the interrupt character). This is implemented using setjmp() and longjmp(). On some systems, depending on the machine architecture and C compiler and who knows what else, you might get "Memory fault (coredump)" or "longjmp botch" instead of the desired effect (this should not happen in 5A(190) and later). In that case, add -DNOCCTRAP to your CFLAGS and rebuild the program.
Job control -- the ability to "suspend" C-Kermit on a Unix system by typing the "susp" character (normally Ctrl-Z) and then resume execution later (with the "fg" command) -- is a tricky business. C-Kermit must trap suspend signals so it can put the terminal back into normal mode when you suspend it (Kermit puts the terminal into various strange modes during interactive command parsing, CONNECT, and file transfer). Supporting code is compiled into C-Kermit automatically if <signal.h> includes a definition for the SIGTSTP signal. HOWEVER... some systems define this signal without supporting job control correctly. You can build Kermit to ignore SIGTSTP signals by including the -DNOJC option in CFLAGS. (You can also do this at runtime by giving the command SET SUSPEND OFF.)
NOTE: As of version 5A(190), C-Kermit makes another safety check. Even if job control is available in the operating system (according to the numerous checks made in congm()), it will still disable the catching of SIGTSTP signals if SIGTSTP was set to SIG_IGN at the time C-Kermit was started.
System V R3 and earlier systems normally do not support job control. If you have an SVR3 system that does, include the following option in your CFLAGS:
-DSVR3JC
On systems that correctly implement POSIX signal handling, signals can be handled more reliably than in Bell, Berkeley, or AT&T Unixes. On systems (such as QNX) that are "strictly POSIX", POSIX signal handling *must* be used, otherwise no signal will work more than once. If you have POSIX-based system and you find that your version of Kermit responds to Ctrl-C (SIGINT) or Ctrl-Z (SIGTSTP) only once, then you should add the following option to your CFLAGS:
-DCK_POSIX_SIG
But be careful; some POSIX implementations, notably 4.4BSD, include POSIX signal handling symbols and functions as "stubs" only, which do nothing. Look in <signal.h> for sigsetjmp and siglongjmp and read the comments.
NOTE: Red Hat Linux 7.2 and later include a new API that allows serial-port arbitration by non-setuid/gid programs. This API has not yet been added to C-Kermit. If C-Kermit is to be used for dialing out on Red Hat 7.2 or later, it must still be installed as described in this section and the next.
The short version:
In order for C-Kermit to be able to dial out from your Unix computer, you need to give it the same owner, group, and permissions as your other dialout programs, such as cu, tip, minicom, uucp, seyon, etc.
The long version:
Make sure your dialout line is correctly configured for dialing out (as opposed to login). The method for doing this is different for each kind of Unix. Consult your system documentation for configuring lines for dialing out (for example, Sun SPARCstation IPC users should read the section "Setting up Modem Software" in the Desktop SPARC Sun System and Network Manager's Guide, or the Terminals and Modems section of the HP manual, "Configuring HP-UX for Peripherals" (e.g. /usr/sbin/sam => Peripheral Devices => Terminals and Modems => Add Modem).
Unlike most other multiuser, multitasking operating systems, Unix allows multiple users to access the same serial device at the same time, even though there is no earthly reason why two users should do this. When they do, user A will read some of the incoming characters, and user B will read the others. In all likelihood, neither user will see them all. Furthermore, User B can hang up User A's call, etc.
Rather than change Unix to enforce exclusive access to serial devices such as ttys, Unix developers chose instead to use a "lock file". Any process that wants to open a tty device should first check to see if a file of a certain name exists, and if so, not to open the device. If the file does not exist, the process creates the file and then opens the device. When the process closes the device, it destroys the lockfile. This procedure was originated for use with Unix's UUCP, CU, and TIP programs, and so these lockfiles are commonly called "UUCP lockfiles" (UUCP = Unix-to-Unix Copy Program).
As you can imagine, this method is riddled with pitfalls:
In an attempt to address the problem of "stale" lockfiles, most UUCP implementations put the PID (Process ID) of the creating process in the lockfile. Thus, another process that wants to open the corresponding device can check not only for the lockfile itself, but also can check the PID for validity. But this doesn't work well either:
Several techniques address the problem of multiple names for the same device:
Most versions of Unix were not designed to accommodate third-party communications software; thus vendors of these Unix products feel no compunction about changing lockfile conventions from release to release, since they also change their versions of the cu, uucp, tip, etc, programs at the same time to match. And since the source code to these programs might not be published, it is difficult for makers of third-party products like C-Kermit to find out what the new conventions are. It also forces release of new versions of C-Kermit whenever the OS vendor makes a change like this.
Some Unix vendors have taken a small step to simplify communications application development for their products: the inclusion of lockfile routines in the standard system C runtime libraries to shield the application from the details of lockfile management (IBM AIX is an example). When such routines are used, communications applications do not need modification when lockfile conventions change (although they will need recompiling if the routines are statically linked into the application). In the AIX example, the simple function calls ttylock(), ttyunlock(), and ttylocked() replace hundreds of lines of ugly code in C-Kermit that attempts to keep pace with every release of every Unix product over the last 20 years. Inclusion of ttylock() code occurs when:
-DUSETTYLOCK
is included in the CFLAGS.
If such routines are available, they should be used. The rest of this section applies when they are not.
To fit in with UUCP and other Unix-based communication software, C-Kermit must have the same idea as your system's uucp, cu, and tip programs about what the UUCP lock directory is called, what the lockfile itself is called, and what its contents should be. In most cases, C-Kermit preprocessor flags create the appropriate configuration at compile time if the appropriate makefile target was used (see ckutio.c). The following CFLAGS options can be used to override the built-in configuration:
CFLAGS= -DBSD4 -DLOCK_DIR=\\\"/usr/local/locks\\\" -DNODEBUG
(NOTE: The triple quoting assumes this is a "top-level" make entry, and not a make entry that calls another one.)
When the LK.inode.major.minor form is used, a single lockfile is enough. Otherwise, a single lockfile rarely suffices. For example, in Linux, it is common to have a /dev/modem symbolic link to an actual dialout device, like /dev/cua0 or /dev/ttyS0, whose purpose is to hide the details of the actual driver from the user. So if one user opens /dev/modem, a lockfile called LCK..modem is created, which does not prevent another user from simulataneously opening the same device by its real name.
On SCO Unix platforms, we have a slightly different problem: the same device is, by convention, known by "lowercase" and "uppercase" names, depending on whether it has modem control. So by convention, communications programs are supposed to create the lockfiles based on the lowercase name. But some programs don't follow this convention. In HP-UX, we have several different names for each serial device. And so on.
For this reason, on platforms where the LK.inode.major.minor form is not used, C-Kermit also creates a secondary lockfile (which is simply a link to the first) if:
NOTE: symlinks are not handled in HP-UX.
Honey DanBer (HDB) UUCP, which is becoming increasingly popular, has two characteristics:
Non-HDB selections assume the lockfile contains the pid in int form (or, more precisely, in PID_T form, where PID_T is either int or pid_t, depending on your system's C library and header files). (b), by the way, is subject to interpretation: the numeric ASCII string may or may not be terminated by a newline, it may or may not have leading spaces (or zeros), and the number of leading spaces or zeros can differ, and the differences can be significant.
Even if you build the program with the right lockfile option, you can still have problems when you try to open the device. Here are the error messages you can get from SET LINE, and what they mean:
There are two solutions for problems (b) and (c), both of which involve intervention by your Unix system administrator (superuser):
su% chmod 777 /usr/spool/locks (or whatever the path is) su% chmod 666 /dev/ttyXX
One risk here is that people can write lots of junk into the lockfile directory, delete other people's files in the lockfile directory, and intercept other people's data as it goes in and out of the tty device. The major danger here would be intercepting a privileged password. Of course, any user could write a short, ordinary, unprivileged program to do exactly the same thing if the tty device was world read/writeable. The other risk as that telephone calls are not controlled -- anybody on your system can make them, without having to belong to any particular group, and this could run up your phone bill.
su% chmod 770 /usr/spool/locks (or whatever the path is) su% chmod 660 /dev/ttyXX
User whatever tool is available on your platform to add users to the appropropriate group (e.g. edit the /etc/group file).
su% chown uucp kermit - or - chgrp uucp kermit su% chmod u+s kermit (setuid) - or - chmod g+s kermit (setgid)
and then make sure the lockfile directory, and the tty devices, have owner (setuid) and/or group (setgid) write permission. For example:
su% chmod o+rwx /usr/spool/uucp su% chown uucp /dev/ttyXX ; chmod 600 /dev/ttyXX
In some cases, the owner and group must be distinct; the key point is that read/write access is required to both the UUCP lockfile directory and the tty itself.
If you make C-Kermit setuid or setgid to root, it refuses to run:
Fatal: C-Kermit setuid to root!
Example:
crw-r----- 1 uucp uucp 5, 67 Feb 11 06:23 /dev/cua3 drwxrwxr-x 3 root uucp 1024 Feb 11 06:22 /var/lock
requires suid uucp to get read/write access on /dev/cua3 and sgid to get read/write access on /var/lock (since you can't set Kermit's uid or gid to root).
The reason Kermit can't be setuid or setgid to root has to do with the fact that some Unix OS's can't switch user or group IDs in that case. Unfortunately, the prohibition against making Kermit setuid or setgid to root means that Unix C-Kermit can't be used to make rlogin connections by non-root users. (The rlogin port is privileged, which is why the regular rlogin command is setuid root -- which is safe because the rlogin program never has to create or access files like Kermit does.)
For the lockfile mechanism to achieve its desired purpose -- prevention of access to the same tty device by more than one process at a time -- ALL programs on a given computer that open, read or write, and close tty devices must use the SAME lockfile conventions. Unfortunately, this is often not the case. Here is a typical example of how this can go wrong: In SunOS 4.0 and earler, the lockfile directory was /usr/spool/uucp; in 4.1 it was changed to /var/spool/locks in the quest for political correctness. Consequently, any third-party programs (such as C-Kermit) that were not modified to account for this change, recompiled, and reinstalled, did not use the same lockfiles as uucp, tip, etc, and so the entire purpose of the lockfile is defeated.
What if your Unix system does not have UUCP installed? For example, you have a Unix workstation, and you do not use uucp, cu, or tip, or UUCP was not even supplied with your version of Unix (QNX is an example). In this case, you have two choices:
-DLOCK_DIR=\\\"/usr/spool/kermit\\\"
Even if you don't intend to run C-Kermit setuid, somebody else might come along and chown and chmod it after it has been built. You should be sure that it is built correctly to run setuid on your system. For POSIX and AT&T Unix based versions, you don't have to do anything special.
For 4.2 and 4.3 BSD-based Unix versions, you normally need not add anything special to the makefile. The program assumes that the setreuid() and setregid() functions are available, without which we cannot switch back and forth between real and effective uids. If "make" complains that _setreuid or _setregid is/are not defined, add -DNOSETREU to CFLAGS. In this case it is very likely (but not certain) that you cannot protect ttys and lockfiles against people and have them run Kermit setuid.
If make does not complain about this, you should find out whether your BSD version (4.3 or other systems like SunOS 4.x that claim to include BSD 4.3 compatibility) includes the saved-setuid feature (see long notes under edit 146 in ckc178.upd). If it does, then add -DSAVEDUID to CFLAGS.
IMPORTANT NOTE: Most Unix system documentation will not give you the required information. To determine whether your Unix system supplies the the saved-original-effective-user/group-id feature, use the ckuuid.c program. Read and follow the instructions in the comments at the beginning.
C-Kermit for 4.4BSD-based systems automatically use sete[ug]id(). See ckutio.c.
If you have a version of Unix that is not BSD-based, but which supplies the setreuid() and setregid() functions, and these are the only way to switch between real and effective uid, add -DSETREUID to your makefile target.
WARNING: There are two calls to access() in ckufio.c, by which Kermit checks to see if it can create an output file. These calls will not work correctly when (a)you have installed C-Kermit setuid or setgid on a BSD-based Unix system, and (b) the saved-original-effective-uid/gid feature is not present, and (c) the access() function always checks what it believes to be the real ID rather than the effective ID. This is the case, for example, in Olivetti X/OS and in NeXTSTEP. In such cases, you can force correct operation of access() calls by defining the symbol SW_ACC_ID at compile time in CFLAGS.
If you have a version of Unix that does not allow a process to switch back and forth between its effective and real user and group ids multiple times, you probably should not attempt to run Kermit setuid, because once having given up its effective uid or gid (which it must do in order to transfer files, fork a shell, etc) it can never get it back, and so it can not use the original effective uid or gid to create or delete uucp lockfiles. In this case, you'll either have to set the permissions on your lockfile directory to make them publicly read/writable, or dispense with locking altogether.
MORAL: Are you thoroughly sickened and/or frightened by all that you have just read? You should be. What is the real answer? Simple. Serial devices -- such as ttys and magnetic tapes -- in Unix should be opened with exclusive access only, enforced by the Unix kernel. Shared access has no conceivable purpose, legitimate or otherwise, except by privileged system programs such as getty. The original design dates from the late 1960s, when Unix was developed for laboratory use under a philosophy of trust by people within shouting distance of each other -- but even then, no useful purpose was served by this particular form of openness; it was probably more of a political statement. Since the emergence of Unix from the laboratory into the commercial market, we have seen every vestige of openness -- but this one -- stripped away. I'd like to see some influential Unix maker take the bold step of making the simple kernel change required to enforce exclusive access to serial devices. (Well, perhaps not so simple when bidirectionality must also be a goal -- but then other OS's like VMS solved this problem decades ago.)
On desktop workstations that are used by only the user at the console keyboard, C-Kermit is always used in local mode. But as delivered, C-Kermit runs in remote mode by default. To put it in local mode at startup, you can put a SET LINE command in your .mykermrc.
You can also build C-Kermit to start up in local mode by default. To do this, include the following in the CFLAGS in your makefile target:
-DDFTTY=\\\"/dev/ttyxx\\\"
where ttyxx is the name of the device you will be using for communications. Presently there is no way of setting the default modem type at compile time, so use this option only for direct lines.
C-Kermit does not work well on certain workstations if it is not run from within a terminal window. For example, you cannot start C-Kermit on a NeXT by launching it directly from NeXTstep. Similarly for Sun workstations in the Open Windows environment. Run Kermit in a terminal window.
See the "beware file",
The program starts, but there is no prompt, and certain operations don't work (you see error messages like "Kermit command error in background execution"). This is because Kermit thinks it is running in the background. See conbgt() in ckutio.c. Try rebuilding Kermit with:
-DPID_T=pid_t
added to your CFLAGS. If that doesn't help, find out the actual data type for pids (look in types.h or similar file) and use it in place of "pid_t", for example:
-DPID_T=short
Unexplainable and inappropriate error messages ("Sockets not supported on this device", etc) have been traced in at least one case to a lack of agreement between the system header files and the actual kernel. This happened because the GNU C compiler (gcc) was being used. gcc wants to have ANSI-C-compliant header files, and so part of the installation procedure for gcc is (or was) to run a shell script called "fixincludes", which translates the system's header files into a separate set of headers that gcc likes. So far so good. Later, a new version of the operating system is installed and nobody remembers to run fixincludes again. From that point, any program compiled with gcc that makes use of header files (particularly ioctl.h) is very likely to misbehave. Solution: run fixincludes again, or use your system's regular C compiler, libraries, and header files instead of gcc.
If C-Kermit constitently dumps core at the beginning of a file transfer, look in SHOW FEATURES for CKREALPATH. If found, rebuild with -DNOREALPATH and see if that fixes the problem (some UNIXes have realpath() but it doesn't work).
Total failure of the Kermit program can occur because of bad memory references, bad system calls, or problems with dynamic memory allocation. First, try to reproduce the problem with debugging turned on: run Kermit with the -d command-line option (for example, "wermit -d") and then examine the resulting debug.log file. The last entry should be in the vicinity of the crash. In VMS, a crash automatically produces a "stack dump" which shows the routine where the crash occurs. In some versions of Unix, you can get a stack dump with "adb" -- just type "adb wermit core" and then give the command "$c", then Ctrl-D to quit (note: replace "wermit" by "kermit" or by the full pathname of the executable that crashed if it is not in the current directory). Or use gdb to get a backtrace, etc.
In edit 186, one implementation, UNISYS 5000/95 built with "make sys5r3", has been reported to run out of memory very quickly (e.g. while executing a short initialization file that contains a SET DIAL DIRECTORY command). Debug logs show that malloc calls are failing, reason unknown. For this and any other implementation that gives error messages about "malloc failure" or "memory allocation failure", rebuild the program *without* the -DDYNAMIC CFLAGS definition, for example:
make sys5r3 KFLAGS=-UDYNAMIC
As of edit 169, C-Kermit includes a malloc() debugging package which you may link with the Kermit program to catch runtime malloc errors. See the makefile entries for sunos41md and nextmd for examples of how to select malloc debugging. Once you have linked Kermit with the malloc debugger, it will halt with an informative message if a malloc-related error occurs and, if possible, dump core. For this reason, malloc-debugging versions of Kermit should be built without the "-s" link option (which removes symbols, preventing analysis of the core dump). You have several ways to track down the malloc error: Analyze the core dump with adb. Or reproduce the problem with "log debug" and then look at the code around the last debug.log entry. If you have gcc, build the program with "-g" added to CFLAGS and then debug it with gdb, e.g.
gdb wermit break main run .. set other breakpoints or watchpoints continue
Watchpoints are especially useful for finding memory leaks, but they make the program run about a thousand times slower than usual, so don't set them until the last possible moment. When a watchpoint is hit, you can use the "where" command to find out which C-Kermit source statement triggered it.
If you have the Pure Software Inc "Purify" product, see the sunos41cp makefile entry for an example of how to use it to debug C-Kermit.
"Syslogging" means recording selected in the system log via the Unix syslog() facility, which is available in most Unix versions. Syslogging is not done unless C-Kermit is started with:
--syslog:n
on the command-line, where n is a number greater than 0 to indicate the level of syslogging. See Section 4.2 of the IKSD Administrator's Guide for details.
Obviously you can't depend on users to include --syslog:3 (or whatever) on the command line every time they start C-Kermit, so if you want certain kinds of records to be recorded in the system log, you can build C-Kermit with forced syslogging at the desired level, e.g.:
make linux KFLAGS=-DSYSLOGLEVEL=2
Levels 2 and 3 are the most likely candidates for this treatment. Level 2 forces logging of all successful dialout calls (e.g. for checking against or phone bills), and level 3 records all connections (SET LINE or SET HOST / TELNET / RLOGIN, etc) so you can see who is connecting out from your system, and to where.
Level 2 and 3 records are equivalent to those in the connection log; see the C-Kermit 7.0 Supplement) for a detailed description of the connection log.
C-Kermit 7.0 and later may be built with Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or SSL/TLS security for strong authentication and encryption of Internet connections. These security methods require external libraries that, in their binary forms, are restricted from export by USA law. See the Kermit Security Reference) for details. C-Kermit binaries themselves are likewise restricted; the C-Kermit binaries that are available for public download on the Internet are not allowed to contain the security options.
Sample makefile entries are provided for Linux and many other operating systems. A list of secure makefile entries is included in the Makefile. Complete instructions on building C-Kermit 8.0 with MIT Kerberos; Secure Remote Password; and/or OpenSSL can be found in the Kermit Security Reference.
C-Kermit 8.0 comes with a current list of Certificate Authority certificates, including one for the Kermit Project that can be used for authentication to Columbia's Internet Kermit Service (IKSD). You can use C-Kermit 7.0 or later to access Columbia's IKSD securely by installing the Kermit Project certificate in /usr/local/ssl/cert.pem (or the appropriate location based upon the installation of OpenSSL on your system). You can find a copy of the certificates file at:
ftp://kermit.columbia.edu/kermit/c-kermit/ca_certs.pem
This requires C-Kermit 8.0.206 or later and an SSH v2 server. If you list C-Kermit as a Subsystem in the SSH v2 server configuration file (as, for example, SFTP is listed), users can make SSH connections direct to a Kermit server as explained here:
http://www.columbia.edu/kermit/skermit.html
The name and location of the SSH server configuration file depends on your platform, which SSH product(s) you have, etc. C-Kermit itself must be referred to in this file as "kermit-sshsub". On the host, install the C-Kermit 8.0.209 binary in the normal way. Then, in the same directory as the C-Kermit binary, make a symbolic link:
ln -s kermit kermit-sshsub
(Note: the "make install" makefile target does this for you.) Then in the sshd configuration file, add a line:
Subsystem kermit /some/path/kermit-sshsub
(where /some/path is the fully specified directory where the symlink is.) This is similar to the line that sets up the SFTP susbsystem. Example:
Subsystem sftp /usr/local/libexec/sftp-server Subsystem kermit /usr/local/bin/kermit-sshsub
The mechanics might vary for other SSH servers; "man sshd" for details. The method shown here is used because the OpenSSH server does not permit the subsystem invocation to include command-line options. C-Kermit would have no way of knowing that it should enter Server mode if it were not called by a special name.
[ Top ] [ Contents ] [ C-Kermit Home ] [ C-Kermit 8.0 Overview ] [ Kermit Home ]