SZ(1) UNIX System V SZ(1)
NAME
sx, sb, sz - XMODEM, YMODEM, ZMODEM file send
SYNOPSIS
sz [-+1abdefkLlNnopqTtuvyY] file ...
sb [-1adfkqtuv] file ...
sx [-1akqtuv] file
sz [-1oqtv] -c COMMAND
sz [-1oqtv] -i COMMAND
DESCRIPTION
Sz uses the ZMODEM, YMODEM or XMODEM error correcting protocol to send
one or more files over a serial port to a variety of programs running
under PC-DOS, CP/M, Unix, VMS, and other operating systems.
The first form of sz sends one or more files with ZMODEM protocol.
ZMODEM greatly simplifies file transfers compared to XMODEM. 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 intervention), Crash Recovery, selective
file transfers, and preservation of exact file date and length.
Output from another program may be piped to sz for transmission by
denoting standard input with "-":
ps -ef | 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:
ONAME=con ps -ef|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.
The second form is invoked as sb to batch send one or more files with
ZMODEM or YMODEM 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.
10/89 Page 1
SZ(1) UNIX System V SZ(1)
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.
The third form of sz is invoked as sx to send 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.
Iff sz is invoked with $SHELL set and iff that variable contains the
string rsh 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 correctly received the command,
before it is executed.
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:
+ Instruct the receiver to append transmitted data to an existing
file (ZMODEM only).
1 Use file descriptor 1 for ioctls and reads. By default, file
descriptor 0 is used.
a 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 (ZMODEM) Binary override: transfer file without any translation.
c COMMAND
Send COMMAND to the receiver for execution, return with COMMAND's
exit status.
d Change all instances of "." to "/" in the transmitted pathname.
Thus, C.dellB0000 (which is unacceptable to MSDOS or CP/M) is
transmitted as C/dellB0000. If the resultant filename has more
than 8 characters in the stem, a "." is inserted to allow a total
of eleven.
e Escape all control characters; normally XON, XOFF, DLE, CR-@-CR,
and Ctrl-X are escaped.
Page 2 10/89
SZ(1) UNIX System V SZ(1)
f Send Full pathname. Normally directory prefixes are stripped from
the transmitted filename.
i COMMAND
Send COMMAND to the receiver for execution, return Immediately upon
the receiving program's successful recption of the command.
k (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 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.
l 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.
n (ZMODEM) Send each file if destination file does not exist.
Overwrite destination file if source file is newer than the
destination file.
N (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 (ZMODEM) Disable automatic selection of 32 bit CRC.
p (ZMODEM) Protect existing destination files by skipping transfer if
the destination file exists.
q Quiet suppresses verbosity.
r (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.
t tim Change timeout to tim tenths of seconds.
u Unlink the file after successful transmission.
v Verbose causes a list of file names to be appended to /tmp/szlog .
More v's generate more output.
y Instruct a ZMODEM receiving program to overwrite any existing file
with the same name.
Y 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.
EXAMPLES
ZMODEM File Transfer
$ sz -a *.c
This single command transfers all .c files in the current Unix directory
with conversion (-a) to end of line conventions appropriate to the
receiving environment.
$ 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.
10/89 Page 3
SZ(1) UNIX System V SZ(1)
XMODEM File Transfer (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 than ZMODEM.
SEE ALSO
rz(1), minirb(1)
Compile time options required for various operating systems are described
in the source file.
FILES
32 bit CRC code courtesy Gary S. Brown.
sz.c, rbsb.c, zm.c, zmodem.h source files
/tmp/szlog stores debugging output (sz -vv)
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 interrupting 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 difference 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.
Many programs claiming to support YMODEM only support XMODEM with 1k
blocks, and they often don't get that quite right.
XMODEM transfers add up to 127 garbage bytes per file (1023 bytes with
XMODEM-k).
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.
Page 4 10/89
SZ(1) UNIX System V SZ(1)
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; perhaps 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.
Some 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.
10/89 Page 5