readme

使用Kermit协议传输文件的程序

G-Kermit  --  GNU Kermit                                          -*- text -*-

Version 1.00 : 25 December 1999

Author:
  Frank da Cruz
  The Kermit Project
  Columbia University
  612 West 115th Street
  New York NY 10025-7799  USA
  [e-mail]


CONTENTS...

   1. OVERVIEW
   2. INVOKING G-KERMIT
   3. COMMAND-LINE OPTIONS
   4. THE MECHANICS OF FILE TRANSFER
   5. INTERRUPTING FILE TRANSFER
   6. TEXT AND BINARY TRANSFER MODE
   7. PATHNAMES
   8. FILENAME CONVERSION
   9. FILENAME COLLISIONS
  10. KERMIT PROTOCOL DETAILS
  11. PROBLEMS, BUGS, ERRORS
  12. BUILDING G-KERMIT
  13. INSTALLING G-KERMIT
  14. DESIGN AND IMPLEMENTATION NOTES


1. OVERVIEW

G-Kermit is a Unix program for uploading and downloading files with the
Kermit protocol.  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.

  This software is OSI Certified Open Source Software.
  OSI Certified is a certification mark of the Open Source Initiative.

G-Kermit is:
 . Fast
 . Small
 . Portable
 . Easy to use
 . Interoperable
 . Low-maintenance
 . Stable and reliable

Features include:
 . Text and binary file transfer on both 7-bit and 8-bit connections
 . Files can be transferred singly or in groups
 . Automatic startup configuration via GKERMIT environment variable
 . Configurability as an external protocol

Kermit protocol features include:
 . Automatic peer recognition
 . Streaming on reliable connections
 . Selectable packet length, 40 to 9000 bytes (4000 default)
 . Single shifts for 8-bit data on 7-bit connections
 . Control-character prefixing for control-character transparency
 . Control-character unprefixing for increased speed (incoming only)
 . Compression of repeated bytes
 . Per-file and batch cancellation

Features selectable on command line:
 . Text or binary mode transfer
 . Filename conversion on/off
 . Filename collision backup versus overwrite
 . Keep or discard incompletely received files
 . Packet length
 . Packet timeout
 . Flow control
 . Parity
 . Streaming
 . Messages
 . Debugging

Features not included (see Section 14):
 . Making connections
 . Character-set translation
 . Interactive commands and scripting
 . File date-time stamps


2. INVOKING G-KERMIT

G-Kermit is always on the "far end" of a connection, on a Unix system that
you have made a connection to from a terminal emulator by dialup, network,
or direct serial.  If you have a direct or dialup serial connection into
Unix, use the "stty -a" or "stty all" command to see if your Unix terminal
driver is conditioned for the appropriate kind of flow control; if it isn't,
very few applications (including gkermit) will work well, or at all.  The
command for setting terminal flow control varies from platform to platform,
but it is usually something like this:

 $ stty crtscts

(where "$ " is the shell prompt) for RTS/CTS hardware flow control, or:

 $ stty ixon ixoff

for Xon/Xoff "software" flow control.  When you have a network connection,
flow control is usually nothing to worry about, since the network protocol
(TCP or X.25) takes care of it automatically, but on certain platforms (such
as HP-UX) the TCP/IP Telnet or Rlogin server uses this for flow control
between itself and the underlying pseudoterminal in which your session runs,
so Xon/Xoff might be required for these sessions too.

The G-Kermit binary is called "gkermit".  It should be stored someplace in
your Unix PATH, such as /usr/local/bin/gkermit or somewhere in the /opt tree
on System V R4.  To run G-Kermit, just type "gkermit" followed by command-
line options that tell it what to do.  If no options are given, G-Kermit
prints a usage message listing the available options:

 G-Kermit CU-1.00, Columbia University, 1999-12-25: POSIX.
 Usage:  gkermit [ options ]
 Options:
  -r      Receive files
  -s fn   Send files
  -g fn   Get files from server
  -a fn   As-name for single file
  -i      Image (binary) mode transfer
  -T      Text mode transfer
  -P      Path/filename conversion disabled
  -w      Write over existing files with same name
  -K      Keep incompletely received files
  -p x    Parity: x = o[dd],e[ven],m[ark],s[pace],n[one]
  -e n    Receive packet-length (40-9000)
  -b n    Timeout (sec, 0 = none)
  -x      Force Xon/Xoff (--x = Don't force Xon/Xoff)
  -S      Disable streaming
  -X      External protocol
  -q      Quiet (suppress messages)
  -d [fn] Debug to ./debug.log [or specified file]
  -h      Help (this message)
 More info: http://www.columbia.edu/kermit/ <[e-mail]>

If an option takes an argument, the argument is required; if an option does
not take an argument, no argument may be given (exceptions: -d may or may
not take an argument; -s can take 1 or more arguments).

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
printing its usage message or creating a debug.log file).  Here are some
examples (in which "$ " is the shell prompt):

  $ gkermit -s hello.c       <-- Sends the hello.c file.
  $ gkermit -s hello.*       <-- Sends all hello.* files.
  $ gkermit -r               <-- Waits for you to send a file to it.
  $ gkermit -g hello.c       <-- Gets the hello.c file from your computer.
  $ gkermit -g \*.c          <-- Gets all *.c files from your computer.

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      <-- Sends hello.o in binary mode.
  $ gkermit -dSr             <-- Receives with debugging and no streaming.

G-Kermit's exit status is 0 if all operations succeeded and 1 if there were
any failures.  If a group of files was transferred, the exit status is 1
if one or more files was not successfully transferred and 0 if all of them
were transferred successfully.


3. COMMAND-LINE OPTIONS

  -r     RECEIVE: This option tells G-Kermit to receive a file or files;
         that is, to passively wait for you to send files from your
         terminal emulator.

  -s fn  SEND: This tells G-Kermit to send the file or files specified by
         fn, which can be a filename, a regular expression, or a list of
         filenames and/or regular expressions (wildcards).  Regular
         expressions are interpreted and expanded by your shell into the
         list of names of files that is given to G-Kermit.  For example
         "*.c" expands to a list of all files in the current directory
         whose names end with ".c".

  -g fn  GET: This option tells G-Kermit to get a file (or files) from a
         Kermit server.  It is useful only when your terminal emulator
         supports the Kermit autodownload feature AND it includes a Kermit
         server mode.  It is equivalent to "gkermit -r", escaping back,
         telling your terminal emulator to send the given files, and then
         reconnecting to Unix.

  -a fn  AS-NAME: When used with -s, this option tells G-Kermit to send
         the file whose name is given as the first -s argument under the
         name fn.  For example, "gkermit -s game -a work" sends the file
         called "game" under the name "work", so the receiver will think
         its name is "work".  When given with the -r or -g command, the
         incoming file (or the first incoming file if there is more than
         one) is stored under the name fn.  In all cases, the given name
         is used as-is; it is not converted.

  -i     IMAGE (binary) mode transfer.  When used with -s, tells G-Kermit
         to send in binary mode.  When used with -r, tells G-Kermit to
         receive in binary mode if the file sender does not specify the
         transfer mode (text or binary).  When used with -g, tells
         G-Kermit to ask your terminal emulator's Kermit to send the given
         file in binary mode.  See Section 6 for details.

  -T     TEXT mode transfer (note uppercase T).  When used with -s, tells
         G-Kermit to send in text mode.  When used with -r, tells G-Kermit
         to receive in text mode if the file sender does not specify the
         transfer mode (text or binary).  When used with -g, tells G-Kermit
         to ask your emulator's Kermit to send the given file in text mode.
         See Section 6 for details.

  -P     PATH (filename) conversion disabled (note uppercase P).
         Normally when sending files, G-Kermit converts filenames to a
         form that should be acceptable to non-Unix platforms, primarily
         changing lowercase letters to uppercase, ensuring there is no
         more than one period, and replacing any "funny" characters by X
         or underscore (explained in Section 8).

  -w     WRITEOVER.  When receiving, and an incoming file has the same
         name as an existing file, write over the existing file.  By
         default G-Kermit backs up the existing file by adding a suffix
         to its name (see Section 9).

  -K     KEEP incompletely received files.  Normally when receiving files,
         and a file transfer is interrupted, G-Kermit discards the
         partially received file so you won't think you have the whole
         file.  Include -K on the command line to tell G-Kermit to keep
         partially received files, e.g. "gkermit -Kr".

  -p x   PARITY: Use the given kind of parity, where x can be 'n' for
         None (which is the default, for use on 8-bit-clean connections);
         's' for Space, 'e' for Even, 'o' for Odd, and 'm' for Mark.  's'
         might be needed on certain Telnet connections; 'e', 'o', and 'm'
         are only for serial connections; don't try them on TCP/IP
         connections.

  -e n   PACKET LENGTH: Receive packet-length, where n can be any number
         between 40 and 9000.  The default length on most platforms is
         4000.  Use this option to specify a different length; usually
         this would be necessary only if transfers fail using the default
         length due to some kind of buffering problem in the host or along
         the communication path.  Example: "gkermit -e 240 -r".

  -b n   TIMEOUT (sec, 0 = none).  Specify the number of seconds to wait
         for a packet before timing out and retransmitting.  By default,
         G-Kermit uses whatever timeout interval your terminal emulator's
         Kermit asks it to use.  No need to change this unless the timeout
         action causes problems.

  -x     XON/XOFF.  Force Xon/Xoff flow control in the Unix terminal
         driver.  Try this if uploads fail without it.  But don't use it
         if you don't need to; on some platforms or connections it hurts
         rather than helps.

  --x    Don't force Xon/Xoff; for use when G-Kermit was built with the
         SETXONXOFF compile-time option (Section 12), to override the
         automatic setting of Xon/Xoff in case it interferes with file
         transfers.

  -S     STREAMING disabled.  Streaming is a high-performance option to
         be used on reliable connections, such as in Telnet or Rlogin
         sessions.  It is used if your terminal emulator's Kermit requests
         it.  Use the -S option (note: uppercase S) to suppress this
         feature in case it causes trouble.  Details in Section 10.

  -X     EXTERNAL PROTOCOL.  Include this option when invoking G-Kermit
         from another program that redirects G-Kermit's standard i/o,
         e.g. over a connection to another computer.  If you omit this
         switch when using G-Kermit as an external protocol to another
         communications program, G-Kermit is likely to perform illegal
         operations and exit prematurely.  If you include this switch
         when G-Kermit is NOT an external protocol to another program,
         file transfers will fail.  G-Kermit has no way of determining
         automatically whether it is being used as an external protocol.

  -q     QUIET.  Suppresses messages.

  -d     DEBUG.  Use this for troubleshooting.  It creates a file called
         debug.log in your current directory, to be used in conjunction
         with the source code, or sent to the Kermit support address for
         analysis.  More about this in Section 11.

  -d fn  DEBUG to specified file (rather than default ./debug.log).

  -h     HELP: Displays the usage message shown above.

You may supply options to G-Kermit on the command line or through the
GKERMIT environment variable, which can contain any valid gkermit
command-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"

G-Kermit's options are compatible with C-Kermit's, with the following
exceptions:

  -P (available only in C-Kermit 7.0 and later)
  -K (currently not used in C-Kermit)
  -b (used in C-Kermit for serial device speed)
  -S (used in C-Kermit to force an interactive command prompt)
  -x (used in C-Kermit to start server mode)
 --x (currently not used in C-Kermit)
  -X (currently not used in C-Kermit)


4. THE 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 installed, meaning you are
online to Unix and have access to the shell prompt (or to some menu that has
an option to invoke G-Kermit), and your terminal emulator must support the
Kermit file transfer protocol.  The connection can be serial (direct or
dialed) or network (Telnet, Rlogin, X.25, etc).

4.1. Sending Files

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 terminal 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-] followed by the letter
   "c" (this is called "escaping back") and then tell it to receive the
   file.  When the transfer is complete, you might have to instruct your
   emulator to go back to its terminal screen.

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

4.2. Receiving Files

When you tell G-Kermit to RECEIVE, this requires you to escape back to your
terminal emulator and instruct it to send the desired file(s).  Autodownload