GKERMIT(1)

okay bestie, this is GKERMIT(1) from the General Commands Manual, and it's giving "old-school file transfer but make it cute" 💖

---

🌸 NAME 🌸

gkermit — G-Kermit (GNU Kermit) 1.00 file transfer software. That's it, that's the whole name section, she's concise 💅

---

✨ SYNOPSIS ✨

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

Three whole moods, pick one 🫶

---

🦋 DESCRIPTION 🦋

G-Kermit is a UNIX program for transferring files using 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. (Yes bestie, actual free software, actual license file, go read it 💖)

💜 INVOKING G-KERMIT 💜

The G-Kermit binary is called gkermit. It should live somewhere in your UNIX PATH; normally it's chilling at /usr/local/bin/gkermit. To run G-Kermit, just type gkermit followed by command-line options that tell it what to do. And if you give it no options at all? It prints a usage message listing the available options. Helpful queen behavior, honestly 😌

If an option takes an argument, that argument is required (no skipping, no cap). If an option doesn't take an argument, you may not give it one — exception: -d. The action options are -r, -s, and -g. Only one action option may be given. And if no action options are given, G-Kermit does nothing (except possibly to print its usage message or create a debug.log file). She's just standing there. Menacingly. 💀

Here are some examples ($ 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 don't take arguments can be "bundled" with other options. But 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. Just sitting pretty, waiting for the moment ✨
• -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). The go-to, the standard, the blueprint 👑
• -T — TEXT. Text-mode transfer.
• -P — PATH (filename) conversion disabled.
• -w — WRITEOVER when filenames collide. Bold. Aggressive. Respect.
• -K — KEEP incompletely received files.
• -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. (Shy girl era 🙈)
• -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 command-line options. These are processed before the actual command-line options and so can be overridden by them. Here's an 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"

Set it once, forget it forever. Iconic ✨

🌈 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). So many options, so much range 💅

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. Effortless. Main character energy 👑
• 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 must instruct your emulator to go back to its terminal screen. Annoying but doable, bestie 🫶

During file transfer, most terminal emulators put up some kind of running display of the file transfer progress. (The little progress bar. We love her.)

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 desired file(s).

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. Auto-pilot mode, no notes 🌟

💅 INTERRUPTING FILE TRANSFER 💅

G-Kermit supports file and group interruption. The method for interrupting 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. Whatever your emulator's vibe is 😌

When G-Kermit is in packet mode and your terminal emulator is in its terminal screen, you can also type three (3) Ctrl-C characters in a row to make G-Kermit exit and restore the normal terminal modes. The emergency exit. The "I'm done here" button. Use it wisely 🔥

🦋 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.) No data lost, no cap, fr fr 💖

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 terminated 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 carriage 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) predominates if the sender gives this information to G-Kermit in a Kermit File Attribute packet, which of course depends on whether your terminal emulator'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. Priorities, bestie. The sender speaks first 📢

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-Kermit'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. It's giving mutual understanding, it's giving soulmates 🥹

When sending, G-Kermit sends all files in the same mode, text or binary. There is no automatic per-file mode switching. When receiving, however, 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). So the shell does that part, okay? Not G-Kermit's job 💅

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

$ gkermit -s /etc/hosts

results in the receiver getting a file called "HOSTS" or "hosts" (the directory part, "/etc/", is stripped). Bye directory, you weren't invited to the party 🎀

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. Not G-Kermit's business, not G-Kermit's problem 😌

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.

⚠️ bestie, heads up: no path means no file. If that directory doesn't exist, it's over. Make the directory first, okay? 🫶

🌸 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. Glow-up, but make it filename edition ✨

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. She's not gonna touch what's already cute 💅

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

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

💖 FILENAME COLLISIONS 💖

When G-Kermit receives a file whose name is the same as that of an existing 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. She's a team player, she plays nice with others 🥹

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. Chaos mode. Choose violence. 🔥

---

⭐ RETURN VALUES ⭐

G-Kermit returns an exit status code of 0 if all actions succeeded and 1 if any actions failed. Zero means slay, one means 😭

---

...and bestie, that's only part 1 — there's more where this came from, don't go anywhere 💖

🌸 IMPLEMENTATION NOTES 🌸

okay so here's the tea about why G-Kermit is the way it is 🫶 — it's built to be small, portable, and stable, and it's meant to live on the far end of a connection only. like, it does not make connections itself, periodt. but bestie, it can be used as an external protocol by other programs that do the connecting. 💅

to keep it smol and stable, it doesn't do sliding windows, it doesn't have a command or scripting language, and it doesn't do character-set translation. nope, none of that. 🙈

and to keep it portable and stable, it avoids system services that aren't standardized across all UNIX varieties. which means — specifically — no file timestamps, no internal wildcard expansion, and no other features that aren't implemented consistently (or at all) across every UNIX out there. it's giving ✨minimalist✨ and honestly? iconic.

---

🌈 ENVIRONMENT 🌈

you can define a GKERMIT environment variable (like, in your shell profile, super casual) and stuff G-Kermit command-line options inside it. 🎀

those get processed by G-Kermit before any options you put on the command line, which means command-line options override them. so the command line is the main character here. 👑

---

💖 DIAGNOSTICS 💖

if something goes wrong during a file transfer, G-Kermit sends an error packet to your terminal emulator to cancel the whole thing. an appropriate error message should pop up on your screen. so like, you will know. 😭

---

💀 ERRORS 💀

file transfers can fail for a bunch of reasons, no cap:

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

...and many others 🫠 — these are covered in the references.

---

📚 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're not familiar with them — and it also includes tutorials on data communications, extensive troubleshooting and performance tips, etc. so like, a whole vibe. 🦋

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 necessarily fast or reliable. 💅 (the way that's just... facts.)

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. yes, all of them. be aware.

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.

---

and that's the whole page bestie 💜 this was UNIX G-Kermit, version dated 25 Dec 1999, living in section GKERMIT(1) of the manual — go forth and transfer some files, you got this 🎀✨