XMODEM(LOCAL) XMODEM(LOCAL)
November 2, 1990
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.
- 1 - Formatted: April 25, 2025
XMODEM(LOCAL) XMODEM(LOCAL)
November 2, 1990
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.
- 2 - Formatted: April 25, 2025
XMODEM(LOCAL) XMODEM(LOCAL)
November 2, 1990
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
- 3 - Formatted: April 25, 2025
XMODEM(LOCAL) XMODEM(LOCAL)
November 2, 1990
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
- 4 - Formatted: April 25, 2025
XMODEM(LOCAL) XMODEM(LOCAL)
November 2, 1990
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.
SEE ALSO
kermit(1), rz(1), sz(1)
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.
- 5 - Formatted: April 25, 2025
