SZ(1)

📦 version 0.13.1, in arch rolling

Manual: SZ(1) — General Commands Manual ✨

🌸 NAME 🌸

Bestie, meet sx, sb, and sz — the XMODEM, YMODEM, ZMODEM file send girlies. 💅

✨ SYNOPSIS ✨

sz [-+8abdefkLlNnopqTtuvyY] file ...
sb [-adfkqtuv] file ...
sx [-akqtuv] file
sz [-oqtv] -c COMMAND
sz [-oqtv] -i COMMAND

💖 DESCRIPTION 💖

Okay so sz uses the ZMODEM, YMODEM or XMODEM error correcting protocol to send one or more files over a dial-in serial port to a variety of programs running under multiple operating systems. It’s giving cross-platform file-transfer main character energy. 🦋

sz sends one or more files with ZMODEM protocol. Periodt.

ZMODEM greatly simplifies file transfers compared to XMODEM. In addition to a friendly user interface, ZMODEM gives Personal Computer and other users an efficient, accurate, and robust file transfer method. Lowkey iconic. 👑

ZMODEM provides complete END-TO-END data integrity between application programs. ZMODEM’s 32 bit CRC catches errors that sneak into even the most advanced networks. No cap, it’s that girl. 🔥

Advanced file management features include AutoDownload (Automatic file Download initiated without user intervention), Display of individual and total file lengths and transmission time estimates, Crash Recovery, selective file transfers, and preservation of exact file date and length. Obsessed, honestly.

Output from another program may be piped to sz for transmission by denoting standard input with -:

ls -l | sz -

The program output is transmitted with the filename sPID.sz where PID is the process ID of the sz program. If the environment variable ONAME is set, that is used instead. In this case, the Unix command:

ls -l | ONAME=con sz -ay -

will send a “file” to the PC-DOS console display. The -y option instructs the receiver to open the file for writing unconditionally. The -a option causes the receiver to convert Unix newlines to PC-DOS carriage returns and linefeeds.

sb batch sends one or more files with YMODEM or ZMODEM protocol. The initial ZMODEM initialization is not sent. When requested by the receiver (!!!), sb supports YMODEM-g with "cbreak" tty mode, XON/XOFF flow control, and interrupt character set to CAN (^X). This increases throughput over error free channels (direct connection, X.PC, etc.) by not acknowledging each transmitted sector. ⚡

The receiver included in this package does not request YMODEM-g. 💀

On Unix systems, additional information about the file is transmitted. If the receiving program uses this information, the transmitted file length controls the exact number of bytes written to the output dataset, and the modify time and file mode are set accordingly.

sx sends a single file with XMODEM or XMODEM-1k protocol (sometimes incorrectly called "ymodem"). The user must supply the file name to both sending and receiving programs.

If sz is invoked with $SHELL set and if that variable contains the string rsh , rbash or rksh (restricted shell), sz operates in restricted mode. Restricted mode restricts pathnames to the current directory and/or subdirectories thereof.

The fourth form sends a single COMMAND to a ZMODEM receiver for execution. sz exits with the COMMAND return value. If COMMAND includes spaces or characters special to the shell, it must be quoted.

The fifth form sends a single COMMAND to a ZMODEM receiver for execution. sz exits as soon as the receiver has correctly received the command, before it is executed. This form (and thus the -c/-i options) is deprecated and will be removed in a future release: it asks the receiving program to execute COMMAND, which only old ZMODEM implementations still do.

If sz 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, bestie:

  • -+, --append — Instruct the receiver to append transmitted data to an existing file (ZMODEM only).
  • -2, --twostop — Use two stop bits (if possible). Do not use this unless you know what you are doing. 🙈
  • -8, --try-8k — Try to go up to 8KB blocksize. This is incompatible with standard zmodem, but a common extension in the bbs world. (ZMODEM only).
  • -9 — Short form of --start-8k.
  • --start-8k — Start with 8KB blocksize. Like --try-8k.
  • -4, --try-4k — Try to go up to 4KB blocksize. (ZMODEM only).
  • -5 — Short form of --start-4k.
  • --start-4k — Start with 4KB blocksize. Like --try-4k.
  • -a, --ascii — Convert NL characters in the transmitted file to CR/LF. This is done by the sender for XMODEM and YMODEM, by the receiver for ZMODEM. Deprecated: for ZMODEM this requests the historic ZCNL conversion, which current ZMODEM documentation marks as deprecated. It is kept for compatibility with old peers; new setups should use binary transfer.
  • -b, --binary — (ZMODEM) Binary override: transfer file without any translation.
  • -B NUMBER, --bufsize NUMBER — Use a readbuffer of NUMBER bytes. Default ist 16384, 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 option — things normally get worse, not better, if the machine starts to swap. 😭
  • -c COMMAND, --command COMMAND — sends COMMAND over to the receiver so it runs it, and then you return with COMMAND's exit status. Deprecated alert 🚩 — this literally asks the receiving program to execute COMMAND. It's hanging around for compatibility with ancient ZMODEM implementations (OMEN zmodem and older lrz) that still execute received commands, and bestie, it will be removed in a future release. New setups should not use it. Modern receivers (including lrz) never execute commands and just answer with a failure status. 💀
  • -C N, --command-tries N — retry sending the command N times (default: 11). Only meaningful together with -c/-i, which are, as established, deprecated. 🙈
  • --delay-startup N — wait N seconds before doing literally anything. Caffeine break. ☕
  • --no-unixmode — sends a mode field of 0 in the ZMODEM file header instead of the file's Unix permission bits. By default, lsz transmits the full st_mode as returned by fstat(2), including permission bits (rwx) and setuid, setgid, and sticky bits. The recipient may — and honestly likely will — modify the mode before applying it. For example, lrz masks the received mode with 0777 in normal operation (stripping setuid, setgid, and sticky) and with 0666 under restricted shell (also stripping execute bits). Use --no-unixmode to leave permission selection entirely to the receiver's defaults (or to keep that information for yourself). 🎀
  • -e, --escape — escape all control characters; normally XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped. 🦋
  • -E, --rename — forces the sender to rename the new file if a file with the same name already exists. No overwriting drama, periodt. ✨
  • -f, --full-path — send the full pathname. Normally directory prefixes are stripped from the transmitted filename. Deprecated 🚩: current ZMODEM documentation states that a sender MUST NOT transmit absolute pathnames or .. components. This option is kept for compatibility with the historical behavior (OMEN sz and derivatives, and for mirroring directory trees with relative paths); a future release will continue to allow relative paths but will reject absolute paths and .. components with a fatal error. New setups should use plain relative filenames. 💅
  • -h, --help — give help. Iconic.
  • -H, --crc-check — (ZMODEM) accept and transfer files if the file lengths and/or the CRCs differ. Yolo checksum vibes.
  • -i COMMAND, --immediate-command COMMAND — sends COMMAND to the receiver for execution and returns immediately upon the receiving program's successful reception of the command. Deprecated 🚩 for the same reasons as -c; kept for compatibility with old ZMODEM implementations that still execute received commands, and it will be removed in a future release.
  • -J FILE, --journal FILE — appends a transfer-statistics line to FILE for each file sent. The line is made of key=value pairs including timestamp, direction (dir=tx), filename, status, byte counts, duration, and throughput. The file is created if it doesn't exist and appended to on each invocation. Receipts! 🧾✨
  • -k, --1k — (XMODEM/YMODEM) send files using 1024 byte blocks rather than the default 128 byte blocks. 1024 byte packets speed file transfers at high bit rates. (ZMODEM streams the data for the best possible throughput.) 🔥
  • -L N, --packetlen N — use ZMODEM sub-packets of length N. A larger N (32 <= N <= 1024) gives slightly higher throughput; a smaller N speeds error recovery. The default is 128 below 300 baud, 256 above 300 baud, or 1024 above 2400 baud. 🎚️
  • -m N, --min-bps N — stop 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: a slow transfer of one file does not count toward the next file's timeout. ⏱️
  • -l N, --framelen N — wait for the receiver to acknowledge correct data every N (32 <= N <= 1024) characters. This may be used to avoid network overrun when XOFF flow control is lacking. 🫶
  • --sync-transfer — (ZMODEM) integrity mode: wait for the receiver's acknowledgement after every data sub-packet (a ZCRCW round trip) instead of streaming. On a packetized transport an entire sub-packet together with its terminator and CRC can be silently swallowed, which plain streaming cannot detect (the CRC is position independent and the frame position is only checked at the start of a ZDATA frame). The cost is one round trip per sub-packet, causing a substantial throughput loss on slow or high-latency lines. This option is only needed on transports that can silently drop a contiguous chunk of the byte stream — for example a packet radio or other datagram link that loses packets without retransmitting them, or a line that overruns its buffer when flow control fails. It is pointless on transports that hide packet loss by retransmitting internally, so that no loss reaches the byte stream (TCP, ISDN, X.25), and wasteful on transports that only corrupt individual characters (noisy modem or serial lines): there the CRC catches the damage and the normal resync heals it, streaming is safe and faster. 🛡️
  • -n, --newer — (ZMODEM) send each file if the destination file does not exist. Overwrite the destination file if the source file is newer than the destination file. 🗓️
  • -N, --newer-or-longer — (ZMODEM) send each file if the destination file does not exist. Overwrite the destination file if the source file is newer or longer than the destination file. 📏
  • -o, --16-bit-crc — (ZMODEM) disable automatic selection of 32 bit CRC.
  • -O, --disable-timeouts — disables read timeout handling. This makes lsz hang if the other side doesn't send anything, but increases performance (not much) and decreases system load (reduces number of system calls by about 50 percent).
Use this option with care. 😭 Seriously.
  • -p, --protect — (ZMODEM) protect existing destination files by skipping the transfer if the destination file exists. 🛟
  • -q, --quiet — quiet suppresses verbosity. Shhh. 🤫
  • -R, --restricted — restricted mode: restricts pathnames to the current directory and/or subdirectories thereof. See SECURITY. 🔒
  • -r, --resume — (ZMODEM) resume an interrupted file transfer. If the source file is longer than the destination file, the transfer commences at the offset in the source file that equals the length of the destination file. Pick up where you left off, bestie. ⏯️
  • -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. The deadline is tracked with a one-second granularity because of the way 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. ⏰
  • --syslog[=off] — turn syslogging on or off. Syslog is on by default. 📝
  • -t TIM, --timeout TIM — change timeout to TIM tenths of seconds.
  • -T, --turbo — do not escape certain characters (^P, ^P|0x80, telenet escape sequence [CR + @]). This improves performance by about 1 percent and shouldn't hurt in the normal case (but be careful — ^P might be useful if connected through a terminal server). 🏎️💨
  • -u, --unlink — unlink the file after successful transmission. Gone, reduced to atoms. 🗑️
  • -U, --unrestrict — removed. See SECURITY.
  • -w N, --windowsize N — limit the transmit window size to N bytes (ZMODEM). 🪟
  • -v, --verbose — verbose output to stderr. With one v, a summary (file names, transfer result, error events) is printed. 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 — enable 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 only), "tty" (terminal mode changes). The special name "all" enables all. 🔍
  • -X, --xmodem — use XMODEM protocol.
  • -y, --overwrite — instruct a ZMODEM receiving program to overwrite any existing file with the same name. 💥
  • -Y, --overwrite-or-skip — instruct a ZMODEM receiving program to overwrite any existing file with the same name, and to skip any source files that do have a file with the same pathname on the destination system. The duality of girl. 🎭
  • -g, --ymodem — use ZMODEM protocol.
  • -Z, --zmodem — use ZMODEM protocol.

🔒 SECURITY 🔒

Restricted mode restricts pathnames to the current directory and/or subdirectories thereof: absolute pathnames and references to a parent directory are not sent, and lsz refuses to send remote commands (the -c/-i options). 🚫

Restricted mode is entered if the R option is given, or if lsz detects that it runs under a restricted shell, or if the environment variable ZMODEM_RESTRICTED is set. Restricted mode cannot be turned off; the U option has been removed (see HISTORICAL NOTES). No take-backs, no escape hatch. 🔐

🌿 ENVIRONMENT 🌿

  • ZNULLS — may be used to specify the number of nulls to send before a ZDATA frame. This is a 1980s modem workaround and of questionable benefit today. It is kept for compatibility. 👵📻
  • SHELL — lsz recognizes a restricted shell if this variable includes rsh or rksh. 🐚
  • ZMODEM_RESTRICTED — lsz enters restricted mode if the variable is set. 🚧

✨ EXAMPLES ✨

🦋 ZMODEM File Transfer 🦋

% sz -a *.c

Okay so this one command sends, like, every .c file in the current directory, and the -a is doing the conversion thing — it converts to whatever end-of-line conventions the receiving environment wants. Slay. ✨

% sz -Yan *.c *.h

This one's pickier, and honestly she's iconic for it: it sends only the .c and .h files that exist on both systems, and that are newer on the sending system than the matching version on the receiving system. Plus it converts Unix to DOS text format if needed. Selective queen behavior 💅

🌸 XMODEM File Transfer 🌸

% sx -a foo.c
ESC
rx foo.c

These three commands (yes, that middle line is literally ESC — it's part of the sequence, don't skip it 🙈) move a single file from the local machine to the remote one, while sz translates Unix newlines to DOS CR/LF.

Bestie, warning: this combo is much slower and far less reliable than ZMODEM. Like, XMODEM is giving vintage typewriter energy. Use it if you must, but know what you're signing up for. 😭

💀 ERROR MESSAGES 💀

If you ever see "Caught signal 99" — yeah, that means the program was not properly compiled. For the details, go look at "bibi(99)" in rbsb.c. Iykyk. 🫶

👀 SEE ALSO 👀

  • lrz
  • ZMODEM.DOC
  • YMODEM.DOC

Also: the compile time options required for the various operating systems are described in the source file. Go read the source, bestie, it's good for you 🌈

🐛 BUGS 🐛

Prepare yourself, this list is a journey 🎢

  • On at least one BSD system, sz would hang or exit when it got within a few kilobytes of the end of file. Using the -w 8192 flag fixed the problem. The real cause is unknown — maybe a bug in the kernel TTY output routines. Spooky. 👻
  • Programs that don't properly implement the specified file transfer protocol may cause sz to "hang" the port for a minute or two. Not her fault, she's doing her best. 😤
  • Many programs claiming to support YMODEM only support XMODEM with 1k blocks, and they often don't get that quite right. Fake fans, honestly. 💀
  • XMODEM transfers add up to 127 garbage bytes per file. XMODEM-1k and YMODEM-1k transfers use 128 byte blocks to avoid that extra padding. Little byte crumbs everywhere, no thank you. 🍓
  • YMODEM programs use the file length transmitted at the beginning of the transfer to prune the file to the correct length — this may cause problems with source files that grow during the course of the transfer. This problem does not pertain to ZMODEM transfers, which preserve the exact file length unconditionally. ZMODEM stays winning 👑
  • Most ZMODEM options are merely passed to the receiving program; some do not implement all these options. So like, she forwards the message, but the other side might leave it on read. 🙈
  • Circular buffering and a ZMODEM sliding window should be used when input is from pipes instead of acknowledging frames each 1024 bytes. And if no files can be opened, sz sends a ZMODEM command to echo a suitable complaint — perhaps it should check for the presence of at least one accessible file before getting hot and bothered. Valid critique tbh 🔥

🩹 WORKAROUNDS 🩹

A few high speed modems have (had?) a firmware bug that drops characters when the direction of high speed transmission is reversed. The environment variable ZNULLS may be used to specify the number of nulls to send before a ZDATA frame. Values of 101 for a 4.77 MHz PC and 124 for an AT were typical. Vintage tech, vintage fixes 🕰️

⚠️ CAVEATS ⚠️

Okay this is the important part, so like, pay attention bestie 🫶

The ZMODEM protocol uses 32-bit fields for file positions, imposing a hard limit of 4 GiB on transfer size.

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

lsz itself handles positions up to 4 GiB correctly, but interoperability with older or 32-bit receivers may fail for files larger than 2 GiB.

lsz prints a warning when sending files larger than 2 GiB; use -q to suppress it.

fr fr, if you're yeeting multi-gigabyte files through ancient ZMODEM code, that's your villain origin story 💀

🦋 HISTORICAL NOTES 🦋

Grab a snack, we're doing lore 🍓

When a receiver ends the session with a ZABORT frame (or ZFERR, which the ZMODEM documentation defines as equivalent), lsz replies with the ZFIN sequence the documentation requires and then ends the session cleanly. Older lsz versions, as well as OMEN-derived senders, answered with the cancel sequence instead.

The outcome — transfer aborted, exit status 0x80 — is the same, so this only matters to peers that inspect the reply. So like, same ending, different goodbye text. ✨

💅 Gone but not forgotten (rip to these) 💅

The following options and features have been removed and are no longer functional. Using the options prints an error message and exits.

  • -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 (impossible under a restricted shell). Removed because security-relevant options cannot be turned off: whoever can pass -U can equally well drop it from the command line, so the option provided no protection — only a trap. See SECURITY.
  • PUBDIR — The PUBDIR environment variable and the associated public directory feature (restricting file transfers to PUBDIR, usually /var/spool/uucppublic) have been removed.
  • -d, --dot-to-slash — Converted dots to slashes in pathnames and truncated filenames to 8.3 format for MS-DOS / CP-M compatibility. Removed because these systems are obsolete. Use -f / --full-path to send full pathnames.

🌸 and that's the whole page, bestie 🌸

This one's from lrzsz-0.12b, dated 2.6.1996 — yes, she's vintage, she's been through things, and she's still serving. Go transfer some files responsibly. You got this 💖🎀

📦 where this page comes from