Columbia Kermit/kermit.zip/archives/ckc197.zip/ckuins.txt

Text File | 2000-03-16 | 123KB | 2,485 lines

C-KERMIT 7.0 INSTALLATION INSTRUCTIONS FOR UNIX

  As of C-Kermit version:  7.0.197
  This file last updated:  8 February 2000

  Author: Frank da Cruz, Columbia University

  Copyright (C) 1985, 2000,
    Trustees of Columbia University in the City of New York.
    All rights reserved.  See the C-Kermit COPYING.TXT file or the
    copyright text in the ckcmai.c module for disclaimer and permissions.


DOCUMENTATION

  Frank da Cruz and Christine M. Gianone, "Using C-Kermit", Second Edition,
  1997, Digital Press / Butterworth-Heinemann, Woburn, MA, ISBN 1-55558-164-1
  US single-copy price: $44.95; quantity discounts available.  Available in
  computer bookstores or directly from Columbia University:

    The Kermit Project
    Columbia University
    612 West 115th Street
    New York NY  10025-7799  USA
    Telephone: [phone]
    Email: [e-mail]
    Web: http://www.columbia.edu/kermit/

  The CKERMIT2.TXT file contains supplementary info for C-Kermit 7.0 to be
  used until the 3rd edition of the manual is ready.


CONTENTS

 1. OVERVIEW
 2. INSTALLING FROM PACKAGES
 3. INSTALLING PREBUILT BINARIES
 4. BUILDING FROM SOURCE CODE
    4.0. Special Considerations for C-Kermit 7.0
    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
 5. INSTALLING THE KERMIT FILES
 6. INSTALLING UNIX C-KERMIT FROM DOS-FORMAT DISKETTES
 7. CHECKING THE RESULTS
 8. REDUCING THE SIZE OF THE EXECUTABLE PROGRAM IMAGE
 9. UNIX VERSIONS
    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
10. DIALING OUT AND COORDINATING WITH UUCP
11. RUNNING UNIX C-KERMIT SETUID OR SETGID
12. CONFIGURING UNIX WORKSTATIONS
13. BIZARRE BEHAVIOR AT RUNTIME
14. CRASHES AND CORE DUMPS
15. SYSLOGGING
16. SECURITY OPTIONS


1. OVERVIEW

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 file ckccfg.txt.  For
troubleshooting after installation, see the files ckcbwr.txt and ckubwr.txt.
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, ckcplm.txt.

You may install C-Kermit:

 . From an "install package", if one is available.
 . As a prebuilt binary, if available, plus accompanying text files.
 . By building from source code.


2. INSTALLING FROM PACKAGES

Various UNIX varieties -- Red Hat Linux, Solaris, 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:

 a. Since C-Kermit is portable to many non-UNIX platforms (VMS, VOS, AOS/VS,
    etc), some of the files in the C-Kermit distribution do not fit into the
    UNIX application model.  In particular, C-Kermit includes some plain
    text files (described in Section 5) and UNIX has no standard place to
    put such files.  Typical UNIX package managers do not allow for them.
    Where should they go, and how will the user know where to find them?

 b. Installation of any program that will be used to make modem calls requires
    some important decisions from the installer regarded security and
    privilege.

Item (b) is discussed at length in Section 10 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 protected against "world".  Therefore, the
install procedure must either run as root in order to give the Kermit binary
the required permissions, or else it must open up the permissions on the
devices and lockfile directory.  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:

 a. Check the permissions of the lockfile directory and the dialout devices.
    If they do not allow unprivileged R/W access, then:

 b. "Your UUCP lockfile directory and/or dialout devices require privilege
    to access.  You must either change their permissions or install Kermit
    with privileges."

 c. "If you wish to install Kermit with privileges, it will be given the
    same owner, group, and permissions as the cu program so it can use the
    dialout devices."

 d. If they choose (c) but the user is not root, give message that the
    install procedure can be run only by root and then quit.

The Kermit Project does not necessarily have the resources or the expertise
to make install packages for any (and certainly not all) UNIX (and other)
platforms.  Most install packages, therefore, are contributed by others, and
they do not necessarily follow the guidelines given above.

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.  Read Section 10 for details.


3. INSTALLING PREBUILT BINARIES

Hundreds of prebuilt C-Kermit binaries are available on the CDROM in the
BINARY tree, and at our ftp site in the kermit/binaries area (with names
starting with "ck").  To install a prebuilt binary:

 a. Rename the binary to "wermit".

 b. Follow steps (b) through (e) in Section 4.

But first...  Please heed the following cautions:

 a. If you pick the wrong one, it won't work (or worse).

 b. Even when you pick the appropriate binary, it still might not work due
    to shared-library mismatches, etc. (see Section 4.0).

 c. Don't expect a binary built on or for version "n" of your OS to work
    on version "m" (where m < n).  However, it is usually safe to run a
    binary built on (or for) an older OS release on a newer one.


4. BUILDING FROM SOURCE CODE

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 from users.

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:

 . The C compiler, linker, and make program must be installed.
 . The C libraries and header files must be installed (*).
 . The C-Kermit source code and makefile in your current directory.
 . The C-Kermit text files (Section 5) in your current directory.

(*) This is becoming problematic in this new age of "selective installs"
    e.g. of Linux packages.  C-Kermit builds will often fail because replying
    "no" to some obscure Linux installation option will result in missing
    libraries or header files.

Plus:

 . For TCP/IP networking support, the sockets library and related header
   files must be installed.

 . For the curses-based fullscreen file-ransfer display, the curses or
   ncurses header file(s) and library, and probably also the termcap and/or
   termlib library.  Note that the names and locations of these files and
   libraries are likely to change capriciously with every new release of your
   UNIX product.  If you discover that the C-Kermit build procedure fails
   because your curses and/or termxxx headers or libraries are not named or
   located as expected, please let us know.  In the meantime, work around by
   installing symlinks.

 . IMPORTANT: Modern Linux distributions might give you the choice during
   installation of whether to install the "ncurses development package"
   (perhaps called "ncurses-devel").  If you did not install it, you won't
   be able to build C-Kermit with curses support included.  In this case,
   either go back and install ncurses, or else choose (or create) a
   non-curses makefile target for your platform.  To install the ncurses
   developers tools in Red Hat Linux, do:

     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.

Directions:

The makefile might need to be renamed from ckuker.mak to makefile.

 a. Type "make xxx" where xxx is the name of the makefile target most
    appropriate to your platform, e.g. "make linux", "make aix43", etc.  Read
    the comments at the top of the makefile for a complete list of available
    targets (it's a long list).

 b. Test the resulting 'wermit' file (see Section 7 for suggestions).
    If it's OK, proceed; otherwise notify us.

 c. Rename the 'wermit' file to 'kermit', copy it to the desired binary
    directory (such as /usr/local/bin or /opt/something), and if it is to be
    used for dialing out, give it the same owner, group, and permissions as
    the 'cu' program (IMPORTANT: read Sections 10 and 11 for details).

 d. Install the man page, ckuker.nr, with your local man pages.

 e. Install the accompanying text files (see Section 5).

Steps (c) through (e) can be accomplished using the 'install' target in the
makefile.  Directories are specified by the following variables:

 Name        Default
  BINDIR      /usr/local/bin
  MANDIR      /usr/man/manl
  MANEXT      l (that's letter "l" for "local", not digit 1)
  INFODIR     /usr/local/doc/kermit

To use the defaults, just type "make install".  You can override any of the
defaults on the 'make' command line, e.g.:

  make "INFODIR=/usr/share/lib/kermit" install

The 'install' target does not attempt to set Kermit's owner, group, and
permissions to allow dialing out.  This requires privileges and open eyes.
Please read Sections 10 and 11 below, make the necessary decisions, and then
implement them by hand as described in those sections.


4.0. Special Considerations for C-Kermit 7.0

(Also see ckccfg.txt Section 8.)

Lots of new features have been added, requiring 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 all we know as of the date of this file.

The first category concerns the new Kermit Service Daemon (IKSD; see separate
iksd.txt file for details):

The wtmp File
  When C-Kermit is started as an IKSD (under inetd), it makes syslog and wtmp
  entries, and also keeps its own ftpd-like log.  The code assumes the wtmp
  log is /var/log/wtmp on Linux and /usr/adm/wtmp elsewhere.  No doubt this
  assumption will need adjustment.  Use -DWTMPFILE=path to override at compile
  time (there is also a runtime override).  See iksd.txt for details.

UTMP, utsname(), etc.
  C-Kermit 7.0 gets as much info as it can about its job -- mainly for IKSD
  logging -- from utmp.  But of course utmp formats and fields differ, and
  for that matter, there can be two different header files, <utmp.h> and
  <utmpx.h>.  Look for HAVEUTMPX and HAVEUTHOST in ckufio.c, let me know of
  any needed adjustments.

Password lookup
  IKSD also needs to authenticate incoming users against the password list.
  In some cases, this requires the addition of -lcrypt (e.g. in Unixware 2.x).
  In most others, the crypt functions are in the regular C library.  If you
  get "crypt" as an unresolved symbol at link time, add -lcrypt to LIBS.
  If your site has local replacement libraries for authentication, you might
  need a special LIBS clause such as "LIBS= -L/usr/local/lib -lpwent".

getusershell()
  This is called by the IKSD at login time to see if a user has been
  "turned off".  But many UNIX platforms lack this function.  In that case,
  you will get unresolved symbol reports at link time for _getusershell,
  _endusershell; to work around, add -DNOGETUSERSHELL.

initgroups()
  This is called by IKSD after successful authentication.  But some platforms
  do not have this function, so obviously it can't be called there, in which
  case add -DNOINITGROUPS.

setreuid(), setregid() not found or "deprecated"
  Find out what your UNIX variety wants you to use instead, and make
  appropriate substitutions in routine zvpass(), module ckufio.c.

printf()
  IKSD installs a printf() substitute to allow redirection of printf-like
  output to the connection.  However, this can conflict with some curses
  libraries.  In this case, separate binaries must be built for IKSD and
  non-IKSD use.

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:

Return type of main()
  The main() routine is in ckcmai.c.  If you get complaints about "main:
  return type is not blah", define MAINTYPE on the CC command line, e.g.
  '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"'

DNS Service Records
  This feature allows a remote host to redirect C-Kermit to the appropriate
  socket for the requested service; e.g. if C-Kermit requests service
  "telnet" and the host offers Telnet service on port 999 rather than the
  customary port 23.  If you get compile-time complaints about not being
  able to find <resolv.h>, <netdb.h>, or <arpa/nameser.h>, add -DNO_DNS_SRV
  to CFLAGS.  If you get link-time complaints about unresolved symbols
  res_search or dn_expand, try adding -lresolve to LIBS.

\v(ipaddress)
  If "echo \v(ipaddress)" shows an empty string rather than your local
  IP address, add -DCKGHNLHOST to CFLAGS and rebuild.

<sys/wait.h>
  If this file can't be found at compile time, add -DNOREDIRECT to CFLAGS.
  This disables the REDIRECT and PIPE commands and anything else that needs
  the wait() system service.

syslog()
  C-Kermit can now write syslog records.  Some older platforms might not have
  the syslog facility.  In that case, add -DNOSYSLOG.  Others might have it,
  but require addition of -lsocket to LIBS (SCO OSR5 is an example).  See
  Section 15.

putenv()
  If "_putenv" comes up as an undefined symbol, add -DNOPUTENV to CFLAGS
  and rebuild.

"Passing arg1 of 'time' from incompatible pointer"
  This is a mess.  See the mass of #ifdefs in the appropriate module,
  ckutio.c or ckufio.c.

gettimeofday()
  Wrong number of arguments.  On most platforms, gettimeofday() takes two
  arguments, but on a handful of others (e.g. Motorola System V/88 V4,
  SNI Reliant UNIX 5.43, etc) it takes one.  If your version of gettimeofday()
  is being called with two args but wants one, add -DGTODONEARG.

"Assignment makes pointer from integer without a cast"
  This warning might appear in ckufio.c or ckutio (or elsewhere), and usually
  can be traced to the use of a system or library function that returns a
  pointer but that is not declared in the system header files even though it
  should be.  Several functions are commonly associated with this error:
   . getcwd(): Add -DDCLGETCWD to CFLAGS and rebuild.
   . popen():  Add -DDCLPOPEN  to CFLAGS and rebuild.
   . fdopen(): Add -DDCLFDOPEN to CFLAGS and rebuild.

"Operands of = have incompatible types" (or "Incompatible types in assignment")
  If this comes from ckcnet.c and comes from a statement involving inet_addr(),
  try adding -DINADDRX to CFLAGS.  If that doesn't help, then try adding
  -DNOMHHOST.

Complaints about args to get/setsockopt(), getpeername(), getsockname()
  These are all in ckcnet.c.  Different platforms & OS's and versions of the
  same OS change this all the time: int, size_t, unsigned long, etc.  All the
  affected variables are declared according to #ifdefs within ckcnet.c, so
  find the declarations and adjust the #ifdefs accordingly.

size_t
  In case of complaints about "unknown type size_t", add -DSIZE_T=int (or
  other appropriate type) to CFLAGS.

'tz' undefined
Use of undefined enum/struct/union 'timezone'
Left of 'tv_sec' specifies undefined struct/union 'timeval'
  And similar complaints in ckutio.c: Add -DNOGFTIMER and/or -DNOTIMEVAL.

Symlinks
  The new built-in DIRECTORY command should show symlinks like "ls -l" does.
  If it does not, check to see if your platform has the lstat() and
  readlink() functions.  If so, add -DUSE_LSTAT and -DCKSYMLINK to CFLAGS
  and rebuild.  On the other hand, if lstat() is unresolved at link time,
  add -DNOLSTAT to CFLAGS.  If readlink() is also unresolved, add -DNOSYMLINK.

realpath()
  Link-time complains about realpath() -- find the library in which it resides
  and add it to LIBS (example for Unixware 7.1: "-lcudk70") or add
  -DNOREALPATH to CFLAGS and rebuild.

Failure to locate header file <term.h>
  Usually happens on Linux systems that have the C compiler installed,
  but not the ncurses package (see comments about selective installs above).
  Go back and install ncurses, or use "make linuxnc" (Linux No Curses).

"Can't find shared library libc.so.2.1"
"Can't find shared library libncurses.so.3.0", etc...
  You are trying to run a binary that was built on a computer that has
  different library versions than your computer, and your computer's
  loader is picky about library version numbers.  Rebuild from source
  on your computer.

Time (struct tm) related difficulties:
  Errors like the following:

    "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 is still used is
  OSF/1 and its derivatives (Digital UNIX and Tru64 UNIX).

Struct timeval and/or timezone not declared:
  In some cases, merely including the appropriate time.h header files is still
  not enough.  POSIX.1 does not define the timeval struct, and so the items we
  need from the header are protected against us by #ifndef _POSIX_SOURCE or
  somesuch.  In this case, we have to declare the timeval (and timezone)
  structs ourselves.  To force this, include -DDCLTIMEVAL in CFLAGS.

Warnings about dn_expand() Argument #4
  WARNING: argument is incompatible with prototyp.  It's the old char versus
  unsigned char stupidity again.  Try to find a compiler switch like GCC's
  "-funsigned-char".  Failing that, add -DCKQUERYTYPE=xxx to CFLAGS, where
  xxx is whatever 'man dn_expand' tells you the type of the 4th argument
  should be (presumably either char or unsigned char; in the latter case use
  CHAR to avoid confusion caused by multiple words.

Switch Table Overflow (in ckouni.c)
  Add -DNOUNICODE to CFLAGS.

Compile-time warnings about ck_out() or tgetstr() or tputs():
  Easy solution: Add -DNOTERMCAP to CFLAGS.  But then you lose the SCREEN
  function.  Real solution:  Try all different combinations of the following
  CFLAGS:
         -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.

"Passing arg 1 of to tputs() makes pointer from integer without a cast":
  Add -DTPUTSARG1CONST to CFLAGS.

"Undefined symbol: dup2"
  Add -DNOZEXEC to CFLAGS.

"header file 'termcap.h' not found"
  Add -DNOHTERMCAP to CFLAGS.

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.

(*) C-Kermit does not use the signed property of chars at all anywhere,
    ever.  So if all chars and char *'s can be made unsigned at compile
    time, as they can in gcc with "-funsigned-char", they should be.

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:

  [e-mail].

4.1. The UNIX Makefile

If your distribution does not contain a file with this name, then
rename the file called ckuker.mak to makefile:

  mv ckuker.mak makefile

and then you type "make xxx", where xxx is the system 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

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 7.0
can't be build 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 entry 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.

If you have trouble with building ckwart.c, or running the resulting wart
preprocessor program on ckcpro.w:

  1. Just "touch" the ckcpro.c file that comes in the distribution and
     then give the "make" command again, or:

  2. Compile ckwart.c "by hand":  cc -o wart ckwart.c, or:

  3. Try various other tricks.  E.g. one Linux user reported that that adding
     the "static" switch to the rule for building wart fixed everything:

     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.

To add compilation options (which are explained later in this document) to
your makefile entry 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 entry.  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 entry.)

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 entry, "make
clean" first.

If you create a new makefile entry, 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"

4.2. The C-Kermit Initialization File

There are several choices for how to handle the C-Kermit initialization file.

 a. The default action is to execute ~/.kermrc (i.e. the ".kermrc" file in
    the user's login directory) upon startup.  But since the initialization
    is standardized, it would be wasteful on multiuser systems to duplicate it
    in every user's home directory.

 b. Define a system-wide initialization file (described below).

 c. Install the standard initialization file in the system-wide PATH as an
    executable Kerbang script (ckermit2.txt Section 7.19).  Users who want to
    take advantage of the services directory and other features that are
    defined in the standard initialization file can "run" the initialization
    file to get them, whereas those who don't need them can run Kermit
    directly.

If you want to define a system-wide initialization file for C-Kermit, rather
than making each user have her/his own copy, define the symbol CK_SYSINI to be
the full pathname of the file, e.g.:

  -DCK_SYSINI=\\\"/usr/local/lib/kermit/ckermit.ini\\\"

It's best to edit the makefile to add this, because there is no good method
for putting it on the 'make' command line with KFLAGS -- the number of escapes
(\\\\...) for the doublequotes would depend on how deeply the particular make
entry is nested; each level of nesting strips off another layer of escapes.
Here's one example that works, but other targets will be different:

  make sunos41 "KFLAGS=-DCK_SYSINI=\\\\\\\"/usr/local/lib/ckermit.ini\\\\\\\""

Or, you can define CK_DSYSINI (note "D") to build C-Kermit with its built-in
default name for a system-wide init file, /usr/local/bin/ckermit.ini, or
/usr/share/lib/kermit/ckermit.ini, depending on which version of UNIX it is.
Since no quoting is needed, this one works with KFLAGS, e.g.:

  make sunos41c KFLAGS=-DCK_DSYSINI

The question arises: if you want C-Kermit to have a system-wide initialization
file, should it take precedence over the user's own?  There are valid reasons
for answering yes or no.  By default, if you build C-Kermit with a system-wide
initialization file, it will take precedence over the user's -- that is, it
will be executed instead of the user's, if the user has one.  You might also
want to set things up so the user's init file is executed if she has one, but
if she doesn't, the system-wide one will be.  Either setup is possible.
Assuming CK_SYSINI is defined, then the following symbols determine the order:

  CK_INI_A
    This means the system-wide init file is looked for first; if found, it
    is executed.  If not found, the user's init file is executed.

  CK_INI_B
    This means the user's init file is looked for first; if found, it is
    executed.  If not found, the system-wide init file is executed.

If CK_SYSINI is defined, but neither CK_INI_A nor CK_INI_B are defined (or
both of them are), then CK_INI_A is assumed.

If you build Kermit with CK_SYSINI and CK_INI_A, you can "chain" to the user's
own initialization file (if any) by ending (or starting, depending on the
desired precedence) the system-wide init file with a command like:

  if exist \v(home).kermrc take \v(home).kermrc

In any case, the initialization file should chain to the user's customization
file, as in this clause from the standard ckermit.ini:

  if exist \m(_myinit)  {        ; If it exists,
      echo Executing \m(_myinit)...    ; print message,
      take \m(_myinit)            ; and TAKE the file.
  }

4.3. The 2.x BSD Makefile

Use the separate makefile ckubs2.mak.  Read the instructions in that file.
NOTE: C-Kermit 6.0 was probably the last version of C-Kermit that could be
built for 2.x BSD -- it just barely fit with a few bytes to spare into the
maximum overlay model.  More recent versions are larger.  But it might be
possible to make it fit using different overlay arrangements; anybody who
cares is welcome to try.

4.4. The Plan 9 Makefile

Use the separate makefile ckpker.mk.

4.5. Makefile Failures

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 entry.  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 entry.

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 entry, 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 -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=datax.

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 entry's CFLAGS, for example -UFIONREAD.

Some well-known symbol is missing from your system header files.  Try defining
in the makefile entry'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
entry 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.


5. INSTALLING THE KERMIT FILES

There is an "install" entry in the makefile, but it is only a sample.  Since
every site has its own layout and requirements, it is better to install the
Kermit files by hand.

After you have built and tested the C-Kermit program successfully, you can
discard the object (ck*.o) files, which are no longer needed.  Use "make
clean" to do this.  If you don't need the source files (ck[cuw]*.[cwh]), you
can remove them too.

You should install the C-Kermit program 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.  Example:

  mv wermit /usr/local/bin/kermit
  chmod 775 /usr/local/bin/kermit  <--  But see Section 10.

You should also install the man page, which is called ckuker.nr, in the
man page directory for local commands, such as /usr/man/manl/, renamed
appropriately, e.g. to kermit.l.

Several text files should be placed in a publicly readable directory, and the
man page should be altered, if necessary (in the FILES section), to point to
that directory.  Suggested directory names are:

  /usr/local/doc/kermit/
  /usr/local/lib/kermit/
  /usr/share/lib/kermit/

(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
  KERMITINFO

If any of these is defined, C-Kermit checks for the existence of the
ckermit2.txt file (the C-Kermit 7.0 updates documentation).  If not found,
it checks the directories listed above (both with and without the "/kermit")
plus several others to see if they contain the ckermit2.txt file.  If found,
various C-Kermit messages can refer the user to this directory.

  READ.ME
    Explanation of the following files.  You can create this file by
    clipping out the following file list.

  COPYING.TXT
    Copyright notice, permissions, and disclaimer.

  ckermit.ini
    The standard initialization file.  Users should copy this to
    their home directories and rename it to .kermrc.  (In C-Kermit 5A(190)
    and later, you can designate a single copy as the system-wide
    initialization file; details above).

  ckermod.ini
    A sample customization file.  Users should copy this file to
    their home directories, make any desired modifications (user- or
    site-specific customizations), and rename it to .mykermrc.

  ckermit.kdd
    A sample dialing directory file.

  ckermit.knd
    A sample network directory.

  ckermit.ksd
    A sample services directory.

  ckedemo.ksc
    Macro definitions from "Using C-Kermit".

  ckevt.ksc
    Command file to demonstrate special screen effects from "Using C-Kermit".

  ckepage.ksc
    A sample script for sending alphanumeric pages.

  ckurzsz.ini
    Macros for using rz and sz as external protocols.

  ckermit2.txt
    A file listing the updates, changes, and corrections made to C-Kermit
    since publication of "Using C-Kermit".

  ckcbwr.txt
    The general C-Kermit "beware" file.

  ckubwr.txt
    The UNIX-specific C-Kermit beware file.

We recommend that the C-Kermit initialization file, named ckermit.ini in the
distribution, be executed by all users, since it defines and sets up certain
important features, such as the dialing directory, services directory,
commonly-used macros, etc.  On multiuser systems, it can be put in a common
place and shared by all users, but this requires building C-Kermit from source
in a special way, which embeds the full path of common initialization file in
the program binary, described above.

Alternatively, each user can copy the ckermit.ini file into her login
directory and rename it to .kermrc.

The user's private "customization file" goes in the login directory and is
called .mykermrc.


6. INSTALLING UNIX C-KERMIT FROM DOS-FORMAT DISKETTES

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.


7. CHECKING THE RESULTS

First some quick checks for problems that can be easily corrected by
recompiling with different options:

DIRECTORY listing is garbage
  Permissions, size, and date are random garbage (but the filenames are
  correct) in a C-Kermit DIRECTORY listing.  On some platforms, the lstat()
  function is present but simply doesn't work; try adding -DNOLSTAT to CFLAGS
  and rebuild.  If that doesn't fix it, also add -DNOLINKBITS.  If it's
  still not fixed, remove -DNOLSTAT and -DNOLINKBITS and add -DNOSYMLINK.

curses
  When you make a connection with C-Kermit and transfer files using the
  fullscreen (curses) file-transfer display, and then get the C-Kermit>
  prompt back afterwards, do characters echo when you type them?  If not,
  the curses library has altered the buffering of /dev/tty.  Try rebuilding
  with KFLAGS=-DCK_NEWTERM.  If it already has -DCK_NEWTERM in CFLAGS, try
  removing it.  If this doesn't help, then rebuild with -DNONOSETBUF (yes,
  two NO's).  If none of this works (and you can't fix the code), then either
  don't use the fullscreen display, or rebuild with -DNOCURSES.

Ctrl-L or any SCREEN command crashes C-Kermit:
  Rebuild with -DNOTERMCAP

No prompt after CONNECT:
  After escaping back from CONNECT mode, does your C-Kermit> prompt
  disappear?  (Yet, typing "?" still produces a command list, etc)
  In that case, add -DCKCONINTB4CB to CFLAGS and rebuild.

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:

  a. Start C-Kermit (usually by typing "./wermit" in the directory where you
     ran the makefile).  Do you see the C-Kermit> prompt?  If not, C-Kermit
     incorrectly deduced that it was running in the background.  The test is
     in conbgt() in ckutio.c.  If you can fix it for your system, please send
     in the fix (Hint: read about "PID_T" below).  Otherwise, you can force
     C-Kermit to foreground mode by starting it with the -z command line
     option, as in "kermit -z", or giving the interactive command SET
     BACKGROUND OFF.

  b. When you type characters at the C-Kermit prompt, do they echo
     immediately?  If not, something is wrong with concb() and probably the
     other terminal mode settings routines in ckutio.c.  Be sure you have used
     the most appropriate make entry.

  c. At the C-Kermit> prompt, type "send *?".  C-Kermit should list all the
     files in the current directory.  If not, it was built for the wrong type
     of UNIX file system.  Details below.  In the meantime, try SET
     WILDCARD-EXPANSION SHELL as a workaround.

  d. CD to a directory that contains a variety of files, symlinks, and
     subdirectories and give a DIRECTORY command at the C-Kermit> prompt. Do
     the permissions, size, and date appear correct?  If not see Section 4.0.

  3. Assuming your platform supports long file names, create a file with a
     long name in your current directory, e.g.:

     % 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.

  f. Make sure that Kermit has the maximum path length right.  Just type
     SHOW FILE and see what it says about this.  If it is too short, there
     could be some problems at runtime.  To correct, look in ckcdeb.h to
     see how the symbol CKMAXPATH is set and make any needed adjustments.

  g. Send a file to your new Kermit program from a different Kermit program
     that is known to work.  Is the date/timestamp of the new file identical
     to the original?  If not, adjustments are needed in zstrdt() in
     ckufio.c.

  h. Go to another computer (Computer B) from which you can send files to
     C-Kermit.  Connect Computer B to the computer (A) where you are testing
     C-Kermit.  Then:

  i. Send a file from B to A.  Make sure it transferred OK and was created
       with the the right name.

  j. Send a file from B to A, specifying an "as-name" that is very, very
     long (longer than the maximum name length on computer A).  Check to
     make sure that the file was received OK and that its name was truncated
     to Computer A's maximum length.  If not, check the MAXNAMLEN definition
     in ckufio.c.

  k. Tell C-Kermit on Computer A to "set receive pathnames relative" and
     then send it a file from Computer B specifying an as-name that contains
     several directory segments:

       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).

  l. Repeat step k, but make each path segment in the pathname longer than
     Computer A's maximum name length.  Make sure each directory name, and
     the final filename, were truncated properly.

  m. Type Ctrl-C (or whatever your UNIX interrupt character is) at the prompt.
     Do you get "^C..." and a new prompt?  If instead, you get a core dump
     (this shouldn't happen any more) "rm core" and then rebuild with
     -DNOCCTRAP added to your CFLAGS.  If it did work, then type another
     Ctrl-C.  If this does the same thing as the first one, then Ctrl-C
     handling is OK.  Otherwise, the SIGINT signal is either not getting
     re-armed (shouldn't happen) or is being masked off after the first time
     it is caught, in which case, if your UNIX is POSIX-based, try rebuilding
     C-Kermit with -DCK_POSIX_SIG.

  n. Type Ctrl-Z (or whatever your UNIX suspend character is) to put C-Kermit
     in the background.  Did it work?  If nothing happened, then (a) your
     version of UNIX does not support job control, or (b) your version of
     C-Kermit was probably built with -DNOJC.  If your session became totally
     frozen, then you are probably running C-Kermit on a UNIX version that
     supports job control, but under a shell that doesn't.  If that's not the
     case, look in the congm() and psuspend() routines in ckutio.c and see if
     you can figure out what's wrong.  If you can't, rebuild with -DNOJC.

  o. Give a SET LINE command for a dialout device, e.g. "set line /dev/tty00".
     If you got some kind of permission or access denied message, go read
     Section 10 and then come back here.

  p. After giving a successful SET LINE command, type "show comm" to
     see the communication parameters.  Do they make sense?

  q. Type "set speed ?" and observe the list of available speeds.  Is it
       what you expected?  If not, see Section 2 of ckccfg.txt.

  r. Give a SET SPEED command to change the device's speed.  Did it work?
       (Type "show comm" again to check.)

  s. Try dialing out: SET MODEM TYPE <whatever>, SET LINE <whatever>, SET
     SPEED <whatever>, DIAL <phone-number>.  If it doesn't work, keep
     reading.  After dialing, can you REDIAL?

  t. If your version was built with TCP/IP network support, try the TELNET
     command.

  u. Transfer some files in remote mode on incoming asynchronous serial
     (direct or modem) connections, and on incoming network (telnet, rlogin,
     terminal server) connections.  If you get lots of errors, try different
     SET FLOW settings on the remote Kermit program.

  v. Establish a serial connection from C-Kermit to another computer (direct
     or dialed) and transfer some files.  If you have network support, do the
     same with a network connection.

  x. If your version was built with fullscreen file transfer display support,
     check that it works during local-mode file transfer.  Also, check
     C-Kermit's operation afterwards: is the echoing funny?  etc etc.  If
     there are problems, see Section 4.

  y. If your version was built with script programming language support,
     TAKE the ckedemo.ksc file to give it a workout.

  z. Does C-Kermit interlock correctly with UUCP-family programs (cu, tip,
     uucp, etc)?  If not, read the section DIALING OUT AND COORDINATING WITH
     UUCP below.

  A. Modem signals...  Give a SET LINE command to a serial device and then
     type the SHOW MODEM command.  If it says "Modem signals unavailable in
     this version of Kermit", then you might want to look at the ttgmdm()
     routine in ckutio.c and add the needed code -- if indeed your version of
     UNIX provides a way to get modem signals (some don't; e.g. modem signals
     are a foreign concept to POSIX, requiring politically incorrect
     workarounds).

     If it says "Modem signals unavailable", then it is likely that the API
     for getting modem signals is provided, but it doesn't actually do
     anything (e.g. ioctl(ttyfd,TIOCMGET,&x) returns EINVAL).

     In any case, it still should be able to manipulate the DTR signal.  To
     test, SET LINE <name-of-dialout-device>, SET MODEM NONE, and HANGUP.
     The DTR light should go out momentarily.  If it doesn't, see if you can
     add the needed code for your system to the tthang() routine in ckutio.c.

     If your version of Kermit has the SET FLOW RTS/CTS command, check to
     see if it works: give Kermit this command, set your modem for RTS/CTS,
     transfer some files (using big packet and window sizes) and watch the
     RTS and CTS lights on the modem.  If they go on and off (and Kermit does
     not get packet errors), then it works.  If your version of Kermit does
     not have this command, but your version of UNIX does support hardware
     flow control, take a look at the tthflow() command in ckutio.c and see
     if you can add the needed code (see the section on HARDWARE FLOW
     CONTROL below).

     (And please send back any added code to the author, so that others can
     benefit from it and it can be carried forward into future releases.)

  B. If C-Kermit starts normally and issues its prompt, echoing is normal,
     etc, but then after returning from a CONNECT session, the prompt no
     longer appears, try rebuilding with -DCKCONINTB4CB.


8. REDUCING THE SIZE OF THE EXECUTABLE PROGRAM IMAGE

  a. Many of C-Kermit's options and features can be deselected at compile
     time.  The greatest savings at the least sacrifice in functionality is
     to disable the logging of debug information by defining NODEBUG during
     compilation.  See the ckccfg.txt file for further information.

  b. Use shared libraries rather than static linking.  This is the default
     on many UNIX systems anyway.  However, executables built for dynamic
     linking with shared libraries are generally not portable away from the
     machine they were built on, so this is recommended if the binary is for
     your use only.

  c. Most UNIX systems have a "strip" command to remove symbol table
     information from an executable program image.  "man strip" for further
     information.  The same effect can be achieved by including "-s" among
     the link flags when building C-Kermit.

  d. SCO, Interactive, and some other UNIX versions have an "mcs" command.
     "mcs -d wermit" can be used to delete the contents of the ".comment"
     section from the executable program image.

  e. Many modern optimizers can be instructed to optimize for space rather
     than execution efficiency.  Check the CFLAGS in the makefile entry,
     adjust as desired.


9. UNIX VERSIONS

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 entry.  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 or later), -DBSD29 (BSD 2.9
for DEC PDP-11s).  BSD44 is BSD4.4, which is the basis of FreeBSD,
NetBSD, OpenBSD, BSDI, and others, and which contains many POSIX features.

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 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 & 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 entry.

9.1. Standards

In edits 166-167, 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.

9.1.1. POSIX

POSIX.1 defines a repertoire of system functions and header files for use by C
language programs.  Most notably, the ioctl() function is not allowed in
POSIX; all ioctl() functions have been replaced by device-specific functions
like tcsetattr(), tcsendbreak(), etc.

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 C-Kermit is built with the -DPOSIX flag, it attempts to configure itself
for a pure POSIX environment.  It defines _POSIX_SOURCE, it calls only
POSIX-defined functions, and it includes POSIX-defined header files.

If Kermit is built with -D_POSIX_SOURCE but not -DPOSIX, C-Kermit must be
built with one of the -DBSD or -DATTSV flags (or one that implies them), but
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.

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.

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:

 - There is no defined way for an application to do wildcard matching of
   filenames.  Kermit uses the inode in the directory structure, but POSIX.1
   does not include this concept.  (Later POSIX revisions include functions
   named (I think) glob() and fnmatch(), but these functions are not yet in
   Kermit, and might not be appropriate in any case.)

 - There is no POSIX mechanism for sensing or controlling modem signals,
   nor to enable RTS/CTS or other hardware flow control.

 - There is no select() for multiplexing i/o, and therefore no TCP/IP.

 - There is no way to check if characters are waiting in a communications
   device (or console) input buffer, short of trying to read them -- no
   select(), ioctl(fd,FIONREAD,blah), rdchk(), etc.  This is bad for CONNECT
   mode and bad for sliding windows.

 - No way to do a millisecond sleep (no nap(), usleep(), select(), etc).

 - There is no popen().

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
<[e-mail]>):

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. Casper's guess --
and mine -- is that you're doing this.

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.

(end quote)

9.1.2. ANSI C

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.

9.1.3. Other Standards

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, Single Unix Spec 98 (or other
number), ISO/IEC 9945-1, ISO 9899, 88Open, OS 99, 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, 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).

9.2. Library Issues

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 PC 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.

9.3. UNIX File System Peculiarities

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 entry 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 entry'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 entry.

Another problem child is <sys/file.h>.  Most UNIX C-Kermit versions need to
#include this file from within ckutio.c and ckufio.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 entry:

  -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.)

If you get compile-time complaints about data type mismatches for process-ID
related functions like getpid(), add -DPID_T=pid_t.

If you get compile-time complaints about data type mismatches for user ID
related functions like getuid(), add -DUID_T=uid_t.

If you get compile-time complaints about data type mismatches for user-ID
related functions like getgid(), add -DGID_T=gid_t.

If you get compile-time complaints about data type mismatches for getpwuid(),
add -DPWID_T=uid_t (or whatever it should be).

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.

9.4. Hardware Flow Control

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:

  a. POSIX does not support hardware flow control.

  b. RTS/CTS flow control support MIGHT be available for System V R3 and
     later if /usr/include/termiox.h exists (its successful operation also
     depends on the device driver, and the device itself, not to mention the
     cable, etc, actually supporting it).  If your SVR3-or-later UNIX system
     does have this file, add:

       -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).

  c. Search ("grep -i") through /usr/include/*.h and /usr/include/sys/*.h for
     RTS or CTS and see what turns up.  For example, in SunOS 4.x we find
     "CRTSCTS".  Figuring out how to use it is another question entirely!  In
     IBM AIX RS/6000 3.x, we have to "add" a new "line discipline" (and you
     won't find uppercase RTS or CTS symbols in the header files).

  d. NeXTSTEP and IRIX, and possibly others, support hardware flow control,
     but do not furnish an API to control it, and thus on these systems
     Kermit has no command to select it -- instead, a special device name
     must be used.  (NeXTSTEP: /dev/cufa instead of /dev/cua; IRIX:
     /dev/ttyf00)

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:

  a. See if it agrees with one of the methods already used in tthflow().
     If not, add new code, appropriately #ifdef'd.

  b. Add -DCK_RTSCTS to the compiler CFLAGS in your makefile entry or define
     this symbol within the appropriate #ifdef's in ckcdeb.h.

To illustrate the difficulties with RTS/CTS, here is a tale from Jamie Watson
<[e-mail]>, 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."

9.5. Terminal Speeds

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.

9.6. Millisecond Sleeps

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

9.7. Nondestructive Input Buffer Peeking

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

9.8. Other System-Dependent Features

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 entry'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:

  a. Linker complains that _rename is an unresolved symbol.

  b. Linking works, but Kermit's RENAME command doesn't work (which happens
     because older versions of rename() might have their arguments reversed).

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.

9.9. Terminal Interruption

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.

10. DIALING OUT AND COORDINATING WITH UUCP

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 & 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 other 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:

  - If a process does not observe the prevailing lockfile convention,
    then it can interfere with other "polite" processes.  And in fact,
    very few UNIX applications or commands handle lockfiles at all; an
    original design goal of UNIX was that "everything is a file", and
    countless utilities operate on files directly (by opening them) or
    indirectly through redirection of standard i/o, without creating or
    looking for lockfiles.

  - If a process crashes while it has the device open, the lockfile is
    left behind, preventing further processes from using the device.

  - Various versions of UNIX use different names for the lockfiles, put
    them in different directories, with different owners and groups and
    permissions, and specify their contents differently.

  - On a given platform, the lockfile conventions may change from one UNIX
    release to the next (for example, SunOS 4.0 to 4.1) or, in the case of
    Linux, across different distributions.

  - The same tty device might have more than one name, and most lockfile
    conventions don't allow for this.  Similarly for symbolic links.

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:

  - PIDs are stored in diverse formats that change with every new release
    (short, integer, long, or string in any of various formats).  If the
    reading program does not follow the same convention as the writing
    program, it can diagnose a valid PID to be invalid, and therefore not
    honor the lock.

  - PIDs recycle.  If the lockfile was created by PID 1234, which later
    crashed without removing the lockfile, and then a new process 1234 exists
    a the time the lockfile is checked, the lockfile will be improperly taken
    as valid, and access to the device denied unnecessarily.

Several techniques address the problem of multiple names for the same device:

  - Multiple lockfiles.  For example, if the user opens a device through a
    symlink, a lockfile is created for both the symlink name and the true
    name (obtained from readlink()).  However, when multiple drivers are
    installed for the same device (e.g. /dev/cua, /dev/cufa, etc), this
    approach won't work unless all applications *know* all the different
    names for the same device and make lockfiles for all of them, which is
    obviously not practical.

  - Lockfiles whose names are not based on the device name.  These
    lockfiles generally have names like LK.inode/major/minor, where
    inode, major, and minor are numbers, which will always be the same for
    any physical device, no matter what its name.  This form of lockfile is
    used in System V R4 and its derivatives, such as Solaris, UnixWare,
    etc.  If lockfiles must be used (as opposed to, say, kernel-based
    locks), this would seem to be the most effective form.

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 is not
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:

  -DLCKDIR:   Tells Kermit that the UUCP lock directory is /usr/spool/uucp/LCK.

  -DACUCNTRL: Tells Kermit to use the BSD 4.3 acucntrl() program to turn
              off getty (login) on the line before using it, and restore
              getty when done.

  -DHDBUUCP:  Include this if your system uses Honey DanBer UUCP, in which
              the lockfile directory and format are relatively standardized.

  -DLOCK_DIR=\\\"/xxx/yyy\\\": Gives the lock directory name explicitly.
              The triple quoting is necessary.  For example:
              "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.)

  -DLFDEVNO   The lockfile name uses the tty device inode and major and minor
              numbers: LK.dev.maj.min, as in Sys V R4, e.g. LK.035.044.008.

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:

  a. The given device name is a symbolic link.  The secondary link is based
     on the device's real name.

  b. On SCO: The device name is not a symbolic link, but it contains uppercase
     letters.  The primary link is based on the lowercase name; the secondary
     link is based on the name that was given.

  c. On HP-UX: The device name starts with "cu".  The primary link is based on
     the name that was given; the secondary link is based on the corresponding
     "ttyd" device, e.g. "LCK..cua0p0" and "LCK..ttyd0p0".

NOTE: symlinks are not handled in HP-UX.

Honey DanBer (HDB) UUCP, which is becoming increasingly popular, has two
characteristics:

   a. Lockfiles are kept in /usr/spool/locks/ (usually).

   b. A lockfile contains the process id (pid) in ASCII, rather than as an int.

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:

   a. "Timed out, no carrier."  This one is not related to lockfiles.  It
      means that you have SET CARRIER ON xx, where xx is the number of seconds
      to wait for carrier, and carrier did not appear within xx seconds.
      Solution: SET CARRIER AUTO or OFF.

   b. "Sorry, access to lock denied."  Kermit has been configured to use
      lockfiles, but (a) the lockfile directory is write-protected against
      you, or (b) it does not exist.  The "access to lock denied" message will
      tell you the reason.  If the directory does not exist, check to make
      sure Kermit is using the right name.  Just because version "n" of your
      UNIX used a certain lockfile directory is no gurantee that version n.1
      does not use a different one.  Workaround: ask the system administrator
      to install a symbolic link from the old name to the new name.  Other
      solutions: (see below)

   c. "Sorry, access to tty device denied."  The tty device that you specified
      in your SET LINE command is read/write protected against you.
      Solution: (see below)

   d. "Sorry, device is in use."  The tty device you have specified is
      currently being used by another user.  A prefatory message gives you
      an "ls -l" listing of the lockfile, which should show the username of
      the person who created it, plus a message "pid = nnn" to show you the
      process id of the user's program.  Solutions: try another device,
      wait until the other user is finished, ask the other user to hurry up,
      or ask the system manager for help.

   e. "Sorry, can't open connection: <reason>".  The device cannot be opened
      for some other reason, which is listed.

   f. "sh: /usr/lib/uucp/acucntrl: not found".  This means your Kermit program
      was built with the -DACUCNTRL switch, but your computer system does not
      have the BSD 4.3 acucntrl program.  Solution: install the acucntrl
      program if you have it, or rebuild Kermit without the -DACUCNTRL switch.

There are two solutions for problems (b) and (c), both of which involve
intervention by your UNIX system administrator (superuser):

   a. Have the superuser change the permission of the lockfile directory and
      to the tty devices so that everyone on the system has read/write
      permission.

        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.

   b. Have the superuser change Kermit to run setuid and/or setgid to the
      owner and/or group of the lockfile directory and the tty devices if
      necessary), typically uucp (see next section), but NOT root.  Example:

    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).

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:

   a. If there may be more than one person running Kermit at the same time,
      competing for the same tty device, then create a special lockfile
      directory just for Kermit, for example, /usr/spool/kermit, and make sure
      you have read/write access to it.  Then add the following to your
      makefile entry CFLAGS, as shown earlier:

           -DLOCK_DIR=\\\"/usr/spool/kermit\\\"

   b. If you are the only user on your workstation, and no other processes will
      ever be competing with Kermit for the dialout tty device, then add
      -DNOUUCP to your makefile entry's CFLAGS and rebuild Kermit.

11. RUNNING UNIX C-KERMIT SETUID OR SETGID

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 &
forth between real & 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 entry.

  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 of serial devices.
(Well, perhaps not so simple when bidirectionality must also be a goal -- but
then other OS's like VMS solved this problem 20 years ago.)

12. CONFIGURING UNIX WORKSTATIONS

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 .kermrc.

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 entry:

-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.

13. BIZARRE BEHAVIOR AT RUNTIME

See the beware file, ckubwr.txt, for hints about runtime misbehavior.
This section lists some runtime problems that can be cured by rebuilding
C-Kermit.

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 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.

14. CRASHES AND CORE DUMPS

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.


15. SYSLOGGING

"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 iksd.txt Section 4.2 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
ckermit2.txt for a detailed description of the connection log.


16. SECURITY OPTIONS

C-Kermit 6.1 and later may be built with Kerberos(TM) and/or SRP(TM) (Secure
Remote Password) capabilities.  These require external libraries that are
restricted from export by USA law.  See the security.txt file for details.

Sample makefile entries are provided for Linux:

  linux:               Regular Linux C-Kermit
  linux+krb5:          Linux C-Kermit with Kerberos V support
  linux+krb5+krb4:     Linux C-Kermit with Kerberos IV and V support
  linux+srp:           Linux C-Kermit with SRP
  linux+srp+no-des:    Linux C-Kermit with SRP but no DES
  linux+srp-export:    Linux C-Kermit with SRP, exportable
  linux+srp+pam:       Linux C-Kermit with SRP with PAM authentication
  linux+krb5+krb4+srp: Linux C-Kermit with Kerberos IV and V support + SRP

and so on.  Similarly for other platforms like Solaris, AIX, etc.  Others
can be added modeled on the ones in the makefile.

(End of ckuins.txt)