1G-Kermit -- GNU Kermit -*- text -*- 2 3Version 1.00 : 25 December 1999 4 5Author: 6 Frank da Cruz 7 The Kermit Project 8 Columbia University 9 612 West 115th Street 10 New York NY 10025-7799 USA 11 fdc@columbia.edu 12 13 14CONTENTS... 15 16 1. OVERVIEW 17 2. INVOKING G-KERMIT 18 3. COMMAND-LINE OPTIONS 19 4. THE MECHANICS OF FILE TRANSFER 20 5. INTERRUPTING FILE TRANSFER 21 6. TEXT AND BINARY TRANSFER MODE 22 7. PATHNAMES 23 8. FILENAME CONVERSION 24 9. FILENAME COLLISIONS 25 10. KERMIT PROTOCOL DETAILS 26 11. PROBLEMS, BUGS, ERRORS 27 12. BUILDING G-KERMIT 28 13. INSTALLING G-KERMIT 29 14. DESIGN AND IMPLEMENTATION NOTES 30 31 321. OVERVIEW 33 34G-Kermit is a Unix program for uploading and downloading files with the 35Kermit protocol. G-Kermit is a product of Kermit Project at Columbia 36University. It is free software under the GNU Public License. See the 37COPYING file for details. 38 39G-Kermit is: 40 . Fast 41 . Small 42 . Portable 43 . Easy to use 44 . Interoperable 45 . Low-maintenance 46 . Stable and reliable 47 48Features include: 49 . Text and binary file transfer on both 7-bit and 8-bit connections 50 . Files can be transferred singly or in groups 51 . Automatic startup configuration via GKERMIT environment variable 52 . Configurability as an external protocol 53 54Kermit protocol features include: 55 . Automatic peer recognition 56 . Streaming on reliable connections 57 . Selectable packet length, 40 to 9000 bytes (4000 default) 58 . Single shifts for 8-bit data on 7-bit connections 59 . Control-character prefixing for control-character transparency 60 . Control-character unprefixing for increased speed (incoming only) 61 . Compression of repeated bytes 62 . Per-file and batch cancellation 63 64Features selectable on command line: 65 . Text or binary mode transfer 66 . Filename conversion on/off 67 . Filename collision backup versus overwrite 68 . Keep or discard incompletely received files 69 . Packet length 70 . Packet timeout 71 . Flow control 72 . Parity 73 . Streaming 74 . Messages 75 . Debugging 76 77Features not included (see Section 14): 78 . Making connections 79 . Character-set translation 80 . Interactive commands and scripting 81 . File date-time stamps 82 83 842. INVOKING G-KERMIT 85 86G-Kermit is always on the "far end" of a connection, on a Unix system that 87you have made a connection to from a terminal emulator by dialup, network, 88or direct serial. If you have a direct or dialup serial connection into 89Unix, use the "stty -a" or "stty all" command to see if your Unix terminal 90driver is conditioned for the appropriate kind of flow control; if it isn't, 91very few applications (including gkermit) will work well, or at all. The 92command for setting terminal flow control varies from platform to platform, 93but it is usually something like this: 94 95 $ stty crtscts 96 97(where "$ " is the shell prompt) for RTS/CTS hardware flow control, or: 98 99 $ stty ixon ixoff 100 101for Xon/Xoff "software" flow control. When you have a network connection, 102flow control is usually nothing to worry about, since the network protocol 103(TCP or X.25) takes care of it automatically, but on certain platforms (such 104as HP-UX) the TCP/IP Telnet or Rlogin server uses this for flow control 105between itself and the underlying pseudoterminal in which your session runs, 106so Xon/Xoff might be required for these sessions too. 107 108The G-Kermit binary is called "gkermit". It should be stored someplace in 109your Unix PATH, such as /usr/local/bin/gkermit or somewhere in the /opt tree 110on System V R4. To run G-Kermit, just type "gkermit" followed by command- 111line options that tell it what to do. If no options are given, G-Kermit 112prints a usage message listing the available options: 113 114 G-Kermit CU-1.00, Columbia University, 1999-12-25: POSIX. 115 Usage: gkermit [ options ] 116 Options: 117 -r Receive files 118 -s fn Send files 119 -g fn Get files from server 120 -a fn As-name for single file 121 -i Image (binary) mode transfer 122 -T Text mode transfer 123 -P Path/filename conversion disabled 124 -w Write over existing files with same name 125 -K Keep incompletely received files 126 -p x Parity: x = o[dd],e[ven],m[ark],s[pace],n[one] 127 -e n Receive packet-length (40-9000) 128 -b n Timeout (sec, 0 = none) 129 -x Force Xon/Xoff (--x = Don't force Xon/Xoff) 130 -S Disable streaming 131 -X External protocol 132 -q Quiet (suppress messages) 133 -d [fn] Debug to ./debug.log [or specified file] 134 -h Help (this message) 135 More info: http://www.columbia.edu/kermit/ <kermit@columbia.edu> 136 137If an option takes an argument, the argument is required; if an option does 138not take an argument, no argument may be given (exceptions: -d may or may 139not take an argument; -s can take 1 or more arguments). 140 141The action options are -r, -s, and -g. Only one action option may be given. 142If no action options are given, G-Kermit does nothing (except possibly 143printing its usage message or creating a debug.log file). Here are some 144examples (in which "$ " is the shell prompt): 145 146 $ gkermit -s hello.c <-- Sends the hello.c file. 147 $ gkermit -s hello.* <-- Sends all hello.* files. 148 $ gkermit -r <-- Waits for you to send a file to it. 149 $ gkermit -g hello.c <-- Gets the hello.c file from your computer. 150 $ gkermit -g \*.c <-- Gets all *.c files from your computer. 151 152Options that do not take arguments can be "bundled" with other options. 153An option that takes an argument must always be followed by a space and 154then its argument(s). Examples: 155 156 $ gkermit -is hello.o <-- Sends hello.o in binary mode. 157 $ gkermit -dSr <-- Receives with debugging and no streaming. 158 159G-Kermit's exit status is 0 if all operations succeeded and 1 if there were 160any failures. If a group of files was transferred, the exit status is 1 161if one or more files was not successfully transferred and 0 if all of them 162were transferred successfully. 163 164 1653. COMMAND-LINE OPTIONS 166 167 -r RECEIVE: This option tells G-Kermit to receive a file or files; 168 that is, to passively wait for you to send files from your 169 terminal emulator. 170 171 -s fn SEND: This tells G-Kermit to send the file or files specified by 172 fn, which can be a filename, a regular expression, or a list of 173 filenames and/or regular expressions (wildcards). Regular 174 expressions are interpreted and expanded by your shell into the 175 list of names of files that is given to G-Kermit. For example 176 "*.c" expands to a list of all files in the current directory 177 whose names end with ".c". 178 179 -g fn GET: This option tells G-Kermit to get a file (or files) from a 180 Kermit server. It is useful only when your terminal emulator 181 supports the Kermit autodownload feature AND it includes a Kermit 182 server mode. It is equivalent to "gkermit -r", escaping back, 183 telling your terminal emulator to send the given files, and then 184 reconnecting to Unix. 185 186 -a fn AS-NAME: When used with -s, this option tells G-Kermit to send 187 the file whose name is given as the first -s argument under the 188 name fn. For example, "gkermit -s game -a work" sends the file 189 called "game" under the name "work", so the receiver will think 190 its name is "work". When given with the -r or -g command, the 191 incoming file (or the first incoming file if there is more than 192 one) is stored under the name fn. In all cases, the given name 193 is used as-is; it is not converted. 194 195 -i IMAGE (binary) mode transfer. When used with -s, tells G-Kermit 196 to send in binary mode. When used with -r, tells G-Kermit to 197 receive in binary mode if the file sender does not specify the 198 transfer mode (text or binary). When used with -g, tells 199 G-Kermit to ask your terminal emulator's Kermit to send the given 200 file in binary mode. See Section 6 for details. 201 202 -T TEXT mode transfer (note uppercase T). When used with -s, tells 203 G-Kermit to send in text mode. When used with -r, tells G-Kermit 204 to receive in text mode if the file sender does not specify the 205 transfer mode (text or binary). When used with -g, tells G-Kermit 206 to ask your emulator's Kermit to send the given file in text mode. 207 See Section 6 for details. 208 209 -P PATH (filename) conversion disabled (note uppercase P). 210 Normally when sending files, G-Kermit converts filenames to a 211 form that should be acceptable to non-Unix platforms, primarily 212 changing lowercase letters to uppercase, ensuring there is no 213 more than one period, and replacing any "funny" characters by X 214 or underscore (explained in Section 8). 215 216 -w WRITEOVER. When receiving, and an incoming file has the same 217 name as an existing file, write over the existing file. By 218 default G-Kermit backs up the existing file by adding a suffix 219 to its name (see Section 9). 220 221 -K KEEP incompletely received files. Normally when receiving files, 222 and a file transfer is interrupted, G-Kermit discards the 223 partially received file so you won't think you have the whole 224 file. Include -K on the command line to tell G-Kermit to keep 225 partially received files, e.g. "gkermit -Kr". 226 227 -p x PARITY: Use the given kind of parity, where x can be 'n' for 228 None (which is the default, for use on 8-bit-clean connections); 229 's' for Space, 'e' for Even, 'o' for Odd, and 'm' for Mark. 's' 230 might be needed on certain Telnet connections; 'e', 'o', and 'm' 231 are only for serial connections; don't try them on TCP/IP 232 connections. 233 234 -e n PACKET LENGTH: Receive packet-length, where n can be any number 235 between 40 and 9000. The default length on most platforms is 236 4000. Use this option to specify a different length; usually 237 this would be necessary only if transfers fail using the default 238 length due to some kind of buffering problem in the host or along 239 the communication path. Example: "gkermit -e 240 -r". 240 241 -b n TIMEOUT (sec, 0 = none). Specify the number of seconds to wait 242 for a packet before timing out and retransmitting. By default, 243 G-Kermit uses whatever timeout interval your terminal emulator's 244 Kermit asks it to use. No need to change this unless the timeout 245 action causes problems. 246 247 -x XON/XOFF. Force Xon/Xoff flow control in the Unix terminal 248 driver. Try this if uploads fail without it. But don't use it 249 if you don't need to; on some platforms or connections it hurts 250 rather than helps. 251 252 --x Don't force Xon/Xoff; for use when G-Kermit was built with the 253 SETXONXOFF compile-time option (Section 12), to override the 254 automatic setting of Xon/Xoff in case it interferes with file 255 transfers. 256 257 -S STREAMING disabled. Streaming is a high-performance option to 258 be used on reliable connections, such as in Telnet or Rlogin 259 sessions. It is used if your terminal emulator's Kermit requests 260 it. Use the -S option (note: uppercase S) to suppress this 261 feature in case it causes trouble. Details in Section 10. 262 263 -X EXTERNAL PROTOCOL. Include this option when invoking G-Kermit 264 from another program that redirects G-Kermit's standard i/o, 265 e.g. over a connection to another computer. If you omit this 266 switch when using G-Kermit as an external protocol to another 267 communications program, G-Kermit is likely to perform illegal 268 operations and exit prematurely. If you include this switch 269 when G-Kermit is NOT an external protocol to another program, 270 file transfers will fail. G-Kermit has no way of determining 271 automatically whether it is being used as an external protocol. 272 273 -q QUIET. Suppresses messages. 274 275 -d DEBUG. Use this for troubleshooting. It creates a file called 276 debug.log in your current directory, to be used in conjunction 277 with the source code, or sent to the Kermit support address for 278 analysis. More about this in Section 11. 279 280 -d fn DEBUG to specified file (rather than default ./debug.log). 281 282 -h HELP: Displays the usage message shown above. 283 284You may supply options to G-Kermit on the command line or through the 285GKERMIT environment variable, which can contain any valid gkermit 286command-line options. These are processed before the actual command-line 287options and so can be overridden by them. Example for bash or ksh, which 288you can put in your profile if you want to always keep incomplete files, 289suppress streaming, suppress messages, and use Space parity: 290 291 export GKERMIT="-K -S -q -p s" 292 293G-Kermit's options are compatible with C-Kermit's, with the following 294exceptions: 295 296 -P (available only in C-Kermit 7.0 and later) 297 -K (currently not used in C-Kermit) 298 -b (used in C-Kermit for serial device speed) 299 -S (used in C-Kermit to force an interactive command prompt) 300 -x (used in C-Kermit to start server mode) 301 --x (currently not used in C-Kermit) 302 -X (currently not used in C-Kermit) 303 304 3054. THE MECHANICS OF FILE TRANSFER 306 307To transfer files with G-Kermit you must be connected through a terminal 308emulator to the Unix system where G-Kermit is installed, meaning you are 309online to Unix and have access to the shell prompt (or to some menu that has 310an option to invoke G-Kermit), and your terminal emulator must support the 311Kermit file transfer protocol. The connection can be serial (direct or 312dialed) or network (Telnet, Rlogin, X.25, etc). 313 3144.1. Sending Files 315 316When you tell G-Kermit to SEND a file (or files), e.g. with: 317 318 $ gkermit -Ts oofa.txt 319 320it pauses for a second and then sends its first packet. What happens next 321depends on the capabilities of your terminal emulator: 322 323 . If your emulator supports Kermit "autodownloads" then it receives the 324 file automatically and puts you back in the terminal screen when done. 325 326 . Otherwise, you'll need to take whatever action is required by your 327 emulator to get its attention: a mouse action, a keystroke like Alt-x, 328 or a character sequence like Ctrl-\ or Ctrl-] followed by the letter 329 "c" (this is called "escaping back") and then tell it to receive the 330 file. When the transfer is complete, you might have to instruct your 331 emulator to go back to its terminal screen. 332 333During file transfer, most terminal emulators put up some kind of running 334display of the file transfer progress. 335 3364.2. Receiving Files 337 338When you tell G-Kermit to RECEIVE, this requires you to escape back to your 339terminal emulator and instruct it to send the desired file(s). Autodownload 340is not effective in this case. When the transfer is complete, you'll need 341to instruct your emulator to return to its terminal screen. 342 3434.3. Getting Files 344 345If your terminal emulator supports Kermit autodownloads AND server mode, you 346can use GET ("gkermit -g files...") rather than RECEIVE ("gkermit -r"), and 347the rest happens automatically, as when G-Kermit is sending. 348 349 3505. INTERRUPTING FILE TRANSFER 351 352G-Kermit supports file and group interruption. The method for interrupting 353a transfer depends on your terminal emulator. For example, while the 354file-transfer display is active, you might type the letter 'x' to cancel the 355current file and go on to the next one (if any), and the letter 'z' to 356cancel the group. Or there might be buttons you can click with your mouse. 357 358When G-Kermit is in packet mode and your terminal emulator is in its 359terminal screen, you can also type three (3) Ctrl-C characters in a row to 360make G-Kermit exit and restore the normal terminal modes. 361 362 3636. TEXT AND BINARY TRANSFER MODE 364 365When sending files in binary mode, G-Kermit sends every byte exactly as it 366appears in the file. This mode is appropriate for program binaries, 367graphics files, tar archives, compressed files, etc, and is G-Kermit's 368default file-transfer mode when sending. When receiving files in binary 369mode, G-Kermit simply copies each byte to disk. (Obviously the bytes are 370encoded for transmission, but the encoding and decoding procedures give a 371replica of the original file after transfer.) 372 373When sending files in text mode, G-Kermit converts the record format to the 374common one that is defined for the Kermit protocol, namely lines terminated 375by carriage return and linefeed (CRLF); the receiver converts the CRLFs to 376whatever line-end or record-format convention is used on its platform. When 377receiving files in text mode, G-Kermit simply strips carriage returns, 378leaving only a linefeed at the end of each line, which is the Unix 379convention. 380 381When receiving files, the sender's transfer mode (text or binary) 382predominates if the sender gives this information to G-Kermit in a Kermit 383File Attribute packet, which of course depends on whether your terminal 384emulator's Kermit protocol has this feature. Otherwise, if you gave a -i or 385-T option on the gkermit command line, the corresponding mode is used; 386otherwise the default mode (binary) is used. 387 388Furthermore, when either sending or receiving, G-Kermit and your terminal 389emulator's Kermit can inform each other of their OS type (Unix in G-Kermit's 390case). If your emulator supports this capability, which is called 391"automatic peer recognition", and it tells G-Kermit that its platform is 392also Unix, G-Kermit and the emulator's Kermit automatically switch into 393binary mode, since no record-format conversion is necessary in this case. 394Automatic peer recognition is disabled automatically if you include the -i 395(image) or -T (text) option. 396 397When sending, G-Kermit sends all files in the same mode, text or binary. 398There is no automatic per-file mode switching. When receiving, however, 399per-file switching occurs automatically based on the incoming Attribute 400packets, if any (explained below), that accompany each file, so if the 401file sender switches types between files, G-Kermit follows along. 402 403 4047. PATHNAMES 405 406When SENDING a file, G-Kermit obtains the filenames from the command line. 407It depends on the shell to expand metacharacters (wildcards and tilde). 408 409G-Kermit uses the full pathname given to find and open the file, but then 410strips the pathname before sending the name to the receiver. For example: 411 412 $ gkermit -s /etc/hosts 413 414results in an arriving file called "HOSTS" or "hosts" (the directory part, 415"/etc/", is stripped; see next section about capitalization). 416 417However, if a pathname is included in the -a option, the directory part 418is not stripped: 419 420 $ gkermit -s /etc/hosts -a /tmp/hosts 421 422This example sends the /etc/hosts file but tells the receiver that its name 423is "/tmp/hosts". What the receiver does with the pathname is, of course, up 424to the receiver, which might have various options for dealing with incoming 425pathnames. 426 427When RECEIVING a file, G-Kermit does NOT strip the pathname, since incoming 428files normally do not include a pathname unless you told your terminal to 429include them or gave an "as-name" including a path when sending to G-Kermit. 430If the incoming filename includes a path, G-Kermit tries to store the file 431in the specified place. If the path does not exist, the transfer fails. 432The incoming filename can, of course, be superseded with the -a option. 433 434 4358. FILENAME CONVERSION 436 437When sending a file, G-Kermit normally converts outbound filenames to 438common form: uppercase, no more than one period, and no funny characters. 439So, for example, gkermit.tar.gz would be sent as GKERMIT_TAR.GZ. 440 441When receiving a file, if the name is all uppercase, G-Kermit converts it 442to all lowercase. If the name contains any lowercase letters, G-Kermit 443leaves the name alone. Otherwise G-Kermit accepts filename characters as 444they are, since Unix allows filenames to contain practically any characters. 445 446If the automatic peer recognition feature is available in the terminal 447emulator, and G-Kermit recognizes the emulator's platform as Unix, G-Kermit 448automatically disables filename conversion and sends and accepts filenames 449literally. 450 451You can force literal filenames by including the -P option on the command 452line. 453 454 4559. FILENAME COLLISIONS 456 457When G-Kermit receives a file whose name is the same as that of an existing 458file, G-Kermit backs up the existing file by adding a unique suffix to its 459name. The suffix is ".~n~", where n is a number between 1 and 999. This 460the same kind of backup suffix used by GNU EMACS and C-Kermit (both of which 461can be used to prune excess backup files). But since G-Kermit does not read 462directories (see Implementation Notes below), it can not guarantee that the 463number chosen will be higher than any other backup prefix number for the 464same file. In fact, the first free number, starting from 1, is chosen. If 465an incoming file already has a backup suffix, G-Kermit strips it before 466adding a new one, rather than creating a file that has two backup suffixes. 467 468To defeat the backup feature and have incoming files overwrite existing 469files of the same name, include the -w (writeover) option on the command 470line. 471 472If G-Kermit has not been been given the -w option and it fails to create a 473backup file, the transfer fails. 474 475 47610. KERMIT PROTOCOL DETAILS 477 478Block check 479 G-Kermit uses the 3-byte, 16-bit CRC by default. If the other Kermit 480 does not agree, both Kermits automatically drop down to the single-byte 481 6-bit checksum that is required of all Kermit implementations. 482 483Attributes 484 When sending files, G-Kermit conveys the file transfer mode and file 485 size in bytes to the receiver in an Attribute (A) packet if the use of 486 A-packets was negotiated. This allows the receiver to switch to the 487 appropriate mode automatically, and to display the percent done, estimated 488 time left, and/or a thermometer bar if it has that capability. When 489 receiving, G-Kermit looks in the incoming A-packet, if any, for the 490 transfer mode (text or binary) and switches itself accordingly on a 491 per-file basis. 492 493Handling of the Eighth Bit 494 G-Kermit normally treats the 8th bit of each byte as a normal data bit. 495 But if you have a 7-bit connection, transfers of 8-bit files fail unless 496 you tell one or both Kermits to use the appropriate kind of parity, in 497 which case Kermit uses single-shift escaping for 8-bit bytes. Generally, 498 telling either Kermit is sufficient; it tells the other. Use the -p 499 option to tell G-Kermit which parity to use. Locking shifts are not 500 included in G-Kermit. 501 502Control-Character Encoding 503 G-Kermit escapes all control characters when sending (for example, 504 Ctrl-A becomes #A). When receiving, it accepts both escaped and bare 505 control characters, including NUL (0). However, unescaped control 506 characters always present a danger, so if uploads to G-Kermit fail, tell 507 your terminal emulator's Kermit to escape most or all control characters 508 (in C-Kermit and Kermit 95 the command is SET PREFIXING CAUTIOUS or SET 509 PREFIXING ALL). 510 511Packet Length 512 All legal packet lengths, 40-9020, are supported although a lower 513 maximum might be imposed on platforms where it is known that bigger ones 514 don't work. When receiving, G-Kermit sends its receive packet length to 515 the sender, and the sender must not send packets any longer than this 516 length. The default length for most platforms is 4000 and it may be 517 overridden with the -e command-line option. 518 519Sliding Windows 520 G-Kermit does not support sliding windows. Streaming is used instead. 521 If the other Kermit bids to use sliding windows, G-Kermit declines. 522 523Streaming 524 If the terminal emulator's Kermit informs G-Kermit that it has a 525 reliable connection (such as TCP/IP or X.25), and the emulator's Kermit 526 supports streaming, then a special form of the Kermit protocol is used 527 in which data packets are not acknowledged; this allows the sender to 528 transmit a steady stream of (framed and checksummed) data to the 529 receiver without waiting for acknowledgements, allowing the fastest 530 possible transfers. Streaming overcomes such obstacles as long round 531 trip delays, unnecessary retransmissions on slow network connections, 532 and most especially the TCP/IP Nagle and Delayed ACK heuristics which 533 are deadly to a higher-level ACK/NAK protocol. When streaming is in use 534 on a particular connection, Kermit speeds are comparable to FTP. The 535 drawback of streaming is that transmission errors are fatal; that's why 536 streaming is only used on reliable connections, which, by definition, 537 guarantee there will be no transmission errors. However, watch out for 538 the relatively rare circumstance in which emulator thinks it has a 539 reliable connection when it doesn't -- for example a Telnet connection 540 to a terminal server, and a dialout from the terminal server to the 541 host. Use the -S option on the command line to defeat streaming in such 542 situations. 543 544Using all defaults on a TCP/IP connection on 10BaseT (10Mbps) Ethernet from 545a modern Kermit program like C-Kermit 7.0 or Kermit 95, typical transfer 546rates are 150-500Kcps. 547 548 54911. PROBLEMS, BUGS, ERRORS 550 551If file transfers fail: 552 553 . Make sure your terminal emulator is not unprefixing control characters; 554 various control characters might cause trouble along the communication 555 path. When in doubt, instruct the file sender to prefix all control 556 characters. 557 558 . Make sure your Unix terminal is conditioned for the appropriate kind 559 of flow control. 560 561 . Use command-line options to back off on performance and transparency; 562 use -S to disable streaming, -e to select a shorter packet length, -p 563 to select space or other parity, -b to increase or disable the timeout, 564 and/or establish the corresponding settings on your emulator. 565 566When receiving files in text mode, G-Kermit strips all carriage returns, 567even if they aren't part of a CRLF pair. 568 569If you have a TCP/IP connection (e.g. Telnet or Rlogin) to Unix from a 570terminal emulator whose Kermit protocol does not support streaming, 571downloads from G-Kermit are likely to be as much as 10 or even 100 times 572slower than uploads if the TCP/IP stack engages in Nagle or Delayed ACK 573heuristics; typically, when your terminal emulator's Kermit protocol sends 574an acknowledgment, the TCP stack holds on to it for (say) 1/5 second before 575sending it, because it is "too small" to send right away. 576 577As noted in Section 9, the backup prefix is not guaranteed to be the highest 578number. For example, if you have files oofa.txt, oofa.txt.~1~, and 579oofa.txt.~3~ in your directory, and a new oofa.txt file arrives, the old 580oofa.txt is backed up to oofa.txt.~2~, rather than oofa.txt.~4~ as you might 581expect. This is because gkermit lacks directory reading capabilities, for 582reasons noted in Section 14, and without this, finding the highest existing 583backup number for a file is impractical. 584 585If you send a file to G-Kermit with streaming active when the connection is 586not truly reliable, all bets are off. A fatal error should occur promptly, 587but if huge amounts of data are lost, G-Kermit might never recognize a single 588data packet and therefore not diagnose a single error; yet your terminal 589emulator keeps sending packets since no acknowledgments are expected; the 590transfer eventually hangs at the end of file. Use -S on G-Kermit's command 591line to disable streaming in situations where the terminal emulator requests 592it in error. 593 594You can use G-Kermit's debug log for troubleshooting; this is useful mainly 595in conjunction with the source code. But even if you aren't a C programmer, 596it should reveal any problem in enough detail to help pinpoint the cause of 597the failure. "gkermit -d" (with no action options) writes a short debug.log 598file that shows the build options and settings. 599 600The debug log is also a packet log; to extract the packets from it, use: 601 602 grep ^PKT debug.log 603 604Packets in the log are truncated to avoid wrap-around on your screen, and 605they have the Ctrl-A packet-start converted to ^ and A to avoid triggering 606a spurious autodownload when displaying the log on your screen. 607 608In certain circumstances it is not desirable or possible to use -d to create 609a log file called debug.log in the current directory; for example, if you 610don't have write access to the current directory, or you already have a 611debug.log file that you want to keep (or transfer). In this case, you can 612include a filename argument after -d: 613 614 gkermit -d /tmp/testing.log -s *.c 615 616(This is an exception to the rule that option arguments are not optional.) 617 618If all else fails, you can contact the Kermit Project for technical support; 619see: 620 621 http://www.columbia.edu/kermit/support 622 623for instructions. 624 625 62612. BUILDING G-KERMIT 627 628G-Kermit is written to require the absolute bare minimum in system services 629and C-language features and libraries, and therefore should be portable to 630practically any Unix platform at all with any C compiler. 631 632The source files are: 633 634 makefile The build procedure 635 gwart.c Source code for a mini-lex substitute 636 gproto.w G-Kermit protocol state machine to be preprocessed by gwart 637 gkermit.h G-Kermit header file 638 gkermit.c G-Kermit main module and routines 639 gcmdline.c G-Kermit command-line parser 640 gunixio.c Unix-specific i/o routines 641 642A simple makefile is provided, which can be used with make or gmake. There 643are three main targets in the makefile: 644 645 posix 646 Build for any POSIX.1 compliant platform (termios). This is the 647 default target, used if you type "make" (or "gmake") alone. This 648 target works for most modern Unixes, including GNU/Linux, FreeBSD, 649 OpenBSD, NetBSD, BSDI, HP-UX, Solaris, SunOS, Unixware, AIX, etc. 650 651 sysv 652 Build for almost any AT&T System V platform (termio). Examples 653 include AT&T Unix releases, e.g. for the AT&T 7300, HP-UX versions 654 prior to 7.00. 655 656 bsd 657 Build for any BSD (pre-4.4) or Unix V7 platform (sgtty). Examples 658 include NeXTSTEP 3.x, OSF/1, and 4.3BSD or earlier. 659 660Note that the target names are all lowercase; "posix" is the default target 661(the one used if you just type "make"). If the build fails with a message 662like: 663 664 gunixio.c: 65: Can't find include file termios.h 665 *** Error code 1 666 667then try "make sysv" or "make bsd". See the build list below for examples. 668 669Some special build targets are also provided: 670 671 sysvx 672 Like sysv but uses getchar()/putchar() for packet i/o rather than 673 buffered nonblocking read()/write(); this is necessary for certain 674 very old System V platforms (see description of USE_GETCHAR below). 675 676 stty 677 When none of the other targets compiles successfully, try this one, 678 which runs the external stty program rather than trying to use 679 API calls to get/set terminal modes (system("stty raw -echo") and 680 system("stty -raw echo")). 681 682Several maintenance/management targets are also included: 683 684 clean 685 Remove object and intermediate files. 686 687 install 688 Install gkermit (read the makefile before using this). 689 690 uninstall 691 Uninstall gkermit from wherever "make install" installed it. 692 693The default compiler is cc. To override (e.g. to force the use of gcc on 694computers that have both cc and gcc installed, or that don't have cc), use: 695 696 [g]make CC=gcc [<target>] 697 698No other tools beyond make, the C compiler and linker, a short list of 699invariant header files, and the standard C library are needed or used. The 700resulting binary should be 100K or less on all hardware platforms (and 64K 701or less on most; see list below). 702 703You may also specify certain build options by including a KFLAGS clause on 704the make command line, e.g.: 705 706 make "KFLAGS=-DSETXONXOFF -DEXTRADEBUG" sysv 707 708By default, nonblocking buffered read() is used for packets; this technique 709works on most platforms but other options -- USE_GETCHAR and DUMBIO -- are 710provided when it doesn't work or when nonblocking i/o is not available. 711 712The build options include: 713 714__STDC__ 715 Include this when the compiler requires ANSI prototyping but does 716 does not define __STDC__ itself. Conversely, you might need to 717 include -U__STDC__ if the compiler defines __STDC__ but does not 718 support minimum ANSI features. 719 720ULONG=long 721 Include this if compilation fails with "unknown type: unsigned long". 722 723CHAR=char 724 Include this if compilation fails with "unknown type: unsigned char". 725 726SMALL 727 Define this when building on or for a "small" platform, for example 728 a 16-bit architecture. 729 730USE_GETCHAR 731 Specifies that packet i/o should be done with (buffered) getchar() 732 and putchar() rather than the default method of nonblocking, 733 internally buffered read() and write(). Use this only when G-Kermit 734 does not build or run otherwise, since if the default i/o code is 735 not used, G-Kermit won't be able to do streaming. 736 737DUMBIO 738 Specifies that packet i/o should be done with blocking single-byte 739 read() and write(). Use this only when G-Kermit doesn't build or 740 run, even with USE_GETCHAR. 741 742MAXRP=nnn 743 Change the maximum receive-packet length to something other than the 744 default, which is 9020. You should change this only to make it smaller; 745 making it bigger is not supported by the Kermit protocol. 746 747DEFRP=nnn 748 Change the default receive packet length to something other than the 749 default, which is 4000. Making it any bigger than this is not advised. 750 751TINBUFSIZ=nnn 752 On builds that use nonblocking buffered read(), override the default 753 input buffer size of 4080. 754 755SETXONXOFF 756 On some platforms, mainly those based on System V R4 and earlier, it was 757 found that receiving files was impossible on TCP/IP connections unless 758 the terminal driver was told to use Xon/Xoff flow control. If downloads 759 work but uploads consistently fail (or fail consistently whenever 760 streaming is used or the packet length is greater than a certain number 761 like 100, or 775), try adding this option. When gkermit is built with 762 this option, it is equivalent to the user always giving the -x option on 763 the command line. (Most versions of HP-UX need this; it is defined 764 automatically at compile time if __hpux is defined.) 765 766SIG_V 767 The data type of signal handlers is void. This is set automatically 768 for System V and POSIX builds. 769 770SIG_I 771 The data type of signal handlers is int. This is set automatically 772 for BSD builds. 773 774NOGETENV 775 Add this to disable the feature in which G-Kermit gets options from 776 the GKERMIT environment variable. 777 778NOSTREAMING 779 Add this to disable streaming. 780 781EXTRADEBUG 782 This adds a lot (a LOT) of extra information to the debug log 783 regarding packet and character-level i/o. 784 785FULLPACKETS 786 Show full packets in the debug log rather than truncating them. 787 788Any compiler warnings should be harmless. Examples include: 789 790"Passing arg 2 of `signal' from incompatible pointer" 791(or "Argument incompatible with prototype"): 792 Because no two Unix platforms agree about signal handlers. Harmless 793 because the signal handler does not return a value that is used. We 794 don't want to open the door to platform-specific #ifdefs just to 795 silence this warning. However, you can include -DSIG_I or -DSIG_V 796 on the CC command line to override the default definitions. 797 798"<blah> declared but never used": 799 Some function parameters are not used because they are just placeholders 800 or compatibility items, or even required by prototypes in system headers. 801 Others might be declared in system header files (like mknod, lstat, etc, 802 which are not used by G-Kermit). 803 804"Do you mean equality?": 805 No, in "while (c = *s++)" the assignment really is intentional. 806 807"Condition is always true": 808 Yes, "while (1)" is always true. 809 810"Flow between cases": 811 Intentional. 812 813"No flow into statement": 814 In gproto.c, because it is a case statement generated by machine, 815 not written by a human. 816 817The coding conventions are aimed at maximum portability. For example: 818 . Only relatively short identifiers. 819 . No long character-string constants. 820 . Only #ifdef, #else, #endif, #define, and #undef preprocessor directives. 821 . Any code that uses ANSI features is enclosed in #ifdef __STDC__..#endif. 822 . No gmake-specific constructs in the makefile. 823 824Here are some sample builds (December 1999): 825 826 Platform Size Target Notes 827 Apple Mac OS X 1.0 gcc: 48K posix (AKA Rhapsody 5.5) 828 AT&T 3B2/300 SVR2 cc: 49K sysv (4) 829 AT&T 6300 PLUS cc: 58K sysv (6) 830 AT&T 7300 UNIX PC cc: 40K sysv 831 AT&T 7300 UNIX PC gcc: 55K sysv (23K with shared lib) 832 BSDI 4.0.1 gcc: 34K posix 833 DEC 5000 MIPS Ultrix 4.3 cc: 99K posix 834 DEC Alpha Digital UNIX 3.2 cc: 98K bsd (AKA OSF/1) (1) 835 DEC Alpha Tru64 UNIX 4.0e cc: 82K bsd (1) 836 DEC PDP-11 2.11BSD cc: 40K bsd211 (7) 837 DG/UX 5.4R3.10 cc: 52K posix 838 DG/UX 5.4R4.11 gcc: 51K posix 839 DYNIX/ptx 4.4.2 cc: 43K posix 840 FreeBSD 2.2.7 gcc: 41K posix 841 FreeBSD 3.3 gcc: 34K posix 842 GNU/Linux RH 5.2 gcc: 35K posix (RH = Red Hat) 843 GNU/Linux RH 6.1 gcc: 44K posix 844 GNU/Linux SW 3.5 gcc: 34K posix (SW = Slackware) 845 GNU/Linux SW 4.0 gcc: 36K posix 846 GNU/Linux SW 7.0 gcc: 44K posix 847 HP-UX 5.21 cc: 55K sysv (2) 848 HP-UX 6.5 cc: 40K sysv (5) 849 HP-UX 7.05 cc: 50K posix 850 HP-UX 8.00 gcc: 33K posix 851 HP-UX 9.05 cc: 57K posix 852 HP-UX 10.01 cc: 57K posix 853 HP-UX 10.20 cc: 61K posix 854 IBM AIX 3.2 IBM cc: 62K posix 855 IBM AIX 4.1.1 IBM cc: 67K posix 856 IBM AIX 4.3.2 IBM cc: 69K posix 857 Motorola 88K SV/88 R4.3 42K posix 858 Motorola 68K SV/68 R3.6 56K sysv (4) 859 NetBSD 1.4.1 gcc: 41K posix 860 NeXTSTEP m68k 3.1 gcc: 77K bsd (3) 861 NeXTSTEP m68k 3.3 gcc: 78K bsd (3) 862 OpenBSD 2.5 gcc: 47K posix 863 QNX 4.25 cc: 33K posix 864 SCO XENIX 2.3.4 cc: 41K sysv (4) 865 SCO UNIX 3.2v4.2 cc: 73K posix 866 SCO UNIX 3.2v4.2 gcc: 61K posix 867 SCO ODT 3.0 cc: 97K posix 868 SCO OSR5.0.5 gcc: 42K posix 869 SCO Unixware 2.1.3 cc: 38K posix 870 SCO Unixware 7.0.1 cc: 37K posix 871 SGI IRIX 5.3 cc: 86K posix 872 SGI IRIX 6.5.4 cc: 91K posix 873 SINIX 5.42 MIPS cc: 57K posix 874 Solaris 2.4 cc: 50K posix 875 Solaris 2.5.1 cc: 51K posix 876 Solaris 2.6 cc: 52K posix 877 Solaris 7 cc: 52K posix 878 SunOS 4.1.3 cc: 57K posix 879 SunOS 4.1.3 gcc: 64K posix 880 881Notes: 882 883(1) "make posix" builds without complaint on OSF/1 (Digital UNIX (Tru64)) 884 but it doesn't work -- i/o hangs or program dumps core. "make bsd" 885 works fine. 886 887(2) POSIX APIs not available in this antique OS (circa 1983). Also due 888 to limited terminal input buffering capacity, streaming must be 889 disabled and relatively short packets must be used when receiving: 890 "gkermit -Se 250 -r". However, it can use streaming when sending. 891 892(3) POSIX APIs not available. 893 894(4) On System V R3 and earlier, EWOULDBLOCK is not defined, so we use EGAIN 895 instead. No special build procedures needed. 896 897(5) Built with 'make -i "KFLAGS=-DDEFRP=512 -DUSE_GETCHAR" sysv'. It can 898 be built without -DUSE_GETCHAR but doesn't work. 899 900(6) Use 'make "CC=cc -Ml" "KFLAGS=-DUSE_GETCHAR sysv'. It builds but 901 doesn't work, reason unknown, but probably because it was never designed 902 to be accessed remotely in the first place. 903 904(7) This is a 16-bit architecture. A special makefile target is needed 905 because its make program does not expand the $(CC) value when invoking 906 second-level makes. Packet and buffer sizes are reduced to keep 907 static data within limits. Overlays are not needed. 908 909 91013. INSTALLING G-KERMIT 911 912The makefile creates a binary called "gkermit". Simply move this binary to 913the desired directory, such as /usr/local/bin. It needs no special 914permissions other than read, write, and execute for the desired users and 915groups: no setuid, no setgid, or any other form of privilege. It should be 916called "gkermit" and not "kermit", since "kermit" is the binary name for 917C-Kermit, and the two are likely to be installed side by side on the same 918computer; even when they are not, consistent naming is better for support 919and sanity purposes. There is also a short man page: 920 921 gkermit.nr 922 923You can view it with: 924 925 nroff -man gkermit.nr | more 926 927Rename and store it appropriately. In addition, this file itself (README) 928should be made available in a public documentation directory as: 929 930 gkermit.txt 931 932The makefile includes a SAMPLE 'install' target that does all this. Please 933read it before use to be sure the appropriate directories and permissions 934are indicated. There is also an 'uninstall' target to undo an installation. 935Obviously you need write access to the relevant directories before you can 936install or uninstall G-Kermit. 937 938 93914. DESIGN AND IMPLEMENTATION NOTES 940 941A primary objective in developing G-Kermit is that it can be released and 942used forever without constant updates to account for platform idiosyncracies 943and changes. For this reason, certain features have been deliberately 944omitted: 945 946 . File timestamps. The methods for dealing with internal time formats 947 are notoriously unportable and also a moving target, especially now 948 with the 32-bit internal time format rollover looming in 2038 and the 949 time_t data type changing out from under us. Furthermore, by excluding 950 any date-handling code, G-Kermit is automatically Y2K, 2038, and Y10K 951 compliant. 952 953 . Internal wildcard expansion, recursive directory traversal, etc. Even 954 after more than 30 years, there is still no standard and portable 955 service in Unix for this. 956 957 . Hardware flow control, millisecond sleeps, nondestructive input buffer 958 peeking, threads, select(), file permissions, etc etc. 959 960Other features are omitted to keep the program small and simple, and to 961avoid creeping featurism: 962 963 . Sliding windows. This technique is more complicated than streaming but 964 not as fast, and furthermore would increase the program size by a 965 factor of 5 or 10 due to buffering requirements. 966 967 . An interactive command parser and scripting language (because users 968 always want more and more commands and features). 969 970 . Character set conversion (because users always want more and more 971 character sets). Adding character set support would increase the 972 program size by a factor of 2 to 4, depending on the selection of sets. 973 974 . Making connections (because this requires huge amounts of tricky and 975 unstable high-maintenance platform- and device-specific code for serial 976 ports, modems, modem signals, network stacks, etc). 977 978All of the above can be found in C-Kermit, which is therefore bigger and 979more complicated, with more platform-specific code and #ifdef spaghetti. 980C-Kermit requires constant updates and patches to keep pace with changes in 981the underlying platforms, networking methods, and demands from its users for 982more features. 983 984The goal for G-Kermit, on the other hand, is simplicity and stability, so we 985don't need thousands of #ifdefs like we have in C-Kermit, and we don't need 986to tweak the code every time a new release of each Unix variety comes out. 987G-Kermit is meant to be PORTABLE and LONG-LASTING so the stress is on a 988MINIMUM of platform dependencies. 989 990If you make changes, please try to avoid adding anything platform-dependent 991or in any other way destabilizing. Bear in mind that the result of your 992changes should still build and run successfully on at least all the 993platforms where it was built originally. In any case, you are encouraged to 994send any changes back to the Kermit Project to be considered for addition to 995the master G-Kermit distribution. 996 997 99815. FURTHER INFORMATION 999 1000The Kermit protocol is specified in "Kermit, A File Transfer Protocol" by 1001Frank da Cruz, Digital Press (1987). A correctness proof of the Kermit 1002protocol appears in "Specification and Validation Methods", edited by Egon 1003Boerger, Oxford University Press (1995). "Using C-Kermit" by Frank da Cruz 1004and Christine M. Gianone, Digital Press (1997, or later edition) explains 1005many of the terms and techniques referenced in this document in case you are 1006not familiar with them, and also includes tutorials on data communications, 1007extensive troubleshooting and performance tips, etc. Various other books on 1008Kermit are available from Digital Press. Online resources include: 1009 1010 http://www.columbia.edu/kermit/ The Kermit Project website 1011 comp.protocols.kermit.misc The unmoderated Kermit newsgroup 1012 kermit-support@columbia.edu Technical support 1013 1014(End of G-Kermit README) 1015