Annotation of embedaddon/lrzsz/man/lsz.1, revision 1.1.1.1
1.1 misho 1: '\"
2: '\" Revision Level
3: '\" Last Delta 04-21-88
4: .TH SZ 1 2.6.1996 lrzsz-0.12b
5: .SH NAME
6: sx, sb, sz \- XMODEM, YMODEM, ZMODEM file send
7: .SH SYNOPSIS
8: sz
9: .RB [\- +8abdefkLlNnopqTtuvyY ]
10: .I file ...
11: .br
12: sb
13: .RB [\- adfkqtuv ]
14: .I file ...
15: .br
16: sx
17: .RB [\- akqtuv ]
18: .I file
19: .br
20: sz
21: .RB [\- oqtv ]
22: .B "-c COMMAND"
23: .br
24: sz
25: .RB [\- oqtv ]
26: .B "-i COMMAND"
27: .br
28: sz -TT
29: .SH DESCRIPTION
30: .B Sz
31: uses the ZMODEM, YMODEM or XMODEM error correcting protocol to send
32: one or more files over a dial-in serial port to a variety of programs running under
33: PC-DOS, CP/M, Unix, VMS, and other operating systems.
34:
35: While
36: .I rz
37: is smart enough to be called from
38: .I cu(1),
39: very few versions of
40: .I cu(1)
41: are smart enough to allow
42: .I sz
43: to work properly.
44: Unix flavors of Professional-YAM are available for such dial-out application.
45:
46:
47: .B Sz
48: sends one or more files with ZMODEM protocol.
49:
50: ZMODEM
51: greatly simplifies file transfers compared to XMODEM.
52: In addition to a friendly user interface, ZMODEM
53: provides Personal Computer and other users
54: an efficient, accurate, and robust file transfer method.
55:
56: ZMODEM provides complete
57: .B "END-TO-END"
58: data integrity between application programs.
59: ZMODEM's 32 bit CRC catches errors
60: that sneak into even the most advanced networks.
61:
62: Advanced file management features include
63: AutoDownload (Automatic file Download initiated without user intervention),
64: Display of individual and total file lengths and transmission time estimates,
65: Crash Recovery,
66: selective file transfers,
67: and preservation of
68: exact file date and length.
69:
70: Output from another program may be piped to
71: .B sz
72: for transmission by denoting standard input with "-":
73: .ce
74: ls -l | sz -
75: The program output is transmitted with the filename sPID.sz
76: where PID is the process ID of the
77: .B sz
78: program.
79: If the environment variable
80: .B ONAME
81: is set, that is used instead.
82: In this case, the Unix command:
83: .ce
84: ls -l | ONAME=con sz -ay -
85: will send a "file" to the PC-DOS console display.
86: The
87: .B -y
88: option instructs the receiver to open the file for writing unconditionally.
89: The
90: .B -a
91: option
92: causes the receiver to convert Unix newlines to PC-DOS carriage returns
93: and linefeeds.
94:
95:
96: .B Sb
97: batch sends one or more files with YMODEM or ZMODEM protocol.
98: The initial ZMODEM initialization is not sent.
99: When requested by the receiver,
100: .B sb
101: supports
102: .B YMODEM-g
103: with "cbreak" tty mode, XON/XOFF flow control,
104: and interrupt character set to CAN (^X).
105: .B YMODEM-g
106: (Professional-YAM
107: .B g
108: option)
109: increases throughput over error free channels
110: (direct connection, X.PC, etc.)
111: by not acknowledging each transmitted sector.
112:
113: On
114: .SM Unix
115: systems, additional information about the file is transmitted.
116: If the receiving program uses this information,
117: the transmitted file length controls the exact number of bytes written to
118: the output dataset,
119: and the modify time and file mode
120: are set accordingly.
121:
122:
123: .B Sx
124: sends a single
125: .I file
126: with
127: .B XMODEM
128: or
129: .B XMODEM-1k
130: protocol
131: (sometimes incorrectly called "ymodem").
132: The user must supply the file name to both sending and receiving programs.
133:
134: If
135: .B sz
136: is invoked with $SHELL set and iff that variable contains the
137: string
138: .I "rsh"
139: ,
140: .I "rbash"
141: or
142: .I "rksh"
143: (restricted shell),
144: .B sz
145: operates in restricted mode.
146: Restricted mode restricts pathnames to the current directory and
147: PUBDIR (usually /usr/spool/uucppublic) and/or subdirectories
148: thereof.
149:
150:
151: The fourth form sends a single COMMAND to a ZMODEM receiver for execution.
152: .B Sz
153: exits with the COMMAND return value.
154: If COMMAND includes spaces or characters special to the shell,
155: it must be quoted.
156:
157:
158: The fifth form sends a single COMMAND to a ZMODEM receiver for execution.
159: .B Sz
160: exits as soon as the receiver has correctly received the command,
161: before it is executed.
162:
163:
164: The sixth form (sz -TT)
165: attempts to output all 256 code combinations to the terminal.
166: In you are having difficulty sending files,
167: this command lets you see which character codes are being
168: eaten by the operating system.
169:
170:
171: If
172: .B sz
173: is invoked with stdout and stderr to different datasets,
174: Verbose is set to 2, causing frame by frame progress reports
175: to stderr.
176: This may be disabled with the
177: .B q
178: option.
179: .PP
180: The meanings of the available options are:
181: .PP
182: .PD 0
183: .TP
184: .B "-+, --append"
185: Instruct the receiver to append transmitted data to an existing file
186: (ZMODEM only).
187: .TP
188: .B "-2, --twostop"
189: use two stop bits (if possible). Do not use this unless you know
190: what you are doing.
191: .TP
192: .B "-8, --try-8k"
193: Try to go up to 8KB blocksize. This is incompatible with standard zmodem,
194: but a common extension in the bbs world. (ZMODEM only).
195: .TP
196: .B "--start-8k"
197: Start with 8KB blocksize. Like --try-8k.
198: .TP
199: .B "-a, --ascii"
200: Convert NL characters in the transmitted file to CR/LF.
201: This is done by the sender for XMODEM and YMODEM, by the receiver
202: for ZMODEM.
203: .TP
204: .B "-b, --binary"
205: (ZMODEM) Binary override: transfer file without any translation.
206: .TP
207: .B "-B NUMBER, --bufsize NUMBER"
208: Use a readbuffer of
209: .B NUMBER
210: bytes. Default ist 16384, which should be enough
211: for most situations. If you have a slow machine or a bad disk interface
212: or suffer from other hardware problems you might want to increase
213: the buffersize.
214: .B -1
215: or
216: .B auto
217: use a buffer large enough to buffer the whole file. Be careful with this
218: option - things normally get worse, not better, if the machine starts
219: to swap.
220:
221: Using this option turns of memory mapping of the input file. This
222: increases memory and cpu usage.
223: .TP
224: .B "-c COMMAND, --command COMMAND"
225: Send COMMAND to the receiver for execution, return with COMMAND\'s exit status.
226: .TP
227: .B "-C N, --command-tries N"
228: Retry to send command N times (default: 11).
229: .TP
230: .B "-d, --dot-to-slash"
231: Change all instances of "." to "/" in the transmitted pathname.
232: Thus, C.omenB0000 (which is unacceptable to MSDOS or CP/M)
233: is transmitted as C/omenB0000.
234: If the resultant filename has more than 8 characters in the stem,
235: a "." is inserted to allow a total of eleven.
236:
237: This option enables the
238: .B "--full-path"
239: option.
240: .TP
241: .B "--delay-startup N"
242: Wait
243: .B N
244: seconds before doing anything.
245: .TP
246: .B "-e, --escape"
247: Escape all control characters;
248: normally XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped.
249: .TP
250: .B"-E, --rename"
251: Force the sender to rename the new file if a file with the same
252: name already exists.
253: .TP
254: .B "-f, --full-path"
255: Send Full pathname.
256: Normally directory prefixes are stripped from the transmitted
257: filename.
258:
259: This is also turned on with to
260: .B "--dot-to-slash"
261: option.
262: .TP
263: .B "-h, --help"
264: give help.
265: .TP
266: .B "-i COMMAND, --immediate-command COMMAND"
267: Send COMMAND to the receiver for execution, return immediately
268: upon the receiving program's successful recption of the command.
269: .TP
270: .B "-k, --1k"
271: (XMODEM/YMODEM) Send files using 1024 byte blocks
272: rather than the default 128 byte blocks.
273: 1024 byte packets speed file transfers at high bit rates.
274: (ZMODEM streams the data for the best possible throughput.)
275: .TP
276: .B "-L N, --packetlen N"
277: Use ZMODEM sub-packets of length N.
278: A larger N (32 <= N <= 1024) gives slightly higher throughput,
279: a smaller N speeds error recovery.
280: The default is 128 below 300 baud, 256 above 300 baud, or 1024 above 2400 baud.
281: .TP
282: .B "-m N, --min-bps N"
283: Stop transmission if BPS-Rate (Bytes Per Second) falls below N for a
284: certain time (see --min-bps-time option).
285: .TP
286: .B "-M N, --min-bps-time"
287: Used together with --min-bps. Default is 120 (seconds).
288: .TP
289: .B "-l N, --framelen N"
290: Wait for the receiver to acknowledge correct data every
291: .B N
292: (32 <= N <= 1024)
293: characters.
294: This may be used to avoid network overrun when XOFF flow control is lacking.
295: .TP
296: .B "-n, --newer"
297: (ZMODEM) Send each file if
298: destination file does not exist.
299: Overwrite destination file if
300: source file is newer than the destination file.
301: .TP
302: .B "-N, --newer-or-longer"
303: (ZMODEM) Send each file if
304: destination file does not exist.
305: Overwrite destination file if
306: source file is newer or longer than the destination file.
307: .TP
308: .B "-o, --16-bit-crc"
309: (ZMODEM) Disable automatic selection of 32 bit CRC.
310: .TP
311: .B "-O, --disable-timeouts"
312: Disable read timeout handling. This makes lsz hang if the other side
313: doesn't send anything, but increases performance (not much) and
314: decreases system load (reduces number of system calls by about 50
315: percent).
316:
317: Use this option with care.
318: .TP
319: .B "-p, --protect"
320: (ZMODEM) Protect existing destination files by skipping transfer if the
321: destination file exists.
322: .TP
323: .B "-q, --quiet"
324: Quiet suppresses verbosity.
325: .TP
326: .B "-R, --restricted"
327: Restricted mode: restricts pathnames to the current directory and
328: PUBDIR (usually /usr/spool/uucppublic) and/or subdirectories
329: thereof.
330: .TP
331: .B "-r, --resume"
332: (ZMODEM) Resume interrupted file transfer.
333: If the source file is longer than the destination file,
334: the transfer commences at the offset in the source file that equals
335: the length of the destination file.
336: .TP
337: .B "-s HH:MM, --stop-at HH:MM"
338: Stop transmission at
339: .B HH
340: hours,
341: .B MM
342: minutes. Another variant, using
343: .B +N
344: instead of
345: .B HH:MM,
346: stops transmission in
347: .B N
348: seconds.
349: .TP
350: .B "-S, --timesync"
351: enable timesync protocol support. See timesync.doc for further
352: information.
353:
354: This option is incompatible with standard zmodem. Use it with care.
355: .TP
356: .B "--syslog[=off]"
357: turn syslogging on or off. the default is set at configure time.
358: This option is ignored if no syslog support is compiled in.
359: .TP
360: .B "-t TIM, --timeout TIM"
361: Change timeout to
362: .I TIM
363: tenths of seconds.
364: .TP
365: .B "-T, --turbo"
366: Do not escape certain characters (^P, ^P|0x80, telenet escape sequence
367: [CR + @]). This improves performance by about 1 percent and shouldn't
368: hurt in the normal case (but be careful - ^P might be useful if connected
369: through a terminal server).
370: .TP
371: .B "--tcp"
372: Try to initiate a TCP/IP connection. lsz will ask the receiving zmodem
373: to open a TCP/IP connection. All handshaking (which address / port to
374: use) will be done by the zmodem programs.
375:
376: You will normally not want to use this option as lrzsz is the only
377: zmodem which understands what to do (private extension). You might
378: want to use this option if the two programs are connected
379: (stdin/out) over a slow or bad (not 8bit clean) network connection.
380:
381: Use of this option imposes a security risk, somebody else could connect
382: to the port in between. See
383: .B SECURITY
384: for details.
385: .TP
386: .B "--tcp-client ADDRESS:PORT"
387: Act as a tcp/ip client: Connect to the given port.
388:
389: See
390: .B "--tcp-server"
391: for more information.
392:
393: .TP
394: .B "--tcp-server"
395: Act as a server: Open a socket, print out what to do, wait for connection.
396:
397: You will normally not want to use this option as lrzsz is the only
398: zmodem which understands what to do (private extension). You might
399: want to use this if you have to use zmodem (for which reason whatever),
400: and cannot use the
401: .B --tcp
402: option of
403: .I lsz
404: (perhaps because your telnet doesn't allow to spawn a local program
405: with stdin/stdout connected to the remote side).
406:
407: If you use this option you have to start
408: .I lsz
409: with the
410: .B --tcp-client ADDRESS:PORT
411: option.
412: .I lrz will print the address and port on startup.
413:
414: Use of this option imposes a security risk, somebody else could connect
415: to the port in between. See
416: .B SECURITY
417: for details.
418:
419: .TP
420: .B "-u"
421: Unlink the file after successful transmission.
422: .TP
423: .B "-U, --unrestrict"
424: Turn off restricted mode (this is not possible if running under a
425: restricted shell).
426: .TP
427: .B "-w N, --windowsize N"
428: Limit the transmit window size to N bytes (ZMODEM).
429: .TP
430: .B "-v, --verbose"
431: Verbose output to stderr. More v's generate more output.
432: .TP
433: .B "-X, --xmodem"
434: use XMODEM protocol.
435: .TP
436: .B "-y, --overwrite"
437: Instruct a ZMODEM receiving program to overwrite any existing file
438: with the same name.
439: .TP
440: .B "-Y, --overwrite-or-skip"
441: Instruct a ZMODEM receiving program to overwrite any existing file
442: with the same name,
443: and to skip any source files that do have a file with the same
444: pathname on the destination system.
445: .TP
446: .B "--ymodem"
447: use ZMODEM protocol.
448: .TP
449: .B "-Z, --zmodem"
450: use ZMODEM protocol.
451: .PD
452: .SH SECURITY
453: Restricted mode restricts pathnames to the current directory
454: and PUBDIR (usually /var/spool/uucppublic)
455: and/or subdirectories thereof, and disables remote command
456: execution.
457:
458: Restricted mode is entered if the
459: .B R
460: option is given or if lsz detects that it runs under a restricted
461: shell or if the environment variable ZMODEM_RESTRICTED is found.
462:
463: Restricted mode can be turned of with the
464: .B U
465: option if not running under a restricted shell.
466:
467: .TP
468: Use of the
469: .B --tcp-client
470: or
471: .B --tcp-server
472: options imposes a security risk, as somebody else could connect to
473: the port before you do it, and grab your data. If there's strong
474: demand for a more secure mode i might introduce some sort of
475: password challenge.
476:
477:
478: .SH ENVIRONMENT
479: .TP
480: .B ZNULLS
481: may be used to specify the number of nulls to send before a ZDATA frame.
482: .TP
483: .B SHELL
484: lsz recognizes a restricted shell if this variable includes
485: .I "rsh"
486: or
487: .I "rksh"
488: .TP
489: .B ZMODEM_RESTRICTED
490: lrz enters restricted mode if the variable is set.
491: .TP
492: .B TMPDIR
493: If this environment variable is set its content is used as the
494: directory to place in the answer file to a
495: .B timesync
496: request.
497: .B TMP
498: Used instead of TMPDIR if TMPDIR is not set. If neither TMPDIR nor
499: TMP is set /tmp will be used.
500: .SH EXAMPLES
501: .ne 7
502: .B "ZMODEM File Transfer"
503: (Unix to DSZ/ZCOMM/Professional-YAM)
504: .br
505: .B "% sz \-a *.c"
506: .br
507: This single command transfers all .c files in the current Unix directory
508: with conversion
509: .RB ( \-a )
510: to end of line conventions appropriate to the receiving environment.
511: With ZMODEM AutoDownload enabled, Professional-YAM and ZCOMM
512: will automatically recieve
513: the files after performing a security check.
514:
515: .br
516: .B "% sz \-Yan *.c *.h"
517: .br
518: Send only the .c and .h files that exist on both systems,
519: and are newer on the sending system than the
520: corresponding version on the receiving system, converting Unix to
521: DOS text format.
522: .br
523: .B
524: $ sz -\\Yan file1.c file2.c file3.c foo.h baz.h
525: .R
526: (for VMS)
527: .br
528:
529: .B "ZMODEM Command Download"
530: (Unix to Professional-YAM)
531: .br
532: cpszall:all
533: sz \-c "c:;cd /yam/dist"
534: sz \-ya $(YD)/*.me
535: sz \-yqb y*.exe
536: sz \-c "cd /yam"
537: sz \-i "!insms"
538: .br
539: This Makefile fragment uses
540: .B sz
541: to issue commands to Professional-YAM to change current disk and directory.
542: Next,
543: .B sz
544: transfers the
545: .I .me
546: files from the $YD directory, commanding the receiver to overwrite the old files
547: and to convert from Unix end of line conventions to PC-DOS conventions.
548: The third line transfers some
549: .I .exe
550: files.
551: The fourth and fifth lines command Pro-YAM to
552: change directory and execute a PC-DOS batch file
553: .I insms .
554: Since the batch file takes considerable time, the
555: .B "\-i"
556: form is used to allow
557: .B sz
558: to exit immediately.
559:
560: .B "XMODEM File Transfer"
561: (Unix to Crosstalk)
562: .br
563: %
564: .B "sx \-a foo.c"
565: .br
566: .B "ESC"
567: .br
568: .B "rx foo.c"
569: .br
570: The above three commands transfer a single file
571: from Unix to a PC and Crosstalk with
572: .I sz
573: translating Unix newlines to DOS CR/LF.
574: This combination is much slower and far less reliable than ZMODEM.
575: .SH ERROR MESSAGES
576: "Caught signal 99"
577: indicates the program was not properly compiled,
578: refer to "bibi(99)" in rbsb.c for details.
579: .SH SEE ALSO
580: rz(omen),
581: ZMODEM.DOC,
582: YMODEM.DOC,
583: Professional-YAM,
584: crc(omen),
585: sq(omen),
586: todos(omen),
587: tocpm(omen),
588: tomac(omen),
589: yam(omen)
590:
591: Compile time options required for various operating systems are described in
592: the source file.
593: .SH "VMS VERSION"
594: The VMS version does not support wild cards.
595: Because of VMS DCL, upper case option letters muse be represented
596: by \\ proceding the letter.
597:
598: The current VMS version does not support XMODEM, XMODEM-1k, or YMODEM.
599:
600: VMS C Standard I/O and RMS may interact to modify the file contents.
601: .SH FILES
602: 32 bit CRC code courtesy Gary S. Brown.
603:
604: sz.c, crctab.c, rbsb.c, zm.c, zmodem.h Unix source files
605:
606: sz.c, crctab.c, vrzsz.c, zm.c, zmodem.h, vmodem.h, vvmodem.c,
607: VMS source files.
608:
609: /tmp/szlog stores debugging output (sz -vv)
610: (szlog on VMS).
611: .SH "TESTING FEATURE"
612: The command "sz -T file"
613: exercises the
614: .B Attn
615: sequence error recovery by commanding
616: errors with unterminated packets.
617: The receiving program should complain five times about
618: binary data packets being too long.
619: Each time
620: .B sz
621: is interrupted,
622: it should send a ZDATA header followed by another defective packet.
623: If the receiver does not detect five long data packets,
624: the
625: .B Attn
626: sequence is not interrupting the sender, and the
627: .B Myattn
628: string in
629: .B sz.c
630: must be modified.
631:
632: After 5 packets,
633: .B sz
634: stops the "transfer" and
635: prints the total number of characters "sent" (Tcount).
636: The difference between Tcount and 5120 represents the number of characters
637: stored in various buffers when the Attn sequence is generated.
638: .SH BUGS
639: Calling
640: .I sz
641: from most versions of cu(1) doesn't work because cu's receive process
642: fights
643: .I sz
644: for characters from the modem.
645:
646: On at least one BSD system, sz would hang or exit when it got within
647: a few kilobytes of the end of file.
648: Using the "-w 8192" flag fixed the problem.
649: The real cause is unknown, perhaps a bug in the kernel TTY output routines.
650:
651: Programs that do not properly implement the specified file transfer protocol
652: may cause
653: .I sz
654: to "hang" the port for a minute or two.
655: This problem is corrected by using
656: ZCOMM, Pro-YAM, or other program with a correct implementation
657: of the specified protocol.
658:
659: Many programs claiming to support YMODEM only support XMODEM with 1k blocks,
660: and they often don't get that quite right.
661:
662: XMODEM transfers add up to 127 garbage bytes per file.
663: XMODEM-1k and YMODEM-1k transfers use 128 byte blocks
664: to avoid extra padding.
665:
666: YMODEM programs use the file length transmitted at the beginning of the
667: transfer to prune the file to the correct length; this may cause problems with
668: source files that grow during the course of the transfer.
669: This problem does not pertain to ZMODEM transfers, which preserve the exact
670: file length unconditionally.
671:
672: Most ZMODEM options are merely passed to the receiving program;
673: some do not implement all these options.
674:
675: Circular buffering and a ZMODEM sliding window should be used
676: when input is from pipes instead of acknowledging frames each 1024 bytes.
677: If no files can be opened,
678: .B sz
679: sends a ZMODEM command to echo a suitable complaint;
680: perhaps it should check for the presence of at least one accessible file before
681: getting hot and bothered.
682: The test mode leaves a zero length file on the receiving system.
683:
684: A few high speed modems have a firmware bug that drops characters when the
685: direction of high speed transmissson is reversed.
686: The environment variable ZNULLS may be used to specify the number of nulls to
687: send before a ZDATA frame.
688: Values of 101 for a 4.77 mHz PC and 124 for an AT are typical.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to lsz.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lrzsz / man