rt-thread/components/utilities/ZMODEM/SZ.1

'\" Revision Level 
'\" Last Delta     5-19-86
.TH SZ 1 OMEN
.SH NAME
sz \- XMODEM, YMODEM, ZMODEM Batch file Send
.SH SYNOPSIS
sz
.RB [\- +1adfknqTuvy ]
.I file ...
.br
sz -X
.RB [\- 1kquv ]
.I file
.br
sz
.RB [\- 1qv ]
.B "-c COMMAND"
.br
sz
.RB [\- 1qv ]
.B "-i COMMAND"
.SH DESCRIPTION
.B 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
.B sz
sends one or more files with ZMODEM or YMODEM batch protocol.
Normally, only the file name part of the pathname is transmitted.
On
.SM 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.

Output from another program may be piped to
.B sz
for transmission by specifying the
.B -1
option and denoting standard input by "-":
.ce
ps -ef | sz -
The program output is transmitted with the filename sPID.sz
where PID is the process ID of the
.B sz
program.
If the environment variable
.B ONAME
is set, that is used instead.
In this case, the Unix command:
.ce
ONAME=con ps -ef|sz -ay -
will send a "file" to the PC-DOS console display.
The
.B -y
bypasses the receiver\'s checking of the output filename.
The
.B -a
causes the receiver to convert Unix newlines to PC-DOS carriage returns
and linefeeds.

Unix
.B sz
supports
.B YMODEM-g
with "cbreak" tty mode, XON/XOFF flow control,
and the interrupt character set to CAN.
.B YMODEM-g
(Professional-YAM
.B g
option)
increases throughput over error free channels
(direct connection, X.PC, etc.)
by not acknowledging each transmitted sector.


The second form of
.B sz
uses the
.B -X
flag to send a single
.I file
with
.B XMODEM
protocol.
The user must supply the file name to both sending and receiving programs.

Iff
.B sz
is invoked with $SHELL set and iff that variable contains the
string
.I "rsh"
or
.I "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 third form sends a single COMMAND to the receiver for execution.
.B Sz
exits with the COMMAND return value.
If COMMAND includes spaces or characters special to the shell,
it must be quoted.

The fourth form sends a single COMMAND to the receiver for execution.
.B Sz
exits as soon as the receiver has 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
.B q
option.
.PP
The meanings of the available options are:
.PP
.PD 0
.TP
.B +
Force the receiver to append transmitted data to an existing file
(ZMODEM only).
.TP
.B 1
Use file descriptor 1 for ioctls and reads (Unix only).
By default, file descriptor 0 is used.
This option allows
.B sz
to be used with the
.I cu
~$
command.
.TP
.B 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.
.TP
.B "c COMMAND"
Send COMMAND to the receiver for execution, return with COMMAND\'s exit status.
.TP
.B "C N"
Make N attempts at ten second intervals
to read COMMAND\'s exit status before exiting.
.TP
.B d
Change all instances of "." to "/" in the transmitted pathname.
Thus, C.omenB0000 (which is unacceptable to MSDOS or CP/M)
is transmitted as C/omenB0000.
If the resultant filename has more than 8 characters in the stem,
a "." in inserted to allow a total of eleven.
.TP
.B f
Send Full pathname.
Normally directory prefixes are stripped from the transmitted
filename.
.TP
.B "i COMMAND"
Send COMMAND to the receiver for execution, return Immediately.
.TP
.B k
Send files using YMODEM 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.)
.TP
.B n
Instruct ZMODEM receiver to skip files if the length and modification times
of the source file and the file on the destination system are equal.
.TP
.B N
Instruct ZMODEM receiver to skip files if the length and CRC\'s
of the source file and the file on the destination system are equal.
.TP
.B q
Quiet suppresses verbosity.
.TP
.B r
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.
.TP
.B u
Unlink the file after successful transmission.
.TP
.B v
Verbose
causes a list of file
names to be appended to
/tmp/szlog .
More v's generate more output.
.TP
.B X
Send a single file with
.B XMODEM
protocol.
.TP
.B y
Force a ZMODEM receiving program to overwrite any existing file
with the same name.
.PD
.SH EXAMPLES
.ne 7
.B "ZMODEM File Transfer"
.br
.B "$ sz -a *.c"
.br
This single command transfers all .c files in the current Unix directory
with conversion
.RB ( -a )
to PC-DOS end of line conventions.
With ZMODEM AutoDownload enabled, Professional-YAM automatically recieves
the files after performing a security challenge.

.B "ZMODEM Command Download"
.br
 cpszall:all
    sz -c "c:;cd /yam/dist"
    sz -ya $(YD)/*.me
    sz -yqb y*.exe
    sz -c "cd /yam"
    sz -i "!insms"
.br
This Makefile fragment uses
.B sz
to issue commands to Professional-YAM to change current disk and directory.
Next,
.B sz
transfers the
.I .me
files from the $YD directory, commanding the receiver to overwrite the old files
and to convert from Unix end of line conventions to PC-DOS conventions.
The third line transfers some
.I .exe
files.
The fourth and fifth lines command Pro-YAM to
change directory and execute a PC-DOS batch file
.I insms .
Since the batch file takes considerable time, the
.B "-i"
form is used to allow
.B sz
to exit immediately.

.B "XMODEM File Transfer"
.br
$
.B "sz -Xa foo.c"
.br
.B "ESC"
.br
.B "rx foo.c"
.br
The above three commands transfer a single file
from Unix to a PC and Crosstalk XVI 3.6,
translating Unix newlines to DOS CR/LF.

.SH SEE ALSO
rz(omen),
ZMODEM.DOC,
YMODEM.DOC,
Professional-YAM manual,
IMP(CP/M),
cu(1),
sq(omen),
todos(omen),
tocpm(omen),
tomac(omen),
yam(omen)

Compile time options required for various operating systems are described in
the source file.
.SH "VMS VERSION"
The VMS version does not transmit the file date.
The VMS version calculates the file length by reading the file
and counting the bytes.

The VMS version does not support YMODEM-g or ZMODEM.

When VMS is lightly loaded, the response time may be too quick for MODEM7
unless the MODEM7
.B "q"
modifier is used.

The VMS C standard i/o package and RMS sometimes interact to modify
file contents unexpectedly.
.SH FILES
sz.c, rbsb.c, zm.c, zmodem.h source files

/tmp/szlog stores debugging output (sz -vv)
.SH "TESTING FEATURE"
The command "sz -T file"
exercises the
.B 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
.B 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
.B Attn
sequence is not interrupting the sender, and the
.B Myattn
string in
.B sz.c
must be modified.

After 5 packets,
.B 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.
.SH BUGS
XMODEM transfers add up to 127 spurious bytes per file.

Circular buffering and a ZMODEM sliding window should be used
when input is from pipes instead of acknowledging frames each 1024 bytes.
.B Sz
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.