gkermit  -  G-Kermit (GNU Kermit) 1.00 file transfer soft­
       ware.


SYNOPSIS

       gkermit [ options ] -s file(s)    Send files
       gkermit [ options ] -g file(s)    Get files
       gkermit [ options ] -r            Receive files


DESCRIPTION

       G-Kermit is a UNIX program for transferring files using the Kermit proto­
       col.  G-Kermit is a product of Kermit Project at Columbia University.  It
       is free software under the GNU Public License.  See the COPYING file  for
       details.

   INVOKING G-KERMIT
       The  G-Kermit  binary is called "gkermit".  It should be stored someplace
       in your UNIX PATH; normally it is  available  as  /usr/local/bin/gkermit.
       To  run  G-Kermit,  just  type "gkermit" followed by command-line options
       that tell it what to do.  If no options are given, it prints a usage mes­
       sage listing the available options.

       If  an  option  takes an argument, the argument is required; if an option
       does not take an argument, no argument may be given (exception: -d).  The
       action  options are -r, -s, and -g.  Only one action option may be given.
       If no action options are given, G-Kermit does nothing (except possibly to
       print its usage message or create a debug.log file).  Here are some exam­
       ples ("$ " is the shell prompt):

         $ gkermit -s hello.c   <-- Send the hello.c file
         $ gkermit -s hello.*   <-- Send all hello.* files
         $ gkermit -r           <-- Wait to receive files
         $ gkermit -g hello.c   <-- Get hello.c file
         $ gkermit -g hello.\*  <-- Get all hello.* files

       Options that do not take arguments can be "bundled" with  other  options.
       An  option  that takes an argument must always be followed by a space and
       then its argument(s).  Examples:

         $ gkermit -is hello.o  <-- Send hello.o in binary mode
         $ gkermit -dr          <-- Receive with debugging

   COMMAND-LINE OPTIONS
         -r      RECEIVE.  Wait for incoming files.
         -s fn   SEND.  Send file(s) specified by fn.
         -g fn   GET.  Get specified file(s) from server.
         -a fn   AS-NAME.  Alternative name for file.
         -i      IMAGE.  Binary-mode transfer (default).
         -T      TEXT. Text-mode transfer.
         -P      PATH (filename) conversion disabled.
         -w      WRITEOVER when filenames collide.

         -p x    PARITY. x = e,o,m,s,n; default = n(one).
         -e n    PACKET LENGTH.  n = 40-9000; default=4000.
         -b n    TIMEOUT.  Per-packet timeout, seconds.
         -x      XON/XOFF.  Set Xon/Xoff in the tty driver.
         --x     Unset Xon/Xoff in the tty driver.
         -S      STREAMING disabled.
         -X      EXTERNAL.  G-Kermit is an external protocol.
         -q      QUIET.  Suppress messages.
         -d      DEBUG.  Write debugging info to ./debug.log.
         -d fn   DEBUG.  Write debugging info to given file.
         -h      HELP.  Display brief usage message.

       You may supply options to G-Kermit on the command  line  or  through  the
       GKERMIT  environment  variable,  which can contain any valid gkermit com­
       mand-line options.  These are processed before  the  actual  command-line
       options and so can be overridden by them.  Example for bash or ksh, which
       you can put in your profile if you want to always keep incomplete  files,
       suppress streaming, suppress messages, and use Space parity:

         export GKERMIT="-K -S -q -p s"

   MECHANICS OF FILE TRANSFER
       To  transfer files with G-Kermit you must be connected through a terminal
       emulator to the UNIX system where G-Kermit is running,  meaning  you  are
       online to UNIX and have access to the shell prompt (or to a menu that has
       an option to invoke G-Kermit).  The connection can be serial  (direct  or
       dialed) or network (Telnet, Rlogin, X.25, etc).

       When you tell G-Kermit to SEND a file (or files), e.g. with:

         $ gkermit -Ts oofa.txt

       it  pauses  for  a  second and then sends its first packet.  What happens
       next depends on the capabilities of your terminal emulator:

          · If  your  emulator  supports  Kermit  "autodownloads"  then  it
            receives the file automatically and puts you back in the termi­
            nal screen when done.

          · Otherwise, you'll need to take whatever action is  required  by
            your emulator to get its attention: a mouse action, a keystroke
            like Alt-x, or a character sequence like Ctrl-\ or Ctrl-]  fol­
            lowed  by  the  letter "c" (this is called "escaping back") and
            then tell it to receive the file.  When the  transfer  is  com­
            plete, you must instruct your emulator to go back to its termi­
            nal screen.

       During file transfer, most terminal emulators put up some kind of running
       display of the file transfer progress.

       When  you tell G-Kermit to RECEIVE (with "gkermit -r"), this requires you
       to escape back to your terminal emulator and  instruct  it  to  send  the


       If your terminal emulator supports Kermit autodownloads AND Kermit server
       mode, then you can use GET ("gkermit -g files...")  rather  than  RECEIVE
       ("gkermit  -r"),  and the rest happens automatically, as when G-Kermit is
       sending.

   INTERRUPTING FILE TRANSFER
       G-Kermit supports file and group interruption.  The method for interrupt­
       ing a transfer depends on your terminal emulator.  For example, while the
       file-transfer display is active, you might type the letter 'x' to  cancel
       the  current  file and go on to the next one (if any), and the letter 'z'
       to cancel the group.  Or there might be buttons you can click  with  your
       mouse.

       When G-Kermit is in packet mode and your terminal emulator is in its ter­
       minal screen, you can also type three (3) Ctrl-C characters in a  row  to
       make G-Kermit exit and restore the normal terminal modes.

   TEXT AND BINARY TRANSFER MODE
       When  sending  files in binary mode, G-Kermit sends every byte exactly as
       it is stored on the disk.  This mode is appropriate for program binaries,
       graphics  files,  tar  archives, compressed files, etc, and is G-Kermit's
       default file transfer mode when sending.  When receiving files in  binary
       mode, G-Kermit simply copies each byte to disk.  (Obviously the bytes are
       encoded for transmission, but the encoding and decoding procedures give a
       replica of the original file after transfer.)

       When  sending  files in text mode, G-Kermit converts the record format to
       the common one that is defined for the Kermit protocol, namely lines ter­
       minated by carriage return and linefeed (CRLF); the receiver converts the
       CRLFs to whatever line-end or record-format convention  is  used  on  its
       platform.  When receiving files in text mode, G-Kermit simply strips car­
       riage returns, leaving only a linefeed at the end of each line, which  is
       the UNIX convention.

       When receiving files, the sender's transfer mode (text or binary) predom­
       inates if the sender gives this information to G-Kermit in a Kermit  File
       Attribute packet, which of course depends on whether your terminal emula­
       tor's Kermit protocol has this feature.  Otherwise, if you gave a  -i  or
       -T  option  on  the gkermit command line, the corresponding mode is used;
       otherwise the default mode (binary) is used.

       Furthermore, when either sending or receiving, G-Kermit and your terminal
       emulator's  Kermit can inform each other of their OS type (UNIX in G-Ker­
       mit's case).  If your emulator supports this capability, which is  called
       "automatic  peer recognition", and it tells G-Kermit that its platform is
       also UNIX, G-Kermit and the emulator's Kermit automatically  switch  into
       binary mode, since no record-format conversion is necessary in this case.
       Automatic peer recognition is disabled automatically if you  include  the
       -i (image) or -T (text) option.

       When  sending, G-Kermit sends all files in the same mode, text or binary.

       per-file  switching  occurs automatically based on the incoming Attribute
       packets, if any (explained below), that accompany each file.

   PATHNAMES
       When SENDING a file, G-Kermit obtains  the  filenames  from  the  command
       line.   It  depends  on the shell to expand metacharacters (wildcards and
       tilde).

       G-Kermit uses the full pathname given to find and open the file, but then
       strips  the  pathname before sending the name to the receiver.  For exam­
       ple:

         $ gkermit -s /etc/hosts

       results in the receiver getting a file called  "HOSTS"  or  "hosts"  (the
       directory part, "/etc/", is stripped).

       However,  if  a pathname is included in the -a option, the directory part
       is not stripped:

         $ gkermit -s /etc/hosts -a /tmp/hosts

       This example sends the /etc/hosts file but tells the  receiver  that  its
       name  is  "/tmp/hosts".   What the receiver does with the pathname is, of
       course, up to the receiver, which might have various options for  dealing
       with incoming pathnames.

       When  RECEIVING  a  file,  G-Kermit  does NOT strip the pathname.  If the
       incoming filename includes a path, G-Kermit tries to store  the  file  in
       the  specified  place.   If  the path does not exist, the transfer fails.
       The incoming pathname can, of course, be overridden with the -a option.

   FILENAME CONVERSION
       When sending a file, G-Kermit normally  converts  outbound  filenames  to
       common form: uppercase, no more than one period, and no funny characters.
       So, for example, gkermit.tar.gz would be sent as GKERMIT_TAR.GZ.

       When receiving a file, if the name is all uppercase, G-Kermit converts it
       to  all  lowercase.  If the name contains any lowercase letters, G-Kermit
       leaves the name alone.

       If the automatic peer recognition feature is available  in  the  terminal
       emulator, and G-Kermit recognizes the emulator's platform as UNIX, G-Ker­
       mit automatically disables filename  conversion  and  sends  and  accepts
       filenames literally.

       You can force literal filenames by including the -P option on the command
       line.

       When G-Kermit receives a file whose name is the same as that of an exist­
       ing file, G-Kermit "backs up" the existing file by adding a unique suffix
       to its name.  The suffix is ".~n~", where n is a number.   This  kind  of
       backup  suffix  is  compatible  with  GNU EMACS and various other popular
       applications.

       To defeat the backup feature and have incoming files  overwrite  existing
       files  of the same name, include the -w (writeover) option on the command
       line.


RETURN VALUES

       G-Kermit resturns an exit status code of 0 if all actions succeeded and 1
       if any actions failed.


IMPLEMENTATION NOTES

       G-Kermit  is  designed to be small, portable, and stable, and is intended
       for use only on the "far end" of a connection; it does not  make  connec­
       tions  itself,  although  it can be used as an external protocol by other
       programs that do make connections.  To keep it small and stable, it  does
       not  include  sliding windows, a command or scripting language or charac­
       ter-set translation.  To keep it portable and stable, it  avoids  use  of
       system  services  that are not standardized across all UNIX varieties and
       therefore, in particular, does  not  support  file  timestamps,  internal
       wildcard  expansion,  and other features that are not implemented consis­
       tently (or at all) across all UNIXes.


ENVIRONMENT

       A GKERMIT environment variable may be defined (for example in your  shell
       profile) to include G-Kermit command-line options; these are processed by
       G-Kermit before any options that are specified on the command  line,  and
       therefore are overriden by command-line options.


DIAGNOSTICS

       If an error occurs during file transfer G-Kermit sends an error packet to
       your terminal emulator to cancel the transfer; an appropriate error  mes­
       sage should be displayed on your screen.


ERRORS

       File transfers can fail for a number of reasons:

          · Lack of read access to a source file.
          · Lack of write access to a target directory.
          · Lack of adequate flow control.
          · Use of streaming on an unreliable connection.
          · Excessive unprefixing of control characters.
          · Sending bare 8-bit data on a 7-bit connection.
          · Packets too long for receiver's buffers.
          · Timeout interval too short for connection.



REFERENCES

       The Kermit protocol is specified in "Kermit, A File Transfer Protocol" by
       Frank da Cruz, Digital Press (1987).  A correctness proof of  the  Kermit
       protocol  appears  in  "Specification  and Validation Methods", edited by
       Egon Boerger, Oxford University Press (1995).  "Using C-Kermit" by  Frank
       da  Cruz and Christine M. Gianone, Digital Press (1997, or later edition)
       explains many of the terms and techniques referenced here in case you are
       not  familiar  with  them, and also includes tutorials on data communica­
       tions, extensive troubleshooting  and  performance  tips,  etc.   Various
       other books on Kermit are available from Digital Press.  Online resources
       include:

         Web:   http://www.columbia.edu/kermit/
         FTP:   ftp://kermit.columbia.edu/kermit/g/
         News:  comp.protocols.kermit.misc
         Email: kermit-support@columbia.edu

       Also see the README file distributed with G-Kermit  for  further  detail.
       It can also be found at ftp://kermit.columbia.edu/kermit/g/README.


BUGS

       The  speed  of  a  file transfer depends not only on the speed of the two
       computers involved and the characteristics of the connection, but also on
       the capabilities and configuration of the two Kermit programs.  Kermit is
       a fast and reliable protocol, but not all implementations of it are  nec­
       essarily fast or reliable.

       Nonstreaming  transfers on a TCP/IP connection might be inordinately slow
       if one or both of the TCP/IP stacks uses the Nagle or Delayed ACK tricks.
       Streaming is used automatically if the other Kermit supports it.

       When  receiving files in text mode, G-Kermit strips all carriage returns,
       even if they aren't followed by linefeed.

       A backups files are not guaranteed to have the highest  number  in  their
       backup suffix.


AUTHOR

       Frank  da  Cruz,  the Kermit Project, Columbia University, New York City,
       December 1999.


Man(1) output converted with man2html