rz



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 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 ..."  com-
       mand 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 automati-
       cally 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  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  ‘‘COM-
       MAND 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 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 COM-
       MAND 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.
       -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 (seconds).
       -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 interrupted file trans-
              fers.
       -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 transmission 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 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 (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, 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 ZMO-
       DEM_RESTRICTED or give the R option. This disables creation  of  subdi-
       rectories 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  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 sys-
       tem 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 prop-
       erly.  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 creation 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 program with a correct implementation of  the  speci-
       fied 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 set the file time.

       VMS  C  Standard I/O and RMS may interact to modify file contents unex-
       pectedly.

       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 mes-
       sage under some error conditions; this is a result of the incompatibil-
       ity of the VMS "exit" function with the Unix/MSDOS standard.


ZMODEM CAPABILITIES

       Rz  supports  incoming  ZMODEM  binary  (-b), ASCII (-a), protect (-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,  vvmodem.c, VMS
       source files.



                                     OMEN                                RZ(1)

Man(1) output converted with man2html