XMODEM

Section: Misc. Reference Manual Pages (LOCAL)
Updated: November 2, 1990
Index Return to Main Contents

NAME

xmodem - Christensen protocol file transfer utility - Version 3.9, November 1990

SYNOPSIS

xmodem [st|sb|sa|rt|rb|ra][ygmkctdlxpwen] [file...]

DESCRIPTION

The xmodem program implements the Christensen (XMODEM) file transfer protocol for moving files between 4.2/4.3BSD Unix systems (and successors, including Suns) and microcomputers. The XMODEM/CRC protocol, the MODEM7 batch protocol, the XMODEM-1K block protocol, the YMODEM batch protocol and the YMODEM-G streaming protocol are all supported by xmodem. The ZMODEM protocol is not supported. For details of the XMODEM/YMODEM protocols, see the document edited by Chuck Forsberg titled XMODEM/YMODEM Protocol Reference.

Option Flags are case insensitive; the cluster of flags may be preceded by an optional "-" character.

PARAMETERS

Exactly one of the following must be selected:

rb: Receive Binary - files are placed on the Unix disk without conversion. Xmodem will silently destroy existing files of the same name.
rt: Receive Text - files are converted from the CP/M and MS-DOS format of CR-LF pairs to the Unix convention of newline characters only between lines. Null bytes are ignored and bit 8 of each character is stripped (which makes Wordstar files much more readable). A CTRL-Z character is deemed to indicate the EOF location in the incoming file. The resulting file is acceptable to the Unix editors and compilers, and is usually slightly smaller than the original file. Xmodem will silently destroy existing files of the same name.
ra: Receive Apple - same as rt save CR characters in the incoming file are translated into Unix newline characters.
sb: Send Binary - files are sent without conversion as they exist on the Unix disk.
st: Send Text - newline characters in the file are converted to CR-LF pairs in accord with the CP/M and MS-DOS conventions for text files. The file "grows" in this process.
sa: Send Apple - same as st save newline characters are converted into CR characters in accord with Apple Macintosh conventions for text files.

OPTIONS

y: Select the YMODEM batch protocol for sending files; a list of files specified on the command line will be sent in sequence. The YMODEM batch protocol is used automatically for file reception if the sending program requests it. If this flag is specified for a batch receive, (xmodem rty, for example), the transfer will never attempt to switch from CRC to checksum mode.
g: Select the YMODEM-G variant of YMODEM when receiving files. YMODEM-G is automatically invoked on transmit if the receiving program requests it. YMODEM-G is designed for "error-free" connections with proper flow control; the transmitting program blasts packets to the receiver as fast as it can without waiting for acknowledgements. Any errors cause the entire file transfer to be aborted.
m: Select the MODEM7 batch protocol for sending files; a list of files specified on the command line will be sent in sequence. The MODEM7 batch protocol is used automatically for file reception if the sending program requests it. If this flag is specified for a batch receive, (xmodem rbm, for example), the transfer starts in checksum mode rather than CRC mode. If both "m" and "c" are specified on a receive command, the initial "file-name" negotiations are done using checksums while the file transfers are done using CRC-16.
k: Select the XMODEM-1K file transfer mode for sending files. Use of 1K packets on low-error lines increases throughput. However, over direct connections at 9600 bps to a busy host, 1K packets may cause data overflows generating excessive retries. 1K packets are automatically used for file reception if the sending program requests it. If this flag is specified with the YMODEM flag in a batch receive (xmodem rbyk, for example), the program will attempt to use the "KMD/IMP" convention to invoke 1K file transfers.
c: Select the CRC-16 error-checking protocol on receive. CRC mode is better at catching transmission errors that occur than the alternative checksum protocol. CRC mode is automatically selected for file transmission if the receiving modem program requests it.
t: Indicates the Unix system is Too Busy and xmodem should fall back to a simpler I/O strategy than normal.
d: Delete the xmodem.log file before file transfer is begun.
l: Do NOT write to the log file. If logging is selected, a file xmodem.log will be created (or appended to), with entries for significant events, errors and retries. This can be useful to see why things went wrong when they do.
x: Toggle on debug mode. If debug mode is selected, copious and possibly useful debugging information will be placed in xmodem.log.
p: Assume that xmodem is being invoked through SunOS tip (via the ~C command). Status and error messages will be sent to stderr, and hence to your screen, while the transfer is in progress. Do not use this option unless you are using tip!
w: Wait 15 seconds before initiating the startup handshake. Useful if handshake characters are trashing things you need to type.
e: Suppress EOT verification. Normally, xmodem tries to verify an EOT character (used to signify the end of file) by NAKing it and waiting for the EOT to be resent. This reliability feature can generate harmless error messages in some microcomputer file transfer programs; other programs refuse to work at all. To accomodate the latter brain-damaged programs, use the "e" option.
n: Allow CAN-CAN aborts during mid-transfer. Normally, as a reliability feature, CAN-CAN aborts are only allowed at the beginning of a file transfer. If you don't like this feature, use the "n" flag.

FILE NAMES

Files transmitted using one of the batch modes will be stored on the remote machine under a CP/M-ified name (path names stripped, limited to eight characters plus a three character extension; ":" characters will be turned into "/" characters; all characters will be in monocase). Files received using one of the batch modes will be stored under their transmitted names (except that any "/" characters in the file name will be converted into ":" characters, all upper-case characters will be translated into lower case and trailing dots will be expunged).

When a batch receive is requested, xmodem takes a wait and see attitude and can adapt to either batch protocol or even a classic XMODEM transfer (note that CRC-16 mode is automatically set under these circumstances unless the b flag is specified). If a classic, "non-batch" XMODEM file reception takes place, the received file is stored as xmodem.in. File names present on the command line for a batch receive are ignored.

NOTES

Remember, CRC-16 error detection and YMODEM-G streaming must be invoked by the receiving program while 1K blocksize must be invoked by the sending program.

While waiting for the beginning of a file transfer, xmodem treats two CAN (CTRL-X) characters that are received within 3 seconds as a request to abort. CAN characters will not cause an abort if received in the midst of a file transfer (unless the "n" option was invoked).

If 10 or more errors are detected during the transmission or reception of any one packet, the transfer is aborted.

Squeezed, compressed, ZIPed or ARCed files must be transferred in binary mode, even if they contain text.

If you use xmodem over a rlogin link, you may have to use the form rlogin machine -8.

If an unexpected error occurs before a file is completely received, the incomplete file is deleted.

Files received using both binary and text mode in a YMODEM batch transfer will be truncated to the file size specified in the YMODEM header (extra CR characters in the incoming file are correctly handled). File sizes are included in the YMODEM header when sending both binary and text files. Thus files transferred via YMODEM should preserve their exact length. File modification times are set for received files if present in the YMODEM header; they are included in the headers for transmitted files (watch for timezone problems, however).

The "KMD/IMP" record count field in the YMODEM header is both set and read.

xmodem can be used through the SunOS tip program to transfer files. Use tip to establish a session on a remote computer. Enter the file transfer command on the remote computer to send or receive files, then use the ~C command which causes tip to request a local command string and enter the appropriate xmodem command. Use the "p" option on the local xmodem command so you will see status reports on your screen. If the xmodem is running on the remote machine, use the "w" option there to halt the initiation of file-transfer handshaking for a bit to allow you to enter the ~C command line without interference.

The MODEM7 batch protocol is archaic and should only be used if YMODEM batch protocols are not available in your PC's communication program. If you must use MODEM7, you may have to specify the "m" option or, preferably, "cm" when receiving files with xmodem.

EXAMPLES

To receive a text file transmitted from a micro (using CRC-16 error-checking) and store it under the name file.name, use the command line

: xmodem rtc file.name

Note that if the transmitting program on the micro uses the 1K packet protocol and/or the YMODEM batch protocol, xmodem detects this automatically and takes appropriate action. Further note that if one of the batch protocols is used, the received file(s) will be stored under their own names and the name on the command line (if any) will be ignored. Finally, note that CRC-16 error checking is the default. Thus, a generic command to receive files would be

: xmodem rt

To send a set of text files to a microcomputer using 1K packets and the YMODEM batch protocol, use the command line

: xmodem styk *.txt

FILES

xmodem.log (if logging is enabled)

BUGS

Batch mode could be smarter about bad file-names in the midst of a batch transmit/receive.

Batch mode could allow a mixture of binary and text files.

Bare Carriage Return characters (i.e., those not immediately followed by a Line Feed character) are mishandled in a received file when using text mode. A file with "overstruck" lines will thus come out looking funny.

AUTHOR

Steve Grandi, National Optical Astronomy Observatories (grandi@noao.edu). Based on xmodem by Brian Kantor, University of California at San Diego. This, in turn, was based on umodem by Lauren Weinstein, Richard Conn and others.

This document was created by man2html, using the manual pages.
Time: 06:35:08 GMT, December 12, 2024