RZ(1)
NAME
rx, rb, rz - XMODEM, YMODEM, ZMODEM (Batch) file receive
SYNOPSIS
rz [- +8abeOpqRtTuUvy]
rb [- +abqRtuUvy]
rx [- abceqRtuUv] file
[-][v]rzCOMMAND
DESCRIPTION
This program uses error correcting protocols to receive
files over a dial-in serial port from a variety of pro-
grams running under PC-DOS, CP/M, Unix, and other operat-
ing systems. It is invoked from a shell prompt manually,
or automatically as a result of an "sz file ..." command
given to the calling program.
While rz is smart enough to be called from cu(1), very few
versions of cu(1) are smart enough to allow rz to work
properly. Unix flavors of Professional-YAM are available
for such dial-out application.
Rz (Receive ZMODEM) receives files with the ZMODEM batch
protocol. Pathnames are supplied by the sending program,
and directories are made if necessary (and possible).
Normally, the "rz" command is automatically issued by the
calling ZMODEM program, but some defective ZMODEM imple-
mentations may require starting rz the old fashioned way.
Rb receives file(s) with YMODEM, accepting either standard
128 byte sectors or 1024 byte sectors (YAM sb -k option).
The user should determine when the 1024 byte block length
actually improves throughput without causing lost data or
even system crashes.
If True YMODEM (Omen Technology trademark) file informa-
tion (file length, etc.) is received, the file length
controls the number of bytes written to the output
dataset, and the modify time and file mode (iff non zero)
are set accordingly.
If no True YMODEM file information is received, slashes in
the pathname are changed to underscore, and any trailing
period in the pathname is eliminated. This conversion is
useful for files received from CP/M systems. With YMODEM,
each file name is converted to lower case unless it con-
tains one or more lower case letters.
Rx receives a single file with XMODEM or XMODEM-1k proto-
col. The user should determine when the 1024 byte block
length actually improves throughput without causing
problems. The user must supply the file name to both
sending and receiving programs. Up to 1023 garbage char-
acters may be added to the received file.
Rz may be invoked as rzCOMMAND (with an optional leading -
as generated by login(1)). For each received file, rz
will pipe the file to ``COMMAND filename'' where filename
is the name of the transmitted file with the file contents
as standard input.
Each file transfer is acknowledged when COMMAND exits with
0 status. A non zero exit status terminates transfers.
A typical use for this form is rzrmail which calls
rmail(1) to post mail to the user specified by the trans-
mitted file name. For example, sending the file "caf"
from a PC-DOS system to rzrmail on a Unix system would
result in the contents of the DOS file "caf" being mailed
to user "caf".
On some Unix systems, the login directory must contain a
link to COMMAND as login sets SHELL=rsh which disallows
absolute pathnames. If invoked with a leading ``v'', rz
will be verbose (see v option). The following entry works
for Unix SYS III/V:
rzrmail::5:1::/bin:/usr/local/rzrmail
If the SHELL environment variable includes rsh , rbash or
rksh (restricted shell), rz will not accept absolute path-
names or references to a parent directory, will not modify
an existing file, and removes any files received in error.
If rz is invoked with stdout and stderr to different
datasets, Verbose is set to 2, causing frame by frame
progress reports to stderr. This may be disabled with the
q option.
OPTIONS
The meanings of the available options are:
-+, --append
append received data to an existing file (ZMODEM,
ASCII only).
-a, --ascii
Convert files to Unix conventions by stripping car-
riage returns and all characters beginning with the
first Control Z (CP/M end of file).
-b, --binary
Binary (tell it like it is) file transfer override.
-B NUMBER, --bufsize NUMBER
Buffer NUMBER bytes before writing to disk. Default
ist 32768, which should be enough for most situa-
tions. If you have a slow machine or a bad disk
interface or suffer from other hardware problems
you might want to increase the buffersize. -1 or
auto use a buffer large enough to buffer the whole
file. Be careful with this options - things nor-
mally get worse, not better, if the machine starts
to swap.
-c, --with-crc
XMODEM only. Use 16 bit CRC (normally a one byte
checksum is used).
-C, --allow-remote-commands
allow remote command execution ( insecure ). This
allows the sender to execute an arbitrary command
through system () or execl (). Default is to dis-
able this feature (?). This option is ignored if
running in restricted mode.
-D, --null
Output file data to /dev/null; for testing. (Unix
only)
--delay-startup N
Wait N seconds before doing anything.
-e, --escape
Force sender to escape all control characters; nor-
mally XON, XOFF, DLE, CR-@-CR, and Ctrl-X are
escaped.
-E, --rename
Rename incoming file if target filename already
exists. The new file name will have a dot and a
number (0..999) appended.
-h, --help
give help screen.
-m N, --min-bps N
Stop transmission if BPS-Rate (Bytes Per Second)
falls below N for a certain time (see --min-bps-
time option).
-M N, --min-bps-time
Used together with --min-bps. Default is 120 (sec-
onds).
-O, --disable-timeouts
Disable read timeout handling code. This makes lrz
hang if the sender does not send any more, but
increases performance (a bit) and decreases system
load (through reducing the number of system calls
by about 50 percent).
Use this option with care.
-p, --protect
(ZMODEM) Protect: skip file if destination file
exists.
-q, --quiet
Quiet suppresses verbosity.
-r, --resume
Crash recovery mode. lrz tries to resume inter-
rupted file transfers.
-R, --restricted
Enter more restricted mode. lrz will not create
directories or files with a leading dot if this
option is given twice.
See SECURITY for mode information about restricted
mode.
-s HH:MM, --stop-at HH:MM
Stop transmission at HH hours, MM minutes. Another
variant, using +N instead of HH:MM, stops transmis-
sion in N seconds.
-S, --timesync
Request timesync packet from the sender. The sender
sends its system time, causing lrz to complain
about more then 60 seconds difference.
Lrz tries to set the local system time to the
remote time if this option is given twice (this
fails if lrz is not run by root).
This option makes lrz incompatible with certain
other ZModems. Don't use it unless you know what
you are doing.
--syslog[=off]
turn syslogging on or off. the default is set at
configure time. This option is ignored if no sys-
log support is compiled in.
-t TIM, --timeout TIM
Change timeout to TIM tenths of seconds. This is
ignored if timeout handling is turned of through
the O option.
-U, --unrestrict
turn off restricted mode (this is not possible if
running under a restricted shell).
--version
prints out version number.
-v, --verbose
Verbose causes a list of file names to be appended
to stderr. More v's generate more output.
-wN, --windowsize N
Set window size to N.
-X, --xmodem
use XMODEM protocol.
-y, --overwrite
Yes, clobber any existing files with the same name.
--ymodem
use YMODEM protocol.
-Z, --zmodem
use ZMODEM protocol.
SECURITY
Contrary to the original ZMODEM lrz defaults to restricted
mode. In restricted mode lrz will not accept absolute
pathnames or references to a parent directory, will not
modify an existing file, and removes any files received in
error. Remote command execution is disabled.
To use a more restricted mode set the environment variable
ZMODEM_RESTRICTED or give the R option. This disables cre-
ation of subdirectories and invisible files.
Restricted mode may be turned off with the U option,
unless lrz runs under a restricted shell.
ENVIRONMENT
lrz uses the following environment variables:
SHELL lrz recognizes a restricted shell if this variable
includes rsh or rksh
ZMODEM_RESTRICTED
lrz enters the more restricted mode if the variable
is set.
EXAMPLES
(Pro-YAM command)
<ALT-2>
Pro-YAM Command: sz *.h *.c
(This automatically invokes rz on the connected system.)
SEE ALSO
ZMODEM.DOC, YMODEM.DOC, Professional-YAM, crc(omen)
sz(omen) usq(omen) undos(omen)
Compile time options required for various operating sys-
tems are described in the source file.
NOTES
Sending serial data to timesharing minicomputers at sus-
tained high speeds has been known to cause lockups, system
halts, kernel panics, and occasional antisocial behaviour.
When experimenting with high speed input to a system, con-
sider rebooting the system if the file transfers are not
successful, especially if the personality of the system
appears altered.
The Unix "ulimit" parameter must be set high enough to
permit large file transfers.
The TTY input buffering on some systems may not allow long
blocks or streaming input at high speed. You should sus-
pect this problem when you can't send data to the Unix
system at high speeds using ZMODEM, YMODEM-1k or XMO-
DEM-1k, when YMODEM with 128 byte blocks works properly.
If the system's tty line handling is really broken, the
serial port or the entire system may not survive the
onslaught of long bursts of high speed data.
The DSZ or Pro-YAM zmodem l numeric parameter may be set
to a value between 64 and 1024 to limit the burst length
("zmodem pl128").
32 bit CRC code courtesy Gary S. Brown. Directory cre-
ation code from John Gilmore's PD TAR program.
BUGS
Calling rz from most versions of cu(1) doesn't work
because cu's receive process fights rz for characters from
the modem.
Programs that do not properly implement the specified file
transfer protocol may cause sz to "hang" the port for a
minute or two. Every reported instance of this problem
has been corrected by using ZCOMM, Pro-YAM, or other pro-
gram with a correct implementation of the specified proto-
col.
Many programs claiming to support YMODEM only support XMO-
DEM with 1k blocks, and they often don't get that quite
right.
Pathnames are restricted to 127 characters. In XMODEM
single file mode, the pathname given on the command line
is still processed as described above. The ASCII option's
CR/LF to NL translation merely deletes CR's; undos(omen)
performs a more intelligent translation.
VMS VERSION
The VMS version does not set the file time.
VMS C Standard I/O and RMS may interact to modify file
contents unexpectedly.
The VMS version does not support invocation as rzCOMMAND .
The current VMS version does not support XMODEM, XMO-
DEM-1k, or YMODEM.
According to the VMS documentation, the buffered input
routine used on the VMS version of rz introduces a delay
of up to one second for each protocol transaction. This
delay may be significant for very short files. Removing
the "#define BUFREAD" line from rz.c will eliminate this
delay at the expense of increased CPU utilization.
The VMS version causes DCL to generate a random off the
wall error message under some error conditions; this is a
result of the incompatibility of the VMS "exit" function
with the Unix/MSDOS standard.
ZMODEM CAPABILITIES
Rz supports incoming ZMODEM binary (-b), ASCII (-a), pro-
tect (-p), clobber (-y), and append (-+) requests. The
default is protect (-p) and binary (-b).
The Unix versions support ZMODEM command execution.
FILES
rz.c, crctab.c, rbsb.c, zm.c, zmodem.h Unix source files.
rz.c, crctab.c, vrzsz.c, zm.c, zmodem.h, vmodem.h, vvmo-
dem.c, VMS source files.