RZ(1)                                                       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  prob-
       lems.   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.

       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.
       --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 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.
       --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  what-
              ever), and cannot use the --tcp option of lsz (per-
              haps 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,  some-
              body 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 cre-
       ation 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

       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.

                               OMEN                             1