Celestin Apprentice 2/Apprentice-Release2.iso/Source Code/C/Libraries/xmodem 3.10/xmodem.1

Text File | 1994-05-10 | 11.2 KB | 312 lines | [TEXT/MPS ]

.TH XMODEM LOCAL "December 14, 1990"
.UC 4.2
.SH NAME
xmodem \- Christensen protocol file transfer utility \- Version 3.10, December 1990
.SH SYNOPSIS
.B xmodem
[\fBst|sb|sa|rt|rb|ra\fR][\fBygmkctdlxpwen\fR]
[file...]
.br
.SH DESCRIPTION
The
.I 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
.IR xmodem .
The ZMODEM protocol is not supported.
For details of the XMODEM/YMODEM protocols,
see the document edited by Chuck Forsberg titled
.I
XMODEM/YMODEM Protocol Reference.
.sp
Option Flags are case insensitive; the cluster of flags
may be preceded by an optional "-"
character.
.PP
.SH PARAMETERS
Exactly one of the following must be selected:
.TP
.B rb
Receive Binary - files are placed on the Unix disk without conversion.
.I Xmodem
will silently destroy existing files of the same name.
.TP
.B 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.
.I Xmodem
will silently destroy existing files of the same name.
.TP
.B ra
Receive Apple - same as rt save CR characters in the incoming file are
translated into Unix newline characters.
.TP
.B sb
Send Binary - files are sent without conversion as they exist on the Unix disk.
.TP
.B 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.
.TP
.B sa
Send Apple - same as st save newline characters are converted into CR
characters in accord with Apple Macintosh conventions for text files.
.PP
.SH OPTIONS
.TP
.B 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, (\fIxmodem rty\fR, for example),
the transfer will never attempt to switch from CRC to checksum mode.
.TP
.B 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.
.TP
.B 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, (\fIxmodem rbm\fR, 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.
.TP
.B 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 (\fIxmodem
rbyk\fR, for example), the program will attempt to use the "KMD/IMP" convention
to invoke 1K file transfers.
.TP
.B 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.
.TP
.B t
Indicates the Unix system is Too Busy and
.I xmodem
should fall back to a simpler I/O strategy than normal.
.TP
.B d
Delete the
.I xmodem.log
file before file transfer is begun.
.TP
.B l
Do NOT write to the log file.  If logging is selected, a file
.I 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.
.TP
.B x
Toggle on debug mode.  If debug mode is selected, copious and possibly
useful debugging information will be placed in
.IR xmodem.log .
A second "x" will place even more information in the log.
.TP
.B p
Assume that
.I 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.
.B Do
.B not
use this option unless you are using tip!
.TP
.B w
Wait 15 seconds before initiating the startup handshake.  Useful if handshake
characters are trashing things you need to type.
.TP
.B e
Suppress EOT verification.
Normally,
.I 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.
.TP
.B 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.
.SH "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).
.PP
When a batch receive is requested,
.I 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
.IR xmodem.in .
File names present on the command line for a batch receive are ignored.
.SH NOTES
Remember, CRC-16 error detection and YMODEM-G streaming must be invoked by
the
.B receiving
program while 1K blocksize must be invoked by the
.B sending
program.
.PP
While waiting for the beginning of a file transfer,
.I 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).
.PP
If 10 or more errors are detected during the transmission or reception of any
one packet, the transfer is aborted.
.PP
Squeezed, compressed, ZIPed or ARCed files must be transferred in binary mode,
even if they contain text.
.PP
If you use
.I xmodem
over a
.I rlogin
link, you may have to use the form
.IR "rlogin machine -8" .
This insures a full 8-bit wide datapath.
.PP
If there is any "magic box" between your Unix box and PC (such as a terminal
server or a telnet box), make sure that the magic box provides a fully
transparent 8-bit path and does not intercept ^S characters or listen for an
"escape" sequence to get the magic box's attention.
.PP
MIPS's RISC/os version of Unix handles ^S characters and strips the high-order
bit on input even in raw mode.
Try the command
.IR "/bin/stty -istrip -ixon"
before running
.I xmodem
on MIPS machines if you are having trouble uploading.
.PP
If an unexpected error occurs before a file is completely received, the
incomplete file is deleted.
.PP
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).
.PP
The "KMD/IMP" record count field in the YMODEM header is both set and read.
.PP
.I xmodem
can be used through the SunOS
.I tip
program to transfer files.  Use
.I 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
.I tip
to request a local command string and enter the appropriate
.I xmodem
command.  Use the "p" option on the local
.I xmodem
command so you will see status reports on your screen.
If the
.I 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.
.PP
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
.IR xmodem .
.SH EXAMPLES
.PP
To receive a text file transmitted from a micro (using CRC-16
error-checking) and store it under the
name
.IR file.name ,
use the command line
.RS
.B "xmodem rtc file.name"
.RE
Note that if the transmitting program on the micro uses the 1K packet
protocol and/or the YMODEM batch protocol,
.I 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
.RS
.B "xmodem rt"
.RE
.PP
To send a set of text files to a microcomputer using 1K packets and the
YMODEM batch protocol, use the command line
.RS
.B "xmodem styk *.txt"
.RE
.SH FILES
xmodem.log (if logging is enabled)
.SH BUGS
Batch mode could be smarter about bad file-names in the midst of a
batch transmit/receive.
.PP
Batch mode could allow a mixture of binary and text files.
.PP
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.
.SH SEE ALSO
kermit(1), rz(1), sz(1)
.SH AUTHOR
Steve Grandi, National Optical Astronomy Observatories ([e-mail]).
Based on
.I xmodem
by Brian Kantor, University of California at San Diego.
This, in turn, was based on
.I umodem
by Lauren Weinstein, Richard Conn and others.