1GKERMIT(1C) GKERMIT(1C)
2
6 gkermit - G-Kermit (GNU Kermit) 1.00 file transfer software.
7
9 gkermit [ options ] -s file(s) Send files
10 gkermit [ options ] -g file(s) Get files
11 gkermit [ options ] -r Receive files
12
14 G-Kermit is a UNIX program for transferring files using the Kermit proto‐
15 col. G-Kermit is a product of Kermit Project at Columbia University. It
16 is free software under the GNU Public License. See the COPYING file for
17 details.
18 INVOKING G-KERMIT
20 The G-Kermit binary is called "gkermit". It should be stored someplace
21 in your UNIX PATH; normally it is available as /usr/local/bin/gkermit.
22 To run G-Kermit, just type "gkermit" followed by command-line options
23 that tell it what to do. If no options are given, it prints a usage mes‐
24 sage listing the available options.
25 If an option takes an argument, the argument is required; if an option
27 does not take an argument, no argument may be given (exception: -d). The
28 action options are -r, -s, and -g. Only one action option may be given.
29 If no action options are given, G-Kermit does nothing (except possibly to
30 print its usage message or create a debug.log file). Here are some exam‐
31 ples ("$ " is the shell prompt):
32 $ gkermit -s hello.c <-- Send the hello.c file
34 $ gkermit -s hello.* <-- Send all hello.* files
35 $ gkermit -r <-- Wait to receive files
36 $ gkermit -g hello.c <-- Get hello.c file
37 $ gkermit -g hello.\* <-- Get all hello.* files
38 Options that do not take arguments can be "bundled" with other options.
40 An option that takes an argument must always be followed by a space and
41 then its argument(s). Examples:
42 $ gkermit -is hello.o <-- Send hello.o in binary mode
44 $ gkermit -dr <-- Receive with debugging
45 COMMAND-LINE OPTIONS
48 -r RECEIVE. Wait for incoming files.
49 -s fn SEND. Send file(s) specified by fn.
50 -g fn GET. Get specified file(s) from server.
51 -a fn AS-NAME. Alternative name for file.
52 -i IMAGE. Binary-mode transfer (default).
53 -T TEXT. Text-mode transfer.
54 -P PATH (filename) conversion disabled.
55 -w WRITEOVER when filenames collide.
56 -K KEEP incompletely received files.
57 -p x PARITY. x = e,o,m,s,n; default = n(one).
58 -e n PACKET LENGTH. n = 40-9000; default=4000.
59 -b n TIMEOUT. Per-packet timeout, seconds.
60 -x XON/XOFF. Set Xon/Xoff in the tty driver.
61 --x Unset Xon/Xoff in the tty driver.
62 -S STREAMING disabled.
63 -X EXTERNAL. G-Kermit is an external protocol.
64 -q QUIET. Suppress messages.
65 -d DEBUG. Write debugging info to ./debug.log.
66 -d fn DEBUG. Write debugging info to given file.
67 -h HELP. Display brief usage message.
68 You may supply options to G-Kermit on the command line or through the
70 GKERMIT environment variable, which can contain any valid gkermit com‐
71 mand-line options. These are processed before the actual command-line
72 options and so can be overridden by them. Example for bash or ksh, which
73 you can put in your profile if you want to always keep incomplete files,
74 suppress streaming, suppress messages, and use Space parity:
75 export GKERMIT="-K -S -q -p s"
77 MECHANICS OF FILE TRANSFER
79 To transfer files with G-Kermit you must be connected through a terminal
80 emulator to the UNIX system where G-Kermit is running, meaning you are
81 online to UNIX and have access to the shell prompt (or to a menu that has
82 an option to invoke G-Kermit). The connection can be serial (direct or
83 dialed) or network (Telnet, Rlogin, X.25, etc).
84 When you tell G-Kermit to SEND a file (or files), e.g. with:
86 $ gkermit -Ts oofa.txt
88 it pauses for a second and then sends its first packet. What happens
90 next depends on the capabilities of your terminal emulator:
91 · If your emulator supports Kermit "autodownloads" then it
93 receives the file automatically and puts you back in the termi‐
94 nal screen when done.
95 · Otherwise, you'll need to take whatever action is required by
97 your emulator to get its attention: a mouse action, a keystroke
98 like Alt-x, or a character sequence like Ctrl-\ or Ctrl-] fol‐
99 lowed by the letter "c" (this is called "escaping back") and
100 then tell it to receive the file. When the transfer is com‐
101 plete, you must instruct your emulator to go back to its termi‐
102 nal screen.
103 During file transfer, most terminal emulators put up some kind of running
105 display of the file transfer progress.
106 When you tell G-Kermit to RECEIVE (with "gkermit -r"), this requires you
108 to escape back to your terminal emulator and instruct it to send the
109 desired file(s).
110 If your terminal emulator supports Kermit autodownloads AND Kermit server
112 mode, then you can use GET ("gkermit -g files...") rather than RECEIVE
113 ("gkermit -r"), and the rest happens automatically, as when G-Kermit is
114 sending.
115 INTERRUPTING FILE TRANSFER
117 G-Kermit supports file and group interruption. The method for interrupt‐
118 ing a transfer depends on your terminal emulator. For example, while the
119 file-transfer display is active, you might type the letter 'x' to cancel
120 the current file and go on to the next one (if any), and the letter 'z'
121 to cancel the group. Or there might be buttons you can click with your
122 mouse.
123 When G-Kermit is in packet mode and your terminal emulator is in its ter‐
125 minal screen, you can also type three (3) Ctrl-C characters in a row to
126 make G-Kermit exit and restore the normal terminal modes.
127 TEXT AND BINARY TRANSFER MODE
129 When sending files in binary mode, G-Kermit sends every byte exactly as
130 it is stored on the disk. This mode is appropriate for program binaries,
131 graphics files, tar archives, compressed files, etc, and is G-Kermit's
132 default file transfer mode when sending. When receiving files in binary
133 mode, G-Kermit simply copies each byte to disk. (Obviously the bytes are
134 encoded for transmission, but the encoding and decoding procedures give a
135 replica of the original file after transfer.)
136 When sending files in text mode, G-Kermit converts the record format to
138 the common one that is defined for the Kermit protocol, namely lines ter‐
139 minated by carriage return and linefeed (CRLF); the receiver converts the
140 CRLFs to whatever line-end or record-format convention is used on its
141 platform. When receiving files in text mode, G-Kermit simply strips car‐
142 riage returns, leaving only a linefeed at the end of each line, which is
143 the UNIX convention.
144 When receiving files, the sender's transfer mode (text or binary) predom‐
146 inates if the sender gives this information to G-Kermit in a Kermit File
147 Attribute packet, which of course depends on whether your terminal emula‐
148 tor's Kermit protocol has this feature. Otherwise, if you gave a -i or
149 -T option on the gkermit command line, the corresponding mode is used;
150 otherwise the default mode (binary) is used.
151 Furthermore, when either sending or receiving, G-Kermit and your terminal
153 emulator's Kermit can inform each other of their OS type (UNIX in G-Ker‐
154 mit's case). If your emulator supports this capability, which is called
155 "automatic peer recognition", and it tells G-Kermit that its platform is
156 also UNIX, G-Kermit and the emulator's Kermit automatically switch into
157 binary mode, since no record-format conversion is necessary in this case.
158 Automatic peer recognition is disabled automatically if you include the
159 -i (image) or -T (text) option.
160 When sending, G-Kermit sends all files in the same mode, text or binary.
162 There is no automatic per-file mode switching. When receiving, however,
163 per-file switching occurs automatically based on the incoming Attribute
164 packets, if any (explained below), that accompany each file.
165 PATHNAMES
167 When SENDING a file, G-Kermit obtains the filenames from the command
168 line. It depends on the shell to expand metacharacters (wildcards and
169 tilde).
170 G-Kermit uses the full pathname given to find and open the file, but then
172 strips the pathname before sending the name to the receiver. For exam‐
173 ple:
174 $ gkermit -s /etc/hosts
176 results in the receiver getting a file called "HOSTS" or "hosts" (the
178 directory part, "/etc/", is stripped).
179 However, if a pathname is included in the -a option, the directory part
181 is not stripped:
182 $ gkermit -s /etc/hosts -a /tmp/hosts
184 This example sends the /etc/hosts file but tells the receiver that its
186 name is "/tmp/hosts". What the receiver does with the pathname is, of
187 course, up to the receiver, which might have various options for dealing
188 with incoming pathnames.
189 When RECEIVING a file, G-Kermit does NOT strip the pathname. If the
191 incoming filename includes a path, G-Kermit tries to store the file in
192 the specified place. If the path does not exist, the transfer fails.
193 The incoming pathname can, of course, be overridden with the -a option.
194 FILENAME CONVERSION
196 When sending a file, G-Kermit normally converts outbound filenames to
197 common form: uppercase, no more than one period, and no funny characters.
198 So, for example, gkermit.tar.gz would be sent as GKERMIT_TAR.GZ.
199 When receiving a file, if the name is all uppercase, G-Kermit converts it
201 to all lowercase. If the name contains any lowercase letters, G-Kermit
202 leaves the name alone.
203 If the automatic peer recognition feature is available in the terminal
205 emulator, and G-Kermit recognizes the emulator's platform as UNIX, G-Ker‐
206 mit automatically disables filename conversion and sends and accepts
207 filenames literally.
208 You can force literal filenames by including the -P option on the command
210 line.
211 FILENAME COLLISIONS
213 When G-Kermit receives a file whose name is the same as that of an exist‐
214 ing file, G-Kermit "backs up" the existing file by adding a unique suffix
215 to its name. The suffix is ".~n~", where n is a number. This kind of
216 backup suffix is compatible with GNU EMACS and various other popular
217 applications.
218 To defeat the backup feature and have incoming files overwrite existing
220 files of the same name, include the -w (writeover) option on the command
221 line.
222
224 G-Kermit resturns an exit status code of 0 if all actions succeeded and 1
225 if any actions failed.
226
228 G-Kermit is designed to be small, portable, and stable, and is intended
229 for use only on the "far end" of a connection; it does not make connec‐
230 tions itself, although it can be used as an external protocol by other
231 programs that do make connections. To keep it small and stable, it does
232 not include sliding windows, a command or scripting language or charac‐
233 ter-set translation. To keep it portable and stable, it avoids use of
234 system services that are not standardized across all UNIX varieties and
235 therefore, in particular, does not support file timestamps, internal
236 wildcard expansion, and other features that are not implemented consis‐
237 tently (or at all) across all UNIXes.
238
240 A GKERMIT environment variable may be defined (for example in your shell
241 profile) to include G-Kermit command-line options; these are processed by
242 G-Kermit before any options that are specified on the command line, and
243 therefore are overriden by command-line options.
244
246 If an error occurs during file transfer G-Kermit sends an error packet to
247 your terminal emulator to cancel the transfer; an appropriate error mes‐
248 sage should be displayed on your screen.
249
251 File transfers can fail for a number of reasons:
252 · Lack of read access to a source file.
254 · Lack of write access to a target directory.
255 · Lack of adequate flow control.
256 · Use of streaming on an unreliable connection.
257 · Excessive unprefixing of control characters.
258 · Sending bare 8-bit data on a 7-bit connection.
259 · Packets too long for receiver's buffers.
260 · Timeout interval too short for connection.
261 and many others; these are covered in the references.
263
265 The Kermit protocol is specified in "Kermit, A File Transfer Protocol" by
266 Frank da Cruz, Digital Press (1987). A correctness proof of the Kermit
267 protocol appears in "Specification and Validation Methods", edited by
268 Egon Boerger, Oxford University Press (1995). "Using C-Kermit" by Frank
269 da Cruz and Christine M. Gianone, Digital Press (1997, or later edition)
270 explains many of the terms and techniques referenced here in case you are
271 not familiar with them, and also includes tutorials on data communica‐
272 tions, extensive troubleshooting and performance tips, etc. Various
273 other books on Kermit are available from Digital Press. Online resources
274 include:
275 Web: http://www.columbia.edu/kermit/
277 FTP: ftp://kermit.columbia.edu/kermit/g/
278 News: comp.protocols.kermit.misc
279 Email: kermit-support@columbia.edu
280 Also see the README file distributed with G-Kermit for further detail.
282 It can also be found at ftp://kermit.columbia.edu/kermit/g/README.
283
285 The speed of a file transfer depends not only on the speed of the two
286 computers involved and the characteristics of the connection, but also on
287 the capabilities and configuration of the two Kermit programs. Kermit is
288 a fast and reliable protocol, but not all implementations of it are nec‐
289 essarily fast or reliable.
290 Nonstreaming transfers on a TCP/IP connection might be inordinately slow
292 if one or both of the TCP/IP stacks uses the Nagle or Delayed ACK tricks.
293 Streaming is used automatically if the other Kermit supports it.
294 When receiving files in text mode, G-Kermit strips all carriage returns,
296 even if they aren't followed by linefeed.
297 A backups files are not guaranteed to have the highest number in their
299 backup suffix.
300
302 Frank da Cruz, the Kermit Project, Columbia University, New York City,
303 December 1999.
304UNIX G-Kermit 25 Dec 1999 GKERMIT(1C)