Section: User Commands (1)
sx, sb, sz - XMODEM, YMODEM, ZMODEM file send
uses the ZMODEM, YMODEM or XMODEM error correcting protocol to sendone or more files over a dial-in serial port to a variety of programs running underPC-DOS, CP/M, Unix, VMS, and other operating systems.
Whilerzis smart enough to be called fromcu(1),very few versions ofcu(1)are smart enough to allowszto work properly.Unix flavors of Professional-YAM are available for such dial-out application.
Szsends one or more files with ZMODEM protocol.
ZMODEMgreatly simplifies file transfers compared to XMODEM.In addition to a friendly user interface, ZMODEMprovides Personal Computer and other usersan efficient, accurate, and robust file transfer method.
ZMODEM provides completeEND-TO-ENDdata integrity between application programs.ZMODEM's 32 bit CRC catches errorsthat sneak into even the most advanced networks.
Advanced file management features includeAutoDownload (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 ofexact file date and length.
Output from another program may be piped toszfor transmission by denoting standard input with "-":ls -l | sz -
The program output is transmitted with the filename sPID.szwhere PID is the process ID of thesz
program.If the environment variableONAME
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
optioncauses the receiver to convert Unix newlines to PC-DOS carriage returnsand linefeeds.
Sbbatch sends one or more files with YMODEM or ZMODEM protocol.The initial ZMODEM initialization is not sent.When requested by the receiver,sbsupportsYMODEM-gwith "cbreak" tty mode, XON/XOFF flow control,and interrupt character set to CAN (^X).YMODEM-g(Professional-YAMgoption)increases throughput over error free channels(direct connection, X.PC, etc.)by not acknowledging each transmitted sector.
OnUnixsystems, 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 tothe output dataset,and the modify time and file modeare set accordingly.
Sxsends a singlefilewithXMODEMorXMODEM-1kprotocol(sometimes incorrectly called "ymodem").The user must supply the file name to both sending and receiving programs.
Ifszis invoked with $SHELL set and iff that variable contains thestringrsh,rbashorrksh(restricted shell),szoperates in restricted mode.Restricted mode restricts pathnames to the current directory andPUBDIR (usually /usr/spool/uucppublic) and/or subdirectoriesthereof.
The fourth form sends a single COMMAND to a ZMODEM receiver for execution.Szexits 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.Szexits as soon as the receiver has correctly 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 difficulty sending files,this command lets you see which character codes are beingeaten by the operating system.
Ifszis invoked with stdout and stderr to different datasets,Verbose is set to 2, causing frame by frame progress reportsto stderr.This may be disabled with theqoption.
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 knowwhat 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 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 receiverfor ZMODEM.
- -b, --binary
- (ZMODEM) Binary override: transfer file without any translation.
- -B NUMBER, --bufsize NUMBER
- Use a readbuffer of NUMBERbytes. Default ist 16384, which should be enoughfor most situations. If you have a slow machine or a bad disk interfaceor suffer from other hardware problems you might want to increasethe buffersize.-1orautouse a buffer large enough to buffer the whole file. Be careful with thisoption - things normally get worse, not better, if the machine startsto swap.
Using this option turns of memory mapping of the input file. Thisincreases 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 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 "." is inserted to allow a total of eleven.
This option enables the --full-pathoption.
- --delay-startup N
- WaitNseconds 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 samename already exists.
- -f, --full-path
- Send Full pathname.Normally directory prefixes are stripped from the transmittedfilename.
This is also turned on with to --dot-to-slashoption.
- -h, --help
- give help.
- -i COMMAND, --immediate-command COMMAND
- Send COMMAND to the receiver for execution, return immediatelyupon the receiving program's successful recption of the command.
- -k, --1k
- (XMODEM/YMODEM) Send files using 1024 byte blocksrather 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 (seconds).
- -l N, --framelen N
- Wait for the receiver to acknowledge correct data everyN(32 <= N <= 1024)characters.This may be used to avoid network overrun when XOFF flow control is lacking.
- -n, --newer
- (ZMODEM) Send each file ifdestination file does not exist.Overwrite destination file ifsource file is newer than the destination file.
- -N, --newer-or-longer
- (ZMODEM) Send each file ifdestination file does not exist.Overwrite destination file ifsource 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 sidedoesn't send anything, but increases performance (not much) anddecreases system load (reduces number of system calls by about 50percent).
Use this option with care.
- -p, --protect
- (ZMODEM) Protect existing destination files by skipping transfer if thedestination file exists.
- -q, --quiet
- Quiet suppresses verbosity.
- -R, --restricted
- Restricted mode: restricts pathnames to the current directory andPUBDIR (usually /usr/spool/uucppublic) and/or subdirectoriesthereof.
- -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 equalsthe length of the destination file.
- -s HH:MM, --stop-at HH:MM
- Stop transmission atHH hours, MMminutes. Another variant, using +N instead of HH:MM,stops transmission inNseconds.
- -S, --timesync
- enable timesync protocol support. See timesync.doc for further information.
This option is incompatible with standard zmodem. Use it with care.
- turn syslogging on or off. the default is set at configure time.This option is ignored if no syslog support is compiled in.
- -t TIM, --timeout TIM
- Change timeout toTIMtenths 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'thurt in the normal case (but be careful - ^P might be useful if connectedthrough a terminal server).
- Try to initiate a TCP/IP connection. lsz will ask the receiving zmodemto open a TCP/IP connection. All handshaking (which address / port touse) will be done by the zmodem programs.
You will normally not want to use this option as lrzsz is the onlyzmodem which understands what to do (private extension). You mightwant to use this option if the two programs are connected(stdin/out) over a slow or bad (not 8bit clean) network connection.
Use of this option imposes a security risk, somebody else could connectto the port in between. SeeSECURITYfor details.
- --tcp-client ADDRESS:PORT
- Act as a tcp/ip client: Connect to the given port.
See--tcp-serverfor more information.
- Act as a server: Open a socket, print out what to do, wait for connection.
You will normally not want to use this option as lrzsz is the onlyzmodem which understands what to do (private extension). You mightwant to use this if you have to use zmodem (for which reason whatever),and cannot use the--tcpoption oflsz(perhaps because your telnet doesn't allow to spawn a local programwith stdin/stdout connected to the remote side).
If you use this option you have to startlszwith the--tcp-client ADDRESS:PORToption.lrz will print the address and port on startup.
Use of this option imposes a security risk, somebody else could connectto the port in between. SeeSECURITYfor details.
- 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 filewith the same name.
- -Y, --overwrite-or-skip
- Instruct a ZMODEM receiving program to overwrite any existing filewith the same name,and to skip any source files that do have a file with the samepathname on the destination system.
- use ZMODEM protocol.
- -Z, --zmodem
- use ZMODEM protocol.
Restricted mode restricts pathnames to the current directoryand PUBDIR (usually /var/spool/uucppublic)and/or subdirectories thereof, and disables remote commandexecution.
Restricted mode is entered if the Roption is given or if lsz detects that it runs under a restrictedshell or if the environment variable ZMODEM_RESTRICTED is found.
Restricted mode can be turned of with the Uoption if not running under a restricted shell.
- Use of the
- --tcp-clientor--tcp-serveroptions imposes a security risk, as somebody else could connect tothe port before you do it, and grab your data. If there's strongdemand for a more secure mode i might introduce some sort ofpassword challenge.
- may be used to specify the number of nulls to send before a ZDATA frame.
- lsz recognizes a restricted shell if this variable includesrshorrksh
- lrz enters restricted mode if the variable is set.
- If this environment variable is set its content is used as the directory to place in the answer file to a timesync request.TMPUsed instead of TMPDIR if TMPDIR is not set. If neither TMPDIR norTMP is set /tmp will be used.
EXAMPLESZMODEM File Transfer
(Unix to DSZ/ZCOMM/Professional-YAM)% sz -a *.c
This single command transfers all .c files in the current Unix directorywith conversion(-a
)to end of line conventions appropriate to the receiving environment.With ZMODEM AutoDownload enabled, Professional-YAM and ZCOMMwill automatically recievethe files after performing a security 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 thecorresponding version on the receiving system, converting Unix toDOS text format.
$ sz -\Yan file1.c file2.c file3.c foo.h baz.h(for VMS)
ZMODEM Command Download(Unix to Professional-YAM)
sz -c "c:;cd /yam/dist"
sz -ya $(YD)/*.me
sz -yqb y*.exe
sz -c "cd /yam"
sz -i "!insms"
This Makefile fragment usesszto issue commands to Professional-YAM to change current disk and directory.Next,sztransfers the.mefiles from the $YD directory, commanding the receiver to overwrite the old filesand to convert from Unix end of line conventions to PC-DOS conventions.The third line transfers some.exefiles.The fourth and fifth lines command Pro-YAM tochange directory and execute a PC-DOS batch fileinsms .Since the batch file takes considerable time, the-iform is used to allowszto exit immediately.
XMODEM File Transfer(Unix to Crosstalk)
%sx -a foo.c
The above three commands transfer a single filefrom Unix to a PC and Crosstalk withsztranslating Unix newlines to DOS CR/LF.This combination is much slower and far less reliable than ZMODEM.
"Caught signal 99"indicates the program was not properly compiled,refer to "bibi(99)" in rbsb.c for details.
Compile time options required for various operating systems are described inthe source file.
The VMS version does not support wild cards.Because of VMS DCL, upper case option letters muse be representedby \ proceding the letter.
The current VMS version does not support XMODEM, XMODEM-1k, or YMODEM.
VMS C Standard I/O and RMS may interact to modify the file contents.
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, vvmodem.c,VMS source files.
/tmp/szlog stores debugging output (sz -vv)(szlog on VMS).
The command "sz -T file"exercises theAttn
sequence error recovery by commandingerrors with unterminated packets.The receiving program should complain five times aboutbinary data packets being too long.Each timesz
is interrupted,it should send a ZDATA header followed by another defective packet.If the receiver does not detect five long data packets,theAttn
sequence is not interrupting the sender, and theMyattn
must be modified.
After 5 packets,szstops the "transfer" andprints the total number of characters "sent" (Tcount).The difference between Tcount and 5120 represents the number of charactersstored in various buffers when the Attn sequence is generated.
from most versions of cu
(1) doesn't work because cu's receive processfightssz
for characters from the modem.
On at least one BSD system, sz would hang or exit when it got withina 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 protocolmay causeszto "hang" the port for a minute or two.This problem is corrected by usingZCOMM, Pro-YAM, or other program with a correct implementationof the specified protocol.
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.XMODEM-1k and YMODEM-1k transfers use 128 byte blocksto avoid extra padding.
YMODEM programs use the file length transmitted at the beginning of thetransfer to prune the file to the correct length; this may cause problems withsource files that grow during the course of the transfer.This problem does not pertain to ZMODEM transfers, which preserve the exactfile 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 usedwhen input is from pipes instead of acknowledging frames each 1024 bytes.If no files can be opened,szsends a ZMODEM command to echo a suitable complaint;perhaps it should check for the presence of at least one accessible file beforegetting 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 thedirection of high speed transmissson is reversed.The environment variable ZNULLS may be used to specify the number of nulls tosend before a ZDATA frame.Values of 101 for a 4.77 mHz PC and 124 for an AT are typical.
- ERROR MESSAGES
- SEE ALSO
- VMS VERSION
- TESTING FEATURE
This document was created byman2html,using the manual pages.