NAME

SYNOPSIS

DESCRIPTION

This program uses error correcting protocols to receive
files over a dial-in serial port from a variety of programs running under
PC-DOS, CP/M,
Unix,
and other operating 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 implementations 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 information (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 contains one or more lower case letters.

Rx
receives a single
file
with XMODEM or XMODEM-1k protocol.
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 characters 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.

A typical use for this form is
rzrmail
which calls rmail(1)
to post mail to the user specified by the transmitted 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 pathnames
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 carriage 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 situations. 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 normally 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 disable 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;
normally 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.

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.

--o-sync

Open output files in synchronous write mode. This may be useful if you
experience errors due to lost interrupts if update (or bdflush or
whoever this daemon is called on your system) writes the buffers to the
disk.

This option is ignored and a warning is printed if your systems
doesn't support O_SYNC.

-p, --protect

(ZMODEM) Protect: skip file if destination file exists.

-q, --quiet

Quiet suppresses verbosity.

-r, --resume

Crash recovery mode. lrz tries to resume interrupted 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.

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

--tcp-client ADDRESS:PORT

Act as a tcp/ip client: Connect to the given port.

See
--tcp-server
for more information.

--tcp-server

Act as a server: Open a socket, print out what to do, wait for connection.

You will normally not want to use this option as lrzsz is the only
zmodem which understands what to do (private extension). You might
want to use this if you have to use zmodem (for which reason whatever),
and cannot use the
--tcp
option of
lsz
(perhaps because your telnet doesn't allow to spawn a local program
with stdin/stdout connected to the remote side).

If you use this option you have to start
lsz
with the
--tcp-client ADDRESS:PORT
option.
lrz will print the address and port on startup.

Use of this option imposes a security risk, somebody else could connect
to the port in between. See
SECURITY
for details.

-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 creation of subdirectories and invisible
files.

Restricted mode may be turned off with the
U
option, unless lrz runs under a restricted shell.

Use of the

--tcp-client
or
--tcp-server
options imposes a security risk, as somebody else could connect to
the port before you do it, and grab your data. If there's strong
demand for a more secure mode i might introduce some sort of
password challenge.

ENVIRONMENT

lrz uses the following environment variables:

SHELL

lrz recognizes a restricted shell if this variable includes
rsh
or
rksh
.

SEE ALSO

Compile time options required
for various operating systems are described in the
source file.

NOTES

Sending serial data to timesharing minicomputers
at sustained 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, consider 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 suspect this problem when you
can't send data to the Unix system at high speeds using ZMODEM,
YMODEM-1k or XMODEM-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").

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 program with a correct implementation
of the specified protocol.

Many programs claiming to support YMODEM only support XMODEM 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 support invocation as
rzCOMMAND .
The current VMS version does not support XMODEM, XMODEM-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.