RZ(1)

📦 version 0.13.1, in arch rolling

hiii bestie!! welcome to the RZ(1) page from the General Commands Manual — it's giving serial-port file-transfer main character energy 💅✨

🌸 NAME 🌸

rx, rb, rz — XMODEM, YMODEM, ZMODEM (Batch) file receive 🎀

🦋 SYNOPSIS 🦋

rz [- +abeOpqRtuUvy]
rb [- +abqRtuUvy]
rx [- abceqRtuUv] file
[-][v]rzCOMMAND

💖 DESCRIPTION 💖

okay so 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. no cap, that's the whole vibe check 🫶

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. lowkey dramatic, but okay 💀

Rb receives file(s) with YMODEM, accepting either standard 128 byte sectors or 1024 byte sectors (lsb -k option). The user should determine when the 1024 byte block length actually improves throughput without causing lost data or even system crashes. bestie, please test carefully — “system crashes” is not a cute look 😭

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. cute little cleanup era 🧚

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.

bestie, heads up: up to 1023 garbage characters may be added to the received file. not iconic, but it's in the manual 💀

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. slay, it's piping time 🎀

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 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. restricted-shell realness — no absolute paths, no parent-dir nonsense, no editing existing files, and errors get yeeted 🚫

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. so if you're seeing those frame by frame progress reports on stderr, that's why — use q and breathe 💅

✨ OPTIONS ✨

okay bestie, here's the tea on literally every single flag this thing takes — no skipping, no cap, we're going through all of them 💅

  • -+, --append — appends the data you receive onto an existing file (ZMODEM only, and ASCII only).
  • -a, --ascii — converts files to Unix conventions by stripping carriage returns and all characters starting from the first Control Z (that's the CP/M end-of-file marker, bless its heart).
Deprecated, bestie 😭 — this uses the ZCNL file conversion option, which current ZMODEM docs mark as historic and straight-up recommend against. ASCII conversion also makes a transfer impossible to resume. It's kept alive for compatibility with 40-year-old peers, but new setups should transfer in binary mode and convert locally if you need to.
Note (this one's important 🙈): for compatibility with old senders, if a file mode arrives in the file metadata that includes file type bits (the historical full st_mode), that silently forces binary transfer for that file — overriding this option — and disables the lower-casing of received file names. This legacy behavior is deprecated too and will likely be removed in a future release.
  • -A, --segmentsize NNNN — tells the sender to turn on Segmented Streaming with a buffer / window of NNNN bytes. If the sender supports it, it'll ask for a ZACK packet every NNNN bytes. This somewhat limits throughput on perfect lines, and can vastly improve performance on faulty lines. NNNN can range from 0 to 65535 (protocol limitation, sorry). The default, '0', tells the sender that the receiver doesn't wish to use segmentation — but heads up, lsz (the sending program in this package) then uses its own default of 16kb anyway. Support for segmented streaming is not universal. 🦋
  • -b, --binary — binary (tell it like it is) file transfer override.
  • -B NUMBER, --bufsize NUMBER — buffers NUMBER bytes before writing to disk. Default is 32768, which should be enough for most situations. Got a slow machine, a bad disk interface, or just other hardware problems? You might wanna increase the buffersize.
  • -c, --with-crc — XMODEM only. Use 16 bit CRC (normally it's a one-byte checksum, so this is the glow-up).
  • -D, --null — sends output file data to /dev/null; for testing. (Unix only, obviously 💅)
  • --delay-startup N — waits N seconds before doing anything. Self-care.
  • -e, --escape — forces the sender to escape all control characters; normally only XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped.
  • -E, --rename — renames the incoming file if the target filename already exists. The new name gets a dot and a number (0..999) appended. (ZMODEM and YMODEM only.)
  • -h, --help — gives you the help screen. your moment of need 🫶
  • -H, --crc-check — (ZMODEM only; not usable with YMODEM, which lacks the required protocol exchange) accepts and transfers files even if the file lengths and/or the CRCs differ.
  • -J FILE, --journal FILE — appends a transfer-statistics line to FILE for each file received. The line is key=value pairs including timestamp, direction (dir=rx), filename, status, byte counts, duration, and throughput. The file gets created if it doesn't exist, and appended to on each invocation. it's giving receipts ✨
  • -m N, --min-bps N — stops transmission if the BPS-Rate (Bytes Per Second) falls below N for a certain time (see the --min-bps-time option). The check is per file: the timer resets at the start of each file.
  • -M N, --min-bps-time — used together with --min-bps. Default is 120 (seconds). The timeout is per file too: a slow transfer of one file does not count toward the next file's timeout.
  • -n, --newer — (ZMODEM and YMODEM) accepts the file if the destination file doesn't exist. Otherwise, accepts it and overwrites the destination if the source file is newer than the destination file.
  • -N, --newer-or-longer — (ZMODEM and YMODEM) accepts the file if the destination file doesn't exist. Otherwise, accepts it and overwrites the destination if the source file is newer or longer than the destination file.
  • -O, --disable-timeouts — disables the read timeout handling code. This makes lrz hang if the sender stops sending, but increases performance (a bit) and decreases system load by reducing the number of system calls by about 50 percent.
Use this option with care, bestie 😭 seriously.
  • --o-sync — opens output files in synchronous write mode. This may be useful if you experience errors due to lost interrupts when 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 system doesn't support O_SYNC.
  • -p, --protect — (ZMODEM) Protect: skips the file if the destination file exists. boundaries! 👑
  • -q, --quiet — quiet suppresses verbosity. shhh 🤫
  • -r, --resume — crash recovery mode. lrz tries to resume interrupted file transfers.
  • -R, --restricted — enters the very restricted mode. lrz will not create directories or files with a leading dot, and will not overwrite any existing file. This option always enables the very restricted mode, even if it was downgraded before (e.g. by combining it with the ZMODEM_RESTRICTED environment variable). See SECURITY for the security model and the description of the restricted levels.
  • --keep-incomplete — keeps partially received files when a transfer fails with an error. The default is to remove incomplete files; this option is the opt-in for keeping them, e.g. so you can --resume the transfer later, or when you're receiving on a private system where the partial data is worth more than the disk space. Interrupted transfers (Ctrl+C, modem hangup) always keep the partial file.
  • -s HH:MM, --stop-at HH:MM — stops transmission at HH hours, MM minutes. Another variant, using +N instead of HH:MM, stops transmission in N seconds. The deadline is tracked with one-second granularity because of how the check is implemented (the N argument is parsed before any data flows and compared against integer seconds afterwards); the transfer stops during the second after the deadline is reached, so a transfer stops within about N+1 to N+2 seconds. clock's ticking ⏰
  • --syslog[=off] — turns syslogging on or off. Syslog is on by default.
  • -t TIM, --timeout TIM — changes the timeout to TIM tenths of a second. This is ignored if timeout handling is turned off through the O option.
  • -U, --unrestrict — Removed. Security-relevant options cannot be turned off; see SECURITY and the HISTORICAL NOTES section. Use --keep-incomplete if you want failed transfers to leave the partial file in place. (rip to this one 💀)
  • --version — prints out the version number.
  • -v, --verbose — verbose output to stderr. With one v, a summary gets printed (file names, transfer result, error events). With two vs, progress reports are also shown. More vs are accepted but have no effect. Since version 0.13, detailed protocol debugging is available with --debug instead.
  • --debug=MODULES — enables debug output for the comma-separated list of MODULES on stderr. Known modules: "protocol" (ZMODEM frame state machine), "readline" (line reader: select/read calls, timeouts, hex dump), "transfer" (file transfer state machine), "windowhandling" (adaptive block length and window logic, ZMODEM sender only), "tty" (terminal mode changes). The special name "all" enables all. 🧚
  • -wN, --windowsize N — sets the window size to N.
  • -X, --xmodem — uses the XMODEM protocol.
  • -y, --overwrite — yes, clobber any existing files with the same name. (Ignored in XMODEM mode, where lrz always writes to the given pathname.)
  • --ymodem — uses the YMODEM protocol.
  • -Z, --zmodem — uses the ZMODEM protocol.

🔒 SECURITY 🔒

Contrary to the original ZMODEM, lrz defaults to restricted mode. Security-relevant options can be enabled but never disabled: restricted mode cannot be turned off, and the very restricted mode cannot be downgraded. no take-backs, bestie 💅

Remote command execution is always denied, in every mode. periodt.

lrz has two restricted levels:

restricted (the default)

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 (see --keep-incomplete for an exception).

very restricted

Additionally disables creation of subdirectories and files with a leading dot, and refuses to overwrite existing files instead of skipping them. Entered by setting the environment variable ZMODEM_RESTRICTED or giving the R option — in either case, and regardless of the order in which options are given. no loopholes 🎀

🌈 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 very restricted mode if the variable is set. Giving the R option also enables the very restricted mode.

📝 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. (not the personality! 😭)

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, but YMODEM with 128 byte blocks works properly. And 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. 🫠

32 bit CRC code courtesy Gary S. Brown. Directory creation code from John Gilmore's PD TAR program. legends only 👑

💀 BUGS 💀

okay so real talk, sometimes things get a little cursed 😭:

  • programs that don't actually implement the file transfer protocol properly? yeah, they can make lrz "hang" the port for a minute or two. every single reported instance of this has been fixed by, bestie, using a program that actually implements the specified protocol correctly 💅
  • and a lot of programs out here claiming they support YMODEM only support XMODEM with 1k blocks — and ngl they often don't even get that quite right 🙈
  • pathnames are restricted to 127 characters. in XMODEM single file mode, the pathname you hand over on the command line is still processed as described above. the file management options (-+, -E, -H, -n, -N, -p, -y) are straight-up ZMODEM features (with partial YMODEM support) — they are ignored in XMODEM mode. XMODEM always writes to the pathname given on the command line, and the restricted mode checks still apply ✨
  • the ASCII option's CR/LF to NL translation merely deletes CR's. that's it. that's the translation. no cap 🫠

✨ ZMODEM CAPABILITIES ✨

rz supports incoming ZMODEM requests for:

  • binary (-b)
  • ASCII (-a)
  • protect (-p)
  • clobber (-y)
  • append (-+)

the default vibe is protect (-p) and binary (-b) 👑

and on the Unix versions? ZMODEM command execution is supported 💅

🫶 CAVEATS 🫶

okay this part is important so listen up 🔥

the ZMODEM protocol uses 32-bit fields for file positions, which imposes a hard limit of 4 GiB on transfer size. periodt.

and on top of that: many ZMODEM implementations derived from the original Omen Technology codebase (including crzsz, rzsz, lrzszolderthanversion0.13, and other 1990s variants) — plus at least some independent implementation — use signed long internally. on 32-bit platforms that limits correct operation to files below 2 GiB.

lrz itself handles positions up to 4 GiB correctly, but interoperation with older or 32-bit senders may fail for files larger than 2 GiB. so like... it's not her fault, it's the sender's 😭

🌸 HISTORICAL NOTES 🌸

these options are gone, bestie. removed. no longer functional. using any of them prints an error message and exits — so don't try it, that's not the slay you think it is 💀

  • -C, --allow-commands — used to allow remote command execution via ZMODEM. removed because of weak security: it relied on the parent process to only set this option when the remote user is perfectly trustworthy 🚩
  • -S, --timesync — time synchronization. removed because no other still-available implementation supported it, and setting the local time would have required root privileges 👑
  • -U, --unrestrict — turned off restricted mode (which is impossible under a restricted shell anyway). removed because security-relevant options can't be turned off: whoever can pass -U can equally well just drop it from the command line, so the option provided no protection — only a trap. the one legitimate use, keeping partially received files on error, lives on as the --keep-incomplete option. go check SECURITY 🫶
  • PUBDIR — the PUBDIR environment variable and the whole associated public directory feature (restricting file transfers to PUBDIR, usually /var/spool/uucppublic) have been removed. bye 👋
  • -B auto — the auto argument to -B / --bufsize (which formerly buffered the entire file in memory) has been removed. no performance benefit was observed on modern systems, so it was giving nothing 🌈

and that's the whole page, bestie!! 🎀 this iconic little manual is brought to you by OMEN, and you're reading RZ(1) — the date at the bottom of the original is a whole mystery (the footer keeps it anonymous 🙈), but the vibes are timeless fr fr. go forth and transfer safely 💖✨🦋

📦 where this page comes from