Return to lrz.1 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lrzsz / man

lrzsz ver 0.12.20

    1: '\"
    2: '\" Revision Level 
    3: '\" Last Delta     04-22-88
    4: .TH RZ 1 OMEN
    5: .SH NAME
    6: rx, rb, rz \- XMODEM, YMODEM, ZMODEM (Batch) file receive
    7: .SH SYNOPSIS
    8: .B rz
    9: .RB [\- "\ +8abeOpqRtTuUvy" ]
   10: .br
   11: .B rb
   12: .RB [\- "\ +abqRtuUvy" ]
   13: .br
   14: .B rx
   15: .RB [\- "\ abceqRtuUv" ]
   16: .I file
   17: .br
   18: .RB [ \- ][ v ] rzCOMMAND
   19: .SH DESCRIPTION
   20: This program uses error correcting protocols to receive
   21: files over a dial-in serial port from a variety of programs running under
   22: PC-DOS, CP/M,
   23: .SM Unix,
   24: and other operating systems.
   25: It is invoked from a shell prompt
   26: manually, or automatically as a result of an
   27: "sz file ..." command given to the calling program.
   28: 
   29: While
   30: .I rz
   31: is smart enough to be called from
   32: .I cu(1),
   33: very few versions of
   34: .I cu(1)
   35: are smart enough to allow
   36: .I rz
   37: to work properly.
   38: Unix flavors of Professional-YAM are available for such dial-out application.
   39: 
   40: 
   41: .B Rz
   42: (Receive ZMODEM)
   43: receives files with the ZMODEM batch protocol.
   44: Pathnames are supplied by the sending program,
   45: and directories are made if necessary (and possible).
   46: Normally, the
   47: "rz" command is automatically issued by the calling ZMODEM program,
   48: but some defective ZMODEM implementations may require starting
   49: .I rz
   50: the old fashioned way.
   51: 
   52: 
   53: .B Rb
   54: receives file(s) with YMODEM,
   55: accepting either standard 128 byte sectors or
   56: 1024 byte sectors
   57: (YAM sb
   58: .B -k
   59: option).
   60: The user should determine when
   61: the 1024 byte block length
   62: actually improves throughput without causing lost data
   63: or even system crashes.
   64: 
   65: If True YMODEM (Omen Technology trademark) file information (file length, etc.)
   66: is received,
   67: the file length controls the number of bytes written to
   68: the output dataset,
   69: and the modify time and file mode
   70: (iff non zero)
   71: are set accordingly.
   72: 
   73: If no True YMODEM file information is received,
   74: slashes in the pathname are changed to underscore,
   75: and any trailing period in the pathname is eliminated.
   76: This conversion is useful for files received from CP/M systems.
   77: With YMODEM, each file name is converted to lower case
   78: unless it contains one or more lower case letters.
   79: 
   80: 
   81: .B Rx
   82: receives a single
   83: .I file
   84: with XMODEM or XMODEM-1k protocol.
   85: The user should determine when
   86: the 1024 byte block length
   87: actually improves throughput without causing problems.
   88: The user must supply the file name to both sending and receiving programs.
   89: Up to 1023 garbage characters may be added to the received file.
   90: 
   91: 
   92: .B Rz
   93: may be invoked as
   94: .B rzCOMMAND
   95: (with an optional leading \- as generated by login(1)).
   96: For each received file,
   97: .I rz
   98: will pipe the file to ``COMMAND filename''
   99: where filename is the name of the transmitted file
  100: with the file contents as standard input.
  101: 
  102: Each file transfer is acknowledged when COMMAND exits with 0 status.
  103: A non zero exit status terminates transfers.
  104: 
  105: A typical use for this form is
  106: .I rzrmail
  107: which calls rmail(1)
  108: to post mail to the user specified by the transmitted file name.
  109: For example, sending the file "caf" from a PC-DOS system to
  110: .I rzrmail
  111: on a
  112: .SM Unix
  113: system
  114: would result in the contents of the DOS file "caf" being mailed to user "caf".
  115: 
  116: On some
  117: .SM Unix
  118: systems, the login directory must contain a link to
  119: COMMAND as login sets SHELL=rsh which disallows absolute
  120: pathnames.
  121: If invoked with a leading ``v'',
  122: .I rz
  123: will be verbose (see 
  124: .B v
  125: option).
  126: The following entry works for
  127: .SM Unix
  128: SYS III/V:
  129: .ce
  130: rzrmail::5:1::/bin:/usr/local/rzrmail
  131: If the SHELL environment variable includes
  132: .I "rsh"
  133: ,
  134: .I "rbash"
  135: or
  136: .I "rksh"
  137: (restricted shell),
  138: .I rz
  139: will not accept absolute pathnames
  140: or references to a parent directory,
  141: will not modify an existing file, and
  142: removes any files received in error.
  143: 
  144: If
  145: .B rz
  146: is invoked with stdout and stderr to different datasets,
  147: Verbose is set to 2, causing frame by frame progress reports
  148: to stderr.
  149: This may be disabled with the
  150: .B q
  151: option.
  152: 
  153: .SH OPTIONS
  154: The meanings of the available options are:
  155: .PP
  156: .PD 0
  157: .TP
  158: .B "-+, --append"
  159: append received data to an existing file (ZMODEM, ASCII only).
  160: .TP
  161: .B "-a, --ascii"
  162: Convert files to
  163: .SM Unix
  164: conventions by stripping carriage returns and all characters
  165: beginning with the first Control Z (CP/M end of file).
  166: .TP
  167: .B "-b, --binary"
  168: Binary
  169: (tell it like it is)
  170: file transfer override.
  171: .TP
  172: .B "-B NUMBER, --bufsize NUMBER"
  173: Buffer 
  174: .B NUMBER
  175: bytes before writing to disk. Default ist 32768, which should be enough
  176: for most situations. If you have a slow machine or a bad disk interface
  177: or suffer from other hardware problems you might want to increase
  178: the buffersize.
  179: .B -1
  180: or
  181: .B auto
  182: use a buffer large enough to buffer the whole file. Be careful with this
  183: options - things normally get worse, not better, if the machine starts
  184: to swap.
  185: .TP
  186: .B "-c, --with-crc"
  187: XMODEM only. Use 16 bit CRC (normally a one byte checksum is used).
  188: .TP
  189: .B "-C, --allow-remote-commands"
  190: allow remote command execution (
  191: .B insecure
  192: ). This allows the sender to execute an arbitrary command through
  193: .B system
  194: () or
  195: .B execl
  196: (). Default is to disable this feature (?). This option is ignored
  197: if running in restricted mode.
  198: .TP
  199: .B "-D, --null"
  200: Output file data to /dev/null; for testing.
  201: (Unix only)
  202: .TP
  203: .B "--delay-startup N"
  204: Wait 
  205: .B N
  206: seconds before doing anything.
  207: .TP
  208: .B "-e, --escape"
  209: Force sender to escape all control characters;
  210: normally XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped.
  211: .TP
  212: .B "-E, --rename"
  213: Rename incoming file if target filename already exists. The new file
  214: name will have a dot and a number (0..999) appended.
  215: .TP
  216: .B "-h, --help"
  217: give help screen.
  218: .TP
  219: .B "-m N, --min-bps N"
  220: Stop transmission if BPS-Rate (Bytes Per Second) falls below N for a
  221: certain time (see --min-bps-time option).
  222: .TP
  223: .B "-M N, --min-bps-time"
  224: Used together with --min-bps. Default is 120 (seconds).
  225: .TP
  226: .B "-O, --disable-timeouts"
  227: Disable read timeout handling code. This makes lrz hang if the
  228: sender does not send any more, but increases performance (a bit)
  229: and decreases system load (through reducing the number of system
  230: calls by about 50 percent).
  231: 
  232: Use this option with care.
  233: .TP
  234: .B "--o-sync"
  235: Open output files in synchronous write mode. This may be useful if you
  236: experience errors due to lost interrupts if update (or bdflush or
  237: whoever this daemon is called on your system) writes the buffers to the
  238: disk.
  239: 
  240: This option is ignored and a warning is printed if your systems 
  241: doesn't support O_SYNC.
  242: .TP
  243: .B "-p, --protect"
  244: (ZMODEM) Protect: skip file if destination file exists.
  245: .TP
  246: .B "-q, --quiet"
  247: Quiet suppresses verbosity.
  248: .TP
  249: .B "-r, --resume"
  250: Crash recovery mode. lrz tries to resume interrupted file transfers.
  251: .TP
  252: .B "-R, --restricted"
  253: Enter more restricted mode. lrz will not create directories or files
  254: with a leading dot if this option is given twice.
  255: 
  256: See 
  257: .B SECURITY
  258: for mode information about restricted mode.
  259: .TP
  260: .B "-s HH:MM, --stop-at HH:MM"
  261: Stop transmission at
  262: .B HH
  263: hours,
  264: .B MM
  265: minutes. Another variant, using
  266: .B +N
  267: instead of
  268: .B HH:MM,
  269: stops transmission in
  270: .B N
  271: seconds.
  272: .TP
  273: .B "-S, --timesync"
  274: Request timesync packet from the sender. The sender sends its system time, 
  275: causing lrz to complain about more then 60 seconds difference. 
  276: 
  277: Lrz tries to set the local system time to the remote time if this option 
  278: is given twice (this fails if lrz is not run by root).
  279: 
  280: This option makes lrz incompatible with certain other ZModems. Don't
  281: use it unless you know what you are doing.
  282: .TP
  283: .B "--syslog[=off]"
  284: turn syslogging on or off. the default is set at configure time.
  285: This option is ignored if no syslog support is compiled in.
  286: .TP
  287: .B "-t TIM, --timeout TIM"
  288: Change timeout to
  289: .I TIM
  290: tenths of seconds. This is ignored if timeout handling is turned of
  291: through the 
  292: .B O 
  293: option.
  294: .TP
  295: .B "--tcp-client ADDRESS:PORT"
  296: Act as a tcp/ip client: Connect to the given port.
  297: 
  298: See 
  299: .B "--tcp-server"
  300: for more information.
  301: 
  302: .TP
  303: .B "--tcp-server"
  304: Act as a server: Open a socket, print out what to do, wait for connection.
  305: 
  306: You will normally not want to use this option as lrzsz is the only 
  307: zmodem which understands what to do (private extension). You might
  308: want to use this if you have to use zmodem (for which reason whatever),
  309: and cannot use the 
  310: .B --tcp
  311: option of
  312: .I lsz
  313: (perhaps because your telnet doesn't allow to spawn a local program
  314: with stdin/stdout connected to the remote side).
  315: 
  316: If you use this option you have to start 
  317: .I lsz 
  318: with the
  319: .B --tcp-client ADDRESS:PORT
  320: option. 
  321: .I lrz will print the address and port on startup.
  322: 
  323: Use of this option imposes a security risk, somebody else could connect
  324: to the port in between. See
  325: .B SECURITY 
  326: for details.
  327: .TP
  328: .B "-U, --unrestrict"
  329: turn off restricted mode (this is not possible if running under
  330: a restricted shell).
  331: .TP
  332: .B "--version"
  333: prints out version number.
  334: .TP
  335: .B "-v, --verbose"
  336: Verbose
  337: causes a list of file
  338: names to be appended to stderr.
  339: More v's generate more output.
  340: .TP
  341: .B "-wN, --windowsize N"
  342: Set window size to N.
  343: .TP
  344: .B "-X, --xmodem"
  345: use XMODEM protocol.
  346: .TP
  347: .B "-y, --overwrite"
  348: Yes, clobber any existing files with the same name.
  349: .TP
  350: .B "--ymodem"
  351: use YMODEM protocol.
  352: .TP
  353: .B "-Z, --zmodem"
  354: use ZMODEM protocol.
  355: .PD
  356: .ne 6
  357: .SH SECURITY
  358: Contrary to the original ZMODEM lrz defaults to restricted mode. In
  359: restricted mode lrz will not accept absolute pathnames or references 
  360: to a parent directory, will not modify an existing file, and
  361: removes any files received in error. Remote command execution is 
  362: disabled.
  363: 
  364: To use a more restricted mode set the environment variable 
  365: .B ZMODEM_RESTRICTED 
  366: or give the
  367: .B R
  368: option. This disables creation of subdirectories and invisible
  369: files.
  370: 
  371: Restricted mode may be turned off with the
  372: .B U 
  373: option, unless lrz runs under a restricted shell.
  374: 
  375: .TP
  376: Use of the 
  377: .B --tcp-client 
  378: or 
  379: .B --tcp-server 
  380: options imposes a security risk, as somebody else could connect to
  381: the port before you do it, and grab your data. If there's strong
  382: demand for a more secure mode i might introduce some sort of
  383: password challenge.
  384: 
  385: .SH ENVIRONMENT
  386: lrz uses the following environment variables:
  387: .TP
  388: .B SHELL
  389: lrz recognizes a restricted shell if this variable includes
  390: .I "rsh"
  391: or
  392: .I "rksh"
  393: \.
  394: .TP
  395: .B ZMODEM_RESTRICTED
  396: lrz enters the more restricted mode if the variable is set.
  397: .SH EXAMPLES
  398: .RE
  399: (Pro-YAM command)
  400: .RS
  401: .I <ALT-2>
  402: .br
  403: Pro-YAM Command:
  404: .I "sz *.h *.c"
  405: .br
  406: (This automatically invokes
  407: .I rz
  408: on the connected system.)
  409: .RE
  410: .SH SEE ALSO
  411: ZMODEM.DOC,
  412: YMODEM.DOC,
  413: Professional-YAM,
  414: crc(omen),
  415: sz(omen),
  416: usq(omen),
  417: undos(omen)
  418: 
  419: Compile time options required
  420: for various operating systems are described in the
  421: source file.
  422: .SH NOTES
  423: Sending serial data to timesharing minicomputers
  424: at sustained high speeds
  425: has been known to cause lockups, system halts, kernel panics,
  426: and occasional antisocial behaviour.
  427: When experimenting with high speed input to a
  428: system, consider rebooting the system
  429: if the file transfers are not successful,
  430: especially if the personality of the system appears altered.
  431: 
  432: The Unix "ulimit" parameter must be set high enough
  433: to permit large file transfers.
  434: 
  435: The TTY input buffering on some systems may not allow long blocks
  436: or streaming input at high speed.
  437: You should suspect this problem when you
  438: can't send data to the Unix system at high speeds using ZMODEM,
  439: YMODEM-1k or XMODEM-1k,
  440: when YMODEM with 128 byte blocks works properly.
  441: If the system's tty line handling is really broken, the serial port
  442: or the entire system may not survive the onslaught of long bursts
  443: of high speed data.
  444: 
  445: The DSZ or Pro-YAM
  446: .B "zmodem l"
  447: numeric parameter may be set to a value between 64 and 1024 to limit the
  448: burst length ("zmodem pl128").
  449: 
  450: 32 bit CRC code courtesy Gary S. Brown.
  451: Directory creation code from John Gilmore's PD TAR program.
  452: .SH BUGS
  453: Calling
  454: .I rz
  455: from most versions of cu(1) doesn't work because cu's receive process
  456: fights
  457: .I rz
  458: for characters from the modem.
  459: 
  460: Programs that do not properly implement the specified file transfer protocol
  461: may cause
  462: .I sz
  463: to "hang" the port for a minute or two.
  464: Every reported instance of this problem has been corrected by using
  465: ZCOMM, Pro-YAM, or other program with a correct implementation
  466: of the specified protocol.
  467: 
  468: Many programs claiming to support YMODEM only support XMODEM with 1k blocks,
  469: and they often don't get that quite right.
  470: 
  471: Pathnames are restricted to 127 characters.
  472: In XMODEM single file mode, the pathname given on the command line
  473: is still processed as described above.
  474: The ASCII option\'s CR/LF to NL translation merely deletes CR\'s;
  475: undos(omen) performs a more intelligent translation.
  476: .SH "VMS VERSION"
  477: The VMS version does not set the file time.
  478: 
  479: VMS C Standard I/O and RMS may interact to modify
  480: file contents unexpectedly.
  481: 
  482: The VMS version does not support invocation as
  483: .B rzCOMMAND .
  484: The current VMS version does not support XMODEM, XMODEM-1k, or YMODEM.
  485: 
  486: According to the VMS documentation,
  487: the buffered input routine used on the VMS version of
  488: .I rz
  489: introduces a delay
  490: of up to one second for each protocol transaction.
  491: This delay may be significant for very short files.
  492: Removing the "#define BUFREAD" line from rz.c will
  493: eliminate this delay at the expense of increased
  494: CPU utilization.
  495: 
  496: The VMS version causes DCL to generate a random off the wall
  497: error message under some error conditions; this is a result of
  498: the incompatibility of the VMS "exit" function with the
  499: Unix/MSDOS standard.
  500: .SH "ZMODEM CAPABILITIES"
  501: .I Rz
  502: supports incoming ZMODEM binary (-b), ASCII (-a),
  503: protect (-p),
  504: clobber (-y),
  505: and append (-+)
  506: requests.
  507: The default is protect (-p) and binary (-b).
  508: 
  509: The Unix versions support ZMODEM command execution.
  510: .SH FILES
  511: rz.c, crctab.c, rbsb.c, zm.c, zmodem.h Unix source files.
  512: 
  513: rz.c, crctab.c, vrzsz.c, zm.c, zmodem.h, vmodem.h, vvmodem.c,
  514: VMS source files.