SZ(1)
NAME
sx, sb, sz - XMODEM, YMODEM, ZMODEM file send
SYNOPSIS
sz [-+8abdefkLlNnopqTtuvyY] file ...
sb [-adfkqtuv] file ...
sx [-akqtuv] file
sz [-oqtv] -c COMMAND
sz [-oqtv] -i COMMAND
sz -TT
DESCRIPTION
Sz uses the ZMODEM, YMODEM or XMODEM error correcting pro-
tocol to send one or more files over a dial-in serial port
to a variety of programs running under PC-DOS, CP/M, Unix,
VMS, and other operating systems.
While rz is smart enough to be called from cu(1), very few
versions of cu(1) are smart enough to allow sz to work
properly. Unix flavors of Professional-YAM are available
for such dial-out application.
Sz sends one or more files with ZMODEM protocol.
ZMODEM greatly simplifies file transfers compared to XMO-
DEM. In addition to a friendly user interface, ZMODEM
provides Personal Computer and other users an efficient,
accurate, and robust file transfer method.
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.
Advanced file management features include AutoDownload
(Automatic file Download initiated without user interven-
tion), Display of individual and total file lengths and
transmission time estimates, Crash Recovery, selective
file transfers, and preservation of exact file date and
length.
Output from another program may be piped to sz for trans-
mission 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 line-
feeds.
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). YMODEM-g (Professional-YAM g
option) increases throughput over error free channels
(direct connection, X.PC, etc.) by not acknowledging each
transmitted sector.
On Unix systems, additional information about the file is
transmitted. If the receiving program uses this informa-
tion, the transmitted file length controls the exact num-
ber 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 pro-
grams.
If sz is invoked with $SHELL set and iff 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 PUBDIR
(usually /usr/spool/uucppublic) 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 cor-
rectly received the command, before it is executed.
The sixth form (sz -TT) attempts to output all 256 code
combinations to the terminal. In you are having diffi-
culty sending files, this command lets you see which char-
acter codes are being eaten by the operating system.
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.
The meanings of the available options are:
-+, --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).
--start-8k
Start with 8KB blocksize. Like --try-8k.
-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.
-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.
Using this option turns of memory mapping of the
input file. This increases memory and cpu usage.
-c COMMAND, --command COMMAND
Send COMMAND to the receiver for execution, return
with COMMAND's exit status.
-C N, --command-tries N
Retry to send command N times (default: 11).
-d, --dot-to-slash
Change all instances of "." to "/" in the transmit-
ted pathname. Thus, C.omenB0000 (which is unac-
ceptable to MSDOS or CP/M) is transmitted as
C/omenB0000. If the resultant filename has more
than 8 characters in the stem, a "." is inserted to
allow a total of eleven.
This option enables the --full-path option.
--delay-startup N
Wait N seconds before doing anything.
-e, --escape
Escape all control characters; normally XON, XOFF,
DLE, CR-@-CR, and Ctrl-X are escaped.
Force the sender to rename the new file if a file with the
same
name already exists.
-f, --full-path
Send Full pathname. Normally directory prefixes
are stripped from the transmitted filename.
This is also turned on with to --dot-to-slash
option.
-h, --help
give help.
-i COMMAND, --immediate-command COMMAND
Send COMMAND to the receiver for execution, return
immediately upon the receiving program's successful
recption of the command.
-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 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).
-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 con-
trol is lacking.
-n, --newer
(ZMODEM) Send each file if destination file does
not exist. Overwrite destination file if source
file is newer than the destination file.
-N, --newer-or-longer
(ZMODEM) Send each file if destination file does
not exist. Overwrite destination file if 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
Disable read timeout handling. This makes lsz hang
if the other side doesn't send anything, but
increases performance (not much) and decreases sys-
tem load (reduces number of system calls by about
50 percent).
Use this option with care.
-p, --protect
(ZMODEM) Protect existing destination files by
skipping transfer if the destination file exists.
-q, --quiet
Quiet suppresses verbosity.
-R, --restricted
Restricted mode: restricts pathnames to the current
directory and PUBDIR (usually /usr/spool/uucppub-
lic) and/or subdirectories thereof.
-r, --resume
(ZMODEM) Resume 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.
-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
enable timesync protocol support. See timesync.doc
for further information.
This option is incompatible with standard zmodem.
Use it with care.
--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.
-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 the file after successful transmission.
-U, --unrestrict
Turn off restricted mode (this is not possible if
running under a restricted shell).
-w N, --windowsize N
Limit the transmit window size to N bytes (ZMODEM).
-v, --verbose
Verbose output to stderr. More v's generate more
output.
-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.
--ymodem
use ZMODEM protocol.
-Z, --zmodem
use ZMODEM protocol.
SECURITY
Restricted mode restricts pathnames to the current direc-
tory and PUBDIR (usually /var/spool/uucppublic) and/or
subdirectories thereof, and disables remote command execu-
tion.
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 found.
Restricted mode can be turned of with the U option if not
running under a restricted shell.
ENVIRONMENT
ZNULLS may be used to specify the number of nulls to send
before a ZDATA frame.
SHELL lsz recognizes a restricted shell if this variable
includes rsh or rksh
ZMODEM_RESTRICTED
lrz enters restricted mode if the variable is set.
TMPDIR If this environment variable is set its content is
used as the directory to place in the answer file
to a timesync request. TMP Used instead of TMPDIR
if TMPDIR is not set. If neither TMPDIR nor TMP is
set /tmp will be used.
EXAMPLES
ZMODEM File Transfer (Unix to DSZ/ZCOMM/Professional-YAM)
% sz -a *.c
This single command transfers all .c files in the current
Unix directory with conversion (-a) to end of line conven-
tions appropriate to the receiving environment. With ZMO-
DEM AutoDownload enabled, Professional-YAM and ZCOMM will
automatically recieve the files after performing a secu-
rity check.
% sz -Yan *.c *.h
Send only the .c and .h files that exist on both systems,
and are newer on the sending system than the corresponding
version on the receiving system, converting Unix to DOS
text format.
$ sz -\Yan file1.c file2.c file3.c foo.h baz.h (R)(for
VMS)
ZMODEM Command Download (Unix to Professional-YAM)
cpszall:all
sz -c "c:;cd /yam/dist"
sz -ya $(YD)/*.me
sz -yqb y*.exe
sz -c "cd /yam"
sz -i "!insms"
This Makefile fragment uses sz to issue commands to Pro-
fessional-YAM to change current disk and directory. Next,
sz transfers the .me files from the $YD directory, com-
manding the receiver to overwrite the old files and to
convert from Unix end of line conventions to PC-DOS con-
ventions. The third line transfers some .exe files. The
fourth and fifth lines command Pro-YAM to change directory
and execute a PC-DOS batch file insms . Since the batch
file takes considerable time, the -i form is used to allow
sz to exit immediately.
XMODEM File Transfer (Unix to Crosstalk)
% sx -a foo.c
ESC
rx foo.c
The above three commands transfer a single file from Unix
to a PC and Crosstalk with sz translating Unix newlines to
DOS CR/LF. This combination is much slower and far less
reliable than ZMODEM.
ERROR MESSAGES
"Caught signal 99" indicates the program was not properly
compiled, refer to "bibi(99)" in rbsb.c for details.
SEE ALSO
rz(omen) ZMODEM.DOC, YMODEM.DOC, Professional-YAM,
crc(omen) sq(omen) todos(omen) tocpm(omen)
tomac(omen) yam(omen)
Compile time options required for various operating sys-
tems are described in the source file.
VMS VERSION
The VMS version does not support wild cards. Because of
VMS DCL, upper case option letters muse be represented by
\ proceding the letter.
The current VMS version does not support XMODEM, XMO-
DEM-1k, or YMODEM.
VMS C Standard I/O and RMS may interact to modify the file
contents.
FILES
32 bit CRC code courtesy Gary S. Brown.
sz.c, crctab.c, rbsb.c, zm.c, zmodem.h Unix source files
sz.c, crctab.c, vrzsz.c, zm.c, zmodem.h, vmodem.h, vvmo-
dem.c, VMS source files.
/tmp/szlog stores debugging output (sz -vv) (szlog on
VMS).
TESTING FEATURE
The command "sz -T file" exercises the Attn sequence error
recovery by commanding errors with unterminated packets.
The receiving program should complain five times about
binary data packets being too long. Each time sz is
interrupted, it should send a ZDATA header followed by
another defective packet. If the receiver does not detect
five long data packets, the Attn sequence is not inter-
rupting the sender, and the Myattn string in sz.c must be
modified.
After 5 packets, sz stops the "transfer" and prints the
total number of characters "sent" (Tcount). The differ-
ence between Tcount and 5120 represents the number of
characters stored in various buffers when the Attn
sequence is generated.
BUGS
Calling sz from most versions of cu(1) doesn't work
because cu's receive process fights sz for characters from
the modem.
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, perhaps a bug in the kernel TTY output routines.
Programs that do not properly implement the specified file
transfer protocol may cause sz to "hang" the port for a
minute or two. This problem is corrected by using ZCOMM,
Pro-YAM, or other program with a correct implementation of
the specified protocol.
Many programs claiming to support YMODEM only support XMO-
DEM with 1k blocks, and they often don't get that quite
right.
XMODEM transfers add up to 127 garbage bytes per file.
XMODEM-1k and YMODEM-1k transfers use 128 byte blocks to
avoid extra padding.
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.
Most ZMODEM options are merely passed to the receiving
program; some do not implement all these options.
Circular buffering and a ZMODEM sliding window should be
used when input is from pipes instead of acknowledging
frames each 1024 bytes. If no files can be opened, sz
sends a ZMODEM command to echo a suitable complaint; per-
haps it should check for the presence of at least one
accessible file before getting hot and bothered. The test
mode leaves a zero length file on the receiving system.
A few high speed modems have a firmware bug that drops
characters when the direction of high speed transmissson
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
are typical.