0000: 27 5c 22 0a 27 5c 22 20 43 6f 70 79 72 69 67 68 '\".'\" Copyrigh
0010: 74 20 28 63 29 20 32 30 30 35 2d 32 30 30 36 20 t (c) 2005-2006
0020: 44 6f 6e 61 6c 20 4b 2e 20 46 65 6c 6c 6f 77 73 Donal K. Fellows
0030: 0a 27 5c 22 0a 27 5c 22 20 53 65 65 20 74 68 65 .'\".'\" See the
0040: 20 66 69 6c 65 20 22 6c 69 63 65 6e 73 65 2e 74 file "license.t
0050: 65 72 6d 73 22 20 66 6f 72 20 69 6e 66 6f 72 6d erms" for inform
0060: 61 74 69 6f 6e 20 6f 6e 20 75 73 61 67 65 20 61 ation on usage a
0070: 6e 64 20 72 65 64 69 73 74 72 69 62 75 74 69 6f nd redistributio
0080: 6e 0a 27 5c 22 20 6f 66 20 74 68 69 73 20 66 69 n.'\" of this fi
0090: 6c 65 2c 20 61 6e 64 20 66 6f 72 20 61 20 44 49 le, and for a DI
00a0: 53 43 4c 41 49 4d 45 52 20 4f 46 20 41 4c 4c 20 SCLAIMER OF ALL
00b0: 57 41 52 52 41 4e 54 49 45 53 2e 0a 2e 54 48 20 WARRANTIES...TH
00c0: 63 68 61 6e 20 6e 20 38 2e 35 20 54 63 6c 20 22 chan n 8.5 Tcl "
00d0: 54 63 6c 20 42 75 69 6c 74 2d 49 6e 20 43 6f 6d Tcl Built-In Com
00e0: 6d 61 6e 64 73 22 0a 2e 73 6f 20 6d 61 6e 2e 6d mands"..so man.m
00f0: 61 63 72 6f 73 0a 2e 42 53 0a 27 5c 22 20 4e 6f acros..BS.'\" No
0100: 74 65 3a 20 20 64 6f 20 6e 6f 74 20 6d 6f 64 69 te: do not modi
0110: 66 79 20 74 68 65 20 2e 53 48 20 4e 41 4d 45 20 fy the .SH NAME
0120: 6c 69 6e 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 line immediately
0130: 20 62 65 6c 6f 77 21 0a 2e 53 48 20 4e 41 4d 45 below!..SH NAME
0140: 0a 63 68 61 6e 20 5c 2d 20 52 65 61 64 2c 20 77 .chan \- Read, w
0150: 72 69 74 65 20 61 6e 64 20 6d 61 6e 69 70 75 6c rite and manipul
0160: 61 74 65 20 63 68 61 6e 6e 65 6c 73 0a 2e 53 48 ate channels..SH
0170: 20 53 59 4e 4f 50 53 49 53 0a 5c 66 42 63 68 61 SYNOPSIS.\fBcha
0180: 6e 20 5c 66 49 6f 70 74 69 6f 6e 5c 66 52 20 3f n \fIoption\fR ?
0190: 5c 66 49 61 72 67 20 61 72 67 20 2e 2e 2e 5c 66 \fIarg arg ...\f
01a0: 52 3f 0a 2e 42 45 0a 2e 53 48 20 44 45 53 43 52 R?..BE..SH DESCR
01b0: 49 50 54 49 4f 4e 0a 2e 50 50 0a 54 68 69 73 20 IPTION..PP.This
01c0: 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65 73 command provides
01d0: 20 73 65 76 65 72 61 6c 20 6f 70 65 72 61 74 69 several operati
01e0: 6f 6e 73 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ons for reading
01f0: 66 72 6f 6d 2c 20 77 72 69 74 69 6e 67 20 74 6f from, writing to
0200: 0a 61 6e 64 20 6f 74 68 65 72 77 69 73 65 20 6d .and otherwise m
0210: 61 6e 69 70 75 6c 61 74 69 6e 67 20 6f 70 65 6e anipulating open
0220: 20 63 68 61 6e 6e 65 6c 73 20 28 73 75 63 68 20 channels (such
0230: 61 73 20 68 61 76 65 20 62 65 65 6e 20 63 72 65 as have been cre
0240: 61 74 65 64 0a 77 69 74 68 20 74 68 65 20 5c 66 ated.with the \f
0250: 42 6f 70 65 6e 5c 66 52 20 61 6e 64 20 5c 66 42 Bopen\fR and \fB
0260: 73 6f 63 6b 65 74 5c 66 52 20 63 6f 6d 6d 61 6e socket\fR comman
0270: 64 73 2c 20 6f 72 20 74 68 65 20 64 65 66 61 75 ds, or the defau
0280: 6c 74 20 6e 61 6d 65 64 0a 63 68 61 6e 6e 65 6c lt named.channel
0290: 73 20 5c 66 42 73 74 64 69 6e 5c 66 52 2c 20 5c s \fBstdin\fR, \
02a0: 66 42 73 74 64 6f 75 74 5c 66 52 20 6f 72 20 5c fBstdout\fR or \
02b0: 66 42 73 74 64 65 72 72 5c 66 52 20 77 68 69 63 fBstderr\fR whic
02c0: 68 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 0a h correspond to.
02d0: 74 68 65 20 70 72 6f 63 65 73 73 27 73 20 73 74 the process's st
02e0: 61 6e 64 61 72 64 20 69 6e 70 75 74 2c 20 6f 75 andard input, ou
02f0: 74 70 75 74 20 61 6e 64 20 65 72 72 6f 72 20 73 tput and error s
0300: 74 72 65 61 6d 73 20 72 65 73 70 65 63 74 69 76 treams respectiv
0310: 65 6c 79 29 2e 0a 5c 66 49 4f 70 74 69 6f 6e 5c ely)..\fIOption\
0320: 66 52 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 fR indicates wha
0330: 74 20 74 6f 20 64 6f 20 77 69 74 68 20 74 68 65 t to do with the
0340: 20 63 68 61 6e 6e 65 6c 3b 20 61 6e 79 20 75 6e channel; any un
0350: 69 71 75 65 0a 61 62 62 72 65 76 69 61 74 69 6f ique.abbreviatio
0360: 6e 20 66 6f 72 20 5c 66 49 6f 70 74 69 6f 6e 5c n for \fIoption\
0370: 66 52 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 fR is acceptable
0380: 2e 20 56 61 6c 69 64 20 6f 70 74 69 6f 6e 73 20 . Valid options
0390: 61 72 65 3a 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a are:..\" METHOD:
03a0: 20 62 6c 6f 63 6b 65 64 0a 2e 54 50 0a 5c 66 42 blocked..TP.\fB
03b0: 63 68 61 6e 20 62 6c 6f 63 6b 65 64 20 5c 66 49 chan blocked \fI
03c0: 63 68 61 6e 6e 65 6c 5c 66 52 0a 2e 0a 54 68 69 channel\fR...Thi
03d0: 73 20 74 65 73 74 73 20 77 68 65 74 68 65 72 20 s tests whether
03e0: 74 68 65 20 6c 61 73 74 20 69 6e 70 75 74 20 6f the last input o
03f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 peration on the
0400: 63 68 61 6e 6e 65 6c 20 63 61 6c 6c 65 64 0a 5c channel called.\
0410: 66 49 63 68 61 6e 6e 65 6c 5c 66 52 20 66 61 69 fIchannel\fR fai
0420: 6c 65 64 20 62 65 63 61 75 73 65 20 69 74 20 77 led because it w
0430: 6f 75 6c 64 20 68 61 76 65 20 6f 74 68 65 72 77 ould have otherw
0440: 69 73 65 20 63 61 75 73 65 64 20 74 68 65 0a 70 ise caused the.p
0450: 72 6f 63 65 73 73 20 74 6f 20 62 6c 6f 63 6b 2c rocess to block,
0460: 20 61 6e 64 20 72 65 74 75 72 6e 73 20 31 20 69 and returns 1 i
0470: 66 20 74 68 61 74 20 77 61 73 20 74 68 65 20 63 f that was the c
0480: 61 73 65 2e 20 49 74 20 72 65 74 75 72 6e 73 20 ase. It returns
0490: 30 0a 6f 74 68 65 72 77 69 73 65 2e 20 4e 6f 74 0.otherwise. Not
04a0: 65 20 74 68 61 74 20 74 68 69 73 20 6f 6e 6c 79 e that this only
04b0: 20 65 76 65 72 20 72 65 74 75 72 6e 73 20 31 20 ever returns 1
04c0: 77 68 65 6e 20 74 68 65 20 63 68 61 6e 6e 65 6c when the channel
04d0: 20 68 61 73 0a 62 65 65 6e 20 63 6f 6e 66 69 67 has.been config
04e0: 75 72 65 64 20 74 6f 20 62 65 20 6e 6f 6e 2d 62 ured to be non-b
04f0: 6c 6f 63 6b 69 6e 67 3b 20 61 6c 6c 20 54 63 6c locking; all Tcl
0500: 20 63 68 61 6e 6e 65 6c 73 20 68 61 76 65 20 62 channels have b
0510: 6c 6f 63 6b 69 6e 67 0a 74 75 72 6e 65 64 20 6f locking.turned o
0520: 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2e 5c n by default...\
0530: 22 20 4d 45 54 48 4f 44 3a 20 63 6c 6f 73 65 0a " METHOD: close.
0540: 2e 54 50 0a 5c 66 42 63 68 61 6e 20 63 6c 6f 73 .TP.\fBchan clos
0550: 65 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 20 e \fIchannel\fR
0560: 3f 5c 66 49 64 69 72 65 63 74 69 6f 6e 5c 66 52 ?\fIdirection\fR
0570: 3f 0a 2e 0a 43 6c 6f 73 65 20 61 6e 64 20 64 65 ?...Close and de
0580: 73 74 72 6f 79 20 74 68 65 20 63 68 61 6e 6e 65 stroy the channe
0590: 6c 20 63 61 6c 6c 65 64 20 5c 66 49 63 68 61 6e l called \fIchan
05a0: 6e 65 6c 5c 66 52 2e 20 4e 6f 74 65 20 74 68 61 nel\fR. Note tha
05b0: 74 20 74 68 69 73 0a 64 65 6c 65 74 65 73 20 61 t this.deletes a
05c0: 6c 6c 20 65 78 69 73 74 69 6e 67 20 66 69 6c 65 ll existing file
05d0: 2d 65 76 65 6e 74 73 20 72 65 67 69 73 74 65 72 -events register
05e0: 65 64 20 6f 6e 20 74 68 65 20 63 68 61 6e 6e 65 ed on the channe
05f0: 6c 2e 0a 49 66 20 74 68 65 20 5c 66 49 64 69 72 l..If the \fIdir
0600: 65 63 74 69 6f 6e 5c 66 52 20 61 72 67 75 6d 65 ection\fR argume
0610: 6e 74 20 28 77 68 69 63 68 20 6d 75 73 74 20 62 nt (which must b
0620: 65 20 5c 66 42 72 65 61 64 5c 66 52 20 6f 72 20 e \fBread\fR or
0630: 5c 66 42 77 72 69 74 65 5c 66 52 20 6f 72 0a 61 \fBwrite\fR or.a
0640: 6e 79 20 75 6e 69 71 75 65 20 61 62 62 72 65 76 ny unique abbrev
0650: 69 61 74 69 6f 6e 20 6f 66 20 74 68 65 6d 29 20 iation of them)
0660: 69 73 20 70 72 65 73 65 6e 74 2c 20 74 68 65 20 is present, the
0670: 63 68 61 6e 6e 65 6c 20 77 69 6c 6c 20 6f 6e 6c channel will onl
0680: 79 20 62 65 0a 68 61 6c 66 2d 63 6c 6f 73 65 64 y be.half-closed
0690: 2c 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e , so that it can
06a0: 20 67 6f 20 66 72 6f 6d 20 62 65 69 6e 67 20 72 go from being r
06b0: 65 61 64 2d 77 72 69 74 65 20 74 6f 20 77 72 69 ead-write to wri
06c0: 74 65 2d 6f 6e 6c 79 20 6f 72 0a 72 65 61 64 2d te-only or.read-
06d0: 6f 6e 6c 79 20 72 65 73 70 65 63 74 69 76 65 6c only respectivel
06e0: 79 2e 20 49 66 20 61 20 72 65 61 64 2d 6f 6e 6c y. If a read-onl
06f0: 79 20 63 68 61 6e 6e 65 6c 20 69 73 20 63 6c 6f y channel is clo
0700: 73 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 2c sed for reading,
0710: 20 69 74 20 69 73 0a 74 68 65 20 73 61 6d 65 20 it is.the same
0720: 61 73 20 69 66 20 74 68 65 20 63 68 61 6e 6e 65 as if the channe
0730: 6c 20 69 73 20 66 75 6c 6c 79 20 63 6c 6f 73 65 l is fully close
0740: 64 2c 20 61 6e 64 20 72 65 73 70 65 63 74 69 76 d, and respectiv
0750: 65 6c 79 20 73 69 6d 69 6c 61 72 20 66 6f 72 0a ely similar for.
0760: 77 72 69 74 65 2d 6f 6e 6c 79 20 63 68 61 6e 6e write-only chann
0770: 65 6c 73 2e 20 57 69 74 68 6f 75 74 20 74 68 65 els. Without the
0780: 20 5c 66 49 64 69 72 65 63 74 69 6f 6e 5c 66 52 \fIdirection\fR
0790: 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 20 63 argument, the c
07a0: 68 61 6e 6e 65 6c 20 69 73 0a 63 6c 6f 73 65 64 hannel is.closed
07b0: 20 66 6f 72 20 62 6f 74 68 20 72 65 61 64 69 6e for both readin
07c0: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 28 62 g and writing (b
07d0: 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 6f 73 65 ut only if those
07e0: 20 64 69 72 65 63 74 69 6f 6e 73 20 61 72 65 0a directions are.
07f0: 63 75 72 72 65 6e 74 6c 79 20 6f 70 65 6e 29 2e currently open).
0800: 20 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 It is an error
0810: 74 6f 20 63 6c 6f 73 65 20 61 20 72 65 61 64 2d to close a read-
0820: 6f 6e 6c 79 20 63 68 61 6e 6e 65 6c 20 66 6f 72 only channel for
0830: 20 77 72 69 74 69 6e 67 2c 20 6f 72 20 61 0a 77 writing, or a.w
0840: 72 69 74 65 2d 6f 6e 6c 79 20 63 68 61 6e 6e 65 rite-only channe
0850: 6c 20 66 6f 72 20 72 65 61 64 69 6e 67 2e 0a 2e l for reading...
0860: 52 53 0a 2e 50 50 0a 41 73 20 70 61 72 74 20 6f RS..PP.As part o
0870: 66 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 68 f closing the ch
0880: 61 6e 6e 65 6c 2c 20 61 6c 6c 20 62 75 66 66 65 annel, all buffe
0890: 72 65 64 20 6f 75 74 70 75 74 20 69 73 20 66 6c red output is fl
08a0: 75 73 68 65 64 20 74 6f 20 74 68 65 0a 63 68 61 ushed to the.cha
08b0: 6e 6e 65 6c 27 73 20 6f 75 74 70 75 74 20 64 65 nnel's output de
08c0: 76 69 63 65 20 28 6f 6e 6c 79 20 69 66 20 74 68 vice (only if th
08d0: 65 20 63 68 61 6e 6e 65 6c 20 69 73 20 63 65 61 e channel is cea
08e0: 73 69 6e 67 20 74 6f 20 62 65 20 77 72 69 74 61 sing to be writa
08f0: 62 6c 65 29 2c 20 61 6e 79 0a 62 75 66 66 65 72 ble), any.buffer
0900: 65 64 20 69 6e 70 75 74 20 69 73 20 64 69 73 63 ed input is disc
0910: 61 72 64 65 64 20 28 6f 6e 6c 79 20 69 66 20 74 arded (only if t
0920: 68 65 20 63 68 61 6e 6e 65 6c 20 69 73 20 63 65 he channel is ce
0930: 61 73 69 6e 67 20 74 6f 20 62 65 20 72 65 61 64 asing to be read
0940: 61 62 6c 65 29 2c 0a 74 68 65 20 75 6e 64 65 72 able),.the under
0950: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
0960: 73 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 20 system resource
0970: 69 73 20 63 6c 6f 73 65 64 20 61 6e 64 20 5c 66 is closed and \f
0980: 49 63 68 61 6e 6e 65 6c 5c 66 52 20 62 65 63 6f Ichannel\fR beco
0990: 6d 65 73 0a 75 6e 61 76 61 69 6c 61 62 6c 65 20 mes.unavailable
09a0: 66 6f 72 20 66 75 74 75 72 65 20 75 73 65 20 28 for future use (
09b0: 62 6f 74 68 20 6f 6e 6c 79 20 69 66 20 74 68 65 both only if the
09c0: 20 63 68 61 6e 6e 65 6c 20 69 73 20 62 65 69 6e channel is bein
09d0: 67 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 63 6c 6f g completely.clo
09e0: 73 65 64 29 2e 0a 2e 50 50 0a 49 66 20 74 68 65 sed)...PP.If the
09f0: 20 63 68 61 6e 6e 65 6c 20 69 73 20 62 6c 6f 63 channel is bloc
0a00: 6b 69 6e 67 20 61 6e 64 20 74 68 65 20 63 68 61 king and the cha
0a10: 6e 6e 65 6c 20 69 73 20 63 65 61 73 69 6e 67 20 nnel is ceasing
0a20: 74 6f 20 62 65 20 77 72 69 74 61 62 6c 65 2c 20 to be writable,
0a30: 74 68 65 0a 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 the.command does
0a40: 20 6e 6f 74 20 72 65 74 75 72 6e 20 75 6e 74 69 not return unti
0a50: 6c 20 61 6c 6c 20 6f 75 74 70 75 74 20 69 73 20 l all output is
0a60: 66 6c 75 73 68 65 64 2e 20 20 49 66 20 74 68 65 flushed. If the
0a70: 20 63 68 61 6e 6e 65 6c 20 69 73 0a 6e 6f 6e 2d channel is.non-
0a80: 62 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 74 68 65 blocking and the
0a90: 72 65 20 69 73 20 75 6e 66 6c 75 73 68 65 64 20 re is unflushed
0aa0: 6f 75 74 70 75 74 2c 20 74 68 65 20 63 68 61 6e output, the chan
0ab0: 6e 65 6c 20 72 65 6d 61 69 6e 73 20 6f 70 65 6e nel remains open
0ac0: 20 61 6e 64 20 74 68 65 0a 63 6f 6d 6d 61 6e 64 and the.command
0ad0: 20 72 65 74 75 72 6e 73 20 69 6d 6d 65 64 69 61 returns immedia
0ae0: 74 65 6c 79 3b 20 6f 75 74 70 75 74 20 77 69 6c tely; output wil
0af0: 6c 20 62 65 20 66 6c 75 73 68 65 64 20 69 6e 20 l be flushed in
0b00: 74 68 65 20 62 61 63 6b 67 72 6f 75 6e 64 20 61 the background a
0b10: 6e 64 20 74 68 65 0a 63 68 61 6e 6e 65 6c 20 77 nd the.channel w
0b20: 69 6c 6c 20 62 65 20 63 6c 6f 73 65 64 20 77 68 ill be closed wh
0b30: 65 6e 20 61 6c 6c 20 74 68 65 20 66 6c 75 73 68 en all the flush
0b40: 69 6e 67 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e ing is complete.
0b50: 0a 2e 50 50 0a 49 66 20 5c 66 49 63 68 61 6e 6e ..PP.If \fIchann
0b60: 65 6c 5c 66 52 20 69 73 20 61 20 62 6c 6f 63 6b el\fR is a block
0b70: 69 6e 67 20 63 68 61 6e 6e 65 6c 20 66 6f 72 20 ing channel for
0b80: 61 20 63 6f 6d 6d 61 6e 64 20 70 69 70 65 6c 69 a command pipeli
0b90: 6e 65 20 74 68 65 6e 0a 5c 66 42 63 68 61 6e 20 ne then.\fBchan
0ba0: 63 6c 6f 73 65 5c 66 52 20 77 61 69 74 73 20 66 close\fR waits f
0bb0: 6f 72 20 74 68 65 20 63 68 69 6c 64 20 70 72 6f or the child pro
0bc0: 63 65 73 73 65 73 20 74 6f 20 63 6f 6d 70 6c 65 cesses to comple
0bd0: 74 65 2e 0a 2e 50 50 0a 49 66 20 74 68 65 20 63 te...PP.If the c
0be0: 68 61 6e 6e 65 6c 20 69 73 20 73 68 61 72 65 64 hannel is shared
0bf0: 20 62 65 74 77 65 65 6e 20 69 6e 74 65 72 70 72 between interpr
0c00: 65 74 65 72 73 2c 20 74 68 65 6e 20 5c 66 42 63 eters, then \fBc
0c10: 68 61 6e 20 63 6c 6f 73 65 5c 66 52 0a 6d 61 6b han close\fR.mak
0c20: 65 73 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 es \fIchannel\fR
0c30: 20 75 6e 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 unavailable in
0c40: 74 68 65 20 69 6e 76 6f 6b 69 6e 67 20 69 6e 74 the invoking int
0c50: 65 72 70 72 65 74 65 72 20 62 75 74 20 68 61 73 erpreter but has
0c60: 0a 6e 6f 20 6f 74 68 65 72 20 65 66 66 65 63 74 .no other effect
0c70: 20 75 6e 74 69 6c 20 61 6c 6c 20 6f 66 20 74 68 until all of th
0c80: 65 20 73 68 61 72 69 6e 67 20 69 6e 74 65 72 70 e sharing interp
0c90: 72 65 74 65 72 73 20 68 61 76 65 20 63 6c 6f 73 reters have clos
0ca0: 65 64 20 74 68 65 0a 63 68 61 6e 6e 65 6c 2e 20 ed the.channel.
0cb0: 57 68 65 6e 20 74 68 65 20 6c 61 73 74 20 69 6e When the last in
0cc0: 74 65 72 70 72 65 74 65 72 20 69 6e 20 77 68 69 terpreter in whi
0cd0: 63 68 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 69 ch the channel i
0ce0: 73 20 72 65 67 69 73 74 65 72 65 64 0a 69 6e 76 s registered.inv
0cf0: 6f 6b 65 73 20 5c 66 42 63 68 61 6e 20 63 6c 6f okes \fBchan clo
0d00: 73 65 5c 66 52 20 28 6f 72 20 5c 66 42 63 6c 6f se\fR (or \fBclo
0d10: 73 65 5c 66 52 29 2c 20 74 68 65 20 63 6c 65 61 se\fR), the clea
0d20: 6e 75 70 20 61 63 74 69 6f 6e 73 0a 64 65 73 63 nup actions.desc
0d30: 72 69 62 65 64 20 61 62 6f 76 65 20 6f 63 63 75 ribed above occu
0d40: 72 2e 20 57 69 74 68 20 68 61 6c 66 2d 63 6c 6f r. With half-clo
0d50: 73 69 6e 67 2c 20 74 68 65 20 68 61 6c 66 2d 63 sing, the half-c
0d60: 6c 6f 73 65 20 6f 66 20 74 68 65 20 63 68 61 6e lose of the chan
0d70: 6e 65 6c 20 6f 6e 6c 79 0a 61 70 70 6c 69 65 73 nel only.applies
0d80: 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
0d90: 69 6e 74 65 72 70 72 65 74 65 72 27 73 20 76 69 interpreter's vi
0da0: 65 77 20 6f 66 20 74 68 65 20 63 68 61 6e 6e 65 ew of the channe
0db0: 6c 20 75 6e 74 69 6c 20 61 6c 6c 20 63 68 61 6e l until all chan
0dc0: 6e 65 6c 73 0a 68 61 76 65 20 63 6c 6f 73 65 64 nels.have closed
0dd0: 20 69 74 20 69 6e 20 74 68 61 74 20 64 69 72 65 it in that dire
0de0: 63 74 69 6f 6e 20 28 6f 72 20 63 6f 6d 70 6c 65 ction (or comple
0df0: 74 65 6c 79 29 2e 0a 53 65 65 20 74 68 65 20 5c tely)..See the \
0e00: 66 42 69 6e 74 65 72 70 5c 66 52 20 63 6f 6d 6d fBinterp\fR comm
0e10: 61 6e 64 20 66 6f 72 20 61 20 64 65 73 63 72 69 and for a descri
0e20: 70 74 69 6f 6e 20 6f 66 20 63 68 61 6e 6e 65 6c ption of channel
0e30: 20 73 68 61 72 69 6e 67 2e 0a 2e 50 50 0a 43 68 sharing...PP.Ch
0e40: 61 6e 6e 65 6c 73 20 61 72 65 20 61 75 74 6f 6d annels are autom
0e50: 61 74 69 63 61 6c 6c 79 20 66 75 6c 6c 79 20 63 atically fully c
0e60: 6c 6f 73 65 64 20 77 68 65 6e 20 61 6e 20 69 6e losed when an in
0e70: 74 65 72 70 72 65 74 65 72 20 69 73 20 64 65 73 terpreter is des
0e80: 74 72 6f 79 65 64 20 61 6e 64 0a 77 68 65 6e 20 troyed and.when
0e90: 74 68 65 20 70 72 6f 63 65 73 73 20 65 78 69 74 the process exit
0ea0: 73 2e 20 20 43 68 61 6e 6e 65 6c 73 20 61 72 65 s. Channels are
0eb0: 20 73 77 69 74 63 68 65 64 20 74 6f 20 62 6c 6f switched to blo
0ec0: 63 6b 69 6e 67 20 6d 6f 64 65 2c 20 74 6f 0a 65 cking mode, to.e
0ed0: 6e 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 6f nsure that all o
0ee0: 75 74 70 75 74 20 69 73 20 63 6f 72 72 65 63 74 utput is correct
0ef0: 6c 79 20 66 6c 75 73 68 65 64 20 62 65 66 6f 72 ly flushed befor
0f00: 65 20 74 68 65 20 70 72 6f 63 65 73 73 20 65 78 e the process ex
0f10: 69 74 73 2e 0a 2e 50 50 0a 54 68 65 20 63 6f 6d its...PP.The com
0f20: 6d 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 mand returns an
0f30: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 61 6e empty string, an
0f40: 64 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 61 d may generate a
0f50: 6e 20 65 72 72 6f 72 20 69 66 0a 61 6e 20 65 72 n error if.an er
0f60: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 ror occurs while
0f70: 20 66 6c 75 73 68 69 6e 67 20 6f 75 74 70 75 74 flushing output
0f80: 2e 20 20 49 66 20 61 20 63 6f 6d 6d 61 6e 64 20 . If a command
0f90: 69 6e 20 61 20 63 6f 6d 6d 61 6e 64 0a 70 69 70 in a command.pip
0fa0: 65 6c 69 6e 65 20 63 72 65 61 74 65 64 20 77 69 eline created wi
0fb0: 74 68 20 5c 66 42 6f 70 65 6e 5c 66 52 20 72 65 th \fBopen\fR re
0fc0: 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 turns an error,
0fd0: 5c 66 42 63 68 61 6e 20 63 6c 6f 73 65 5c 66 52 \fBchan close\fR
0fe0: 0a 67 65 6e 65 72 61 74 65 73 20 61 6e 20 65 72 .generates an er
0ff0: 72 6f 72 20 28 73 69 6d 69 6c 61 72 20 74 6f 20 ror (similar to
1000: 74 68 65 20 5c 66 42 65 78 65 63 5c 66 52 20 63 the \fBexec\fR c
1010: 6f 6d 6d 61 6e 64 2e 29 0a 2e 50 50 0a 4e 6f 74 ommand.)..PP.Not
1020: 65 20 74 68 61 74 20 68 61 6c 66 2d 63 6c 6f 73 e that half-clos
1030: 65 73 20 6f 66 20 73 6f 63 6b 65 74 73 20 61 6e es of sockets an
1040: 64 20 63 6f 6d 6d 61 6e 64 20 70 69 70 65 6c 69 d command pipeli
1050: 6e 65 73 20 63 61 6e 20 68 61 76 65 20 69 6d 70 nes can have imp
1060: 6f 72 74 61 6e 74 20 73 69 64 65 0a 65 66 66 65 ortant side.effe
1070: 63 74 73 20 62 65 63 61 75 73 65 20 74 68 65 79 cts because they
1080: 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 68 75 result in a shu
1090: 74 64 6f 77 6e 28 29 20 6f 72 20 63 6c 6f 73 65 tdown() or close
10a0: 28 29 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c () of the underl
10b0: 79 69 6e 67 0a 73 79 73 74 65 6d 20 72 65 73 6f ying.system reso
10c0: 75 72 63 65 2c 20 77 68 69 63 68 20 63 61 6e 20 urce, which can
10d0: 63 68 61 6e 67 65 20 68 6f 77 20 6f 74 68 65 72 change how other
10e0: 20 70 72 6f 63 65 73 73 65 73 20 6f 72 20 73 79 processes or sy
10f0: 73 74 65 6d 73 20 72 65 73 70 6f 6e 64 20 74 6f stems respond to
1100: 0a 74 68 65 20 54 63 6c 20 70 72 6f 67 72 61 6d .the Tcl program
1110: 2e 0a 2e 50 50 0a 43 68 61 6e 6e 65 6c 73 20 61 ...PP.Channels a
1120: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 re automatically
1130: 20 63 6c 6f 73 65 64 20 77 68 65 6e 20 61 6e 20 closed when an
1140: 69 6e 74 65 72 70 72 65 74 65 72 20 69 73 20 64 interpreter is d
1150: 65 73 74 72 6f 79 65 64 20 61 6e 64 0a 77 68 65 estroyed and.whe
1160: 6e 20 74 68 65 20 70 72 6f 63 65 73 73 20 65 78 n the process ex
1170: 69 74 73 2e 0a 46 72 6f 6d 20 38 2e 36 20 6f 6e its..From 8.6 on
1180: 20 28 54 49 50 23 33 39 38 29 2c 20 6e 6f 6e 62 (TIP#398), nonb
1190: 6c 6f 63 6b 69 6e 67 20 63 68 61 6e 6e 65 6c 73 locking channels
11a0: 20 61 72 65 20 6e 6f 20 6c 6f 6e 67 65 72 20 73 are no longer s
11b0: 77 69 74 63 68 65 64 20 74 6f 0a 62 6c 6f 63 6b witched to.block
11c0: 69 6e 67 20 6d 6f 64 65 20 77 68 65 6e 20 65 78 ing mode when ex
11d0: 69 74 69 6e 67 3b 20 74 68 69 73 20 67 75 61 72 iting; this guar
11e0: 61 6e 74 65 65 73 20 61 20 74 69 6d 65 6c 79 20 antees a timely
11f0: 65 78 69 74 20 65 76 65 6e 20 77 68 65 6e 20 74 exit even when t
1200: 68 65 0a 70 65 65 72 20 6f 72 20 61 20 63 6f 6d he.peer or a com
1210: 6d 75 6e 69 63 61 74 69 6f 6e 20 63 68 61 6e 6e munication chann
1220: 65 6c 20 69 73 20 73 74 61 6c 6c 65 64 2e 20 54 el is stalled. T
1230: 6f 20 65 6e 73 75 72 65 20 70 72 6f 70 65 72 20 o ensure proper
1240: 66 6c 75 73 68 69 6e 67 20 6f 66 0a 73 74 61 6c flushing of.stal
1250: 6c 65 64 20 6e 6f 6e 62 6c 6f 63 6b 69 6e 67 20 led nonblocking
1260: 63 68 61 6e 6e 65 6c 73 20 6f 6e 20 65 78 69 74 channels on exit
1270: 2c 20 6f 6e 65 20 6d 75 73 74 20 6e 6f 77 20 65 , one must now e
1280: 69 74 68 65 72 20 28 61 29 20 61 63 74 69 76 65 ither (a) active
1290: 6c 79 0a 73 77 69 74 63 68 20 74 68 65 6d 20 62 ly.switch them b
12a0: 61 63 6b 20 74 6f 20 62 6c 6f 63 6b 69 6e 67 20 ack to blocking
12b0: 6f 72 20 28 62 29 20 75 73 65 20 74 68 65 20 65 or (b) use the e
12c0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 69 61 nvironment varia
12d0: 62 6c 65 0a 5c 66 42 54 43 4c 5f 46 4c 55 53 48 ble.\fBTCL_FLUSH
12e0: 5f 4e 4f 4e 42 4c 4f 43 4b 49 4e 47 5f 4f 4e 5f _NONBLOCKING_ON_
12f0: 45 58 49 54 5c 66 52 2c 20 77 68 69 63 68 20 77 EXIT\fR, which w
1300: 68 65 6e 20 73 65 74 20 61 6e 64 20 6e 6f 74 20 hen set and not
1310: 65 71 75 61 6c 20 74 6f 0a 2e 51 57 20 5c 66 42 equal to..QW \fB
1320: 30 5c 66 52 0a 72 65 73 74 6f 72 65 73 20 74 68 0\fR.restores th
1330: 65 20 70 72 65 76 69 6f 75 73 20 62 65 68 61 76 e previous behav
1340: 69 6f 72 2e 0a 2e 52 45 0a 2e 5c 22 20 4d 45 54 ior...RE..\" MET
1350: 48 4f 44 3a 20 63 6f 6e 66 69 67 75 72 65 0a 2e HOD: configure..
1360: 54 50 0a 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 TP.\fBchan confi
1370: 67 75 72 65 20 5c 66 49 63 68 61 6e 6e 65 6c 5c gure \fIchannel\
1380: 66 52 20 3f 5c 66 49 6f 70 74 69 6f 6e 4e 61 6d fR ?\fIoptionNam
1390: 65 5c 66 52 3f 20 3f 5c 66 49 76 61 6c 75 65 5c e\fR? ?\fIvalue\
13a0: 66 52 3f 20 3f 5c 66 49 6f 70 74 69 6f 6e 4e 61 fR? ?\fIoptionNa
13b0: 6d 65 20 76 61 6c 75 65 5c 66 52 3f 2e 2e 2e 0a me value\fR?....
13c0: 2e 0a 51 75 65 72 79 20 6f 72 20 73 65 74 20 74 ..Query or set t
13d0: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
13e0: 20 6f 70 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 options of the
13f0: 63 68 61 6e 6e 65 6c 20 6e 61 6d 65 64 0a 5c 66 channel named.\f
1400: 49 63 68 61 6e 6e 65 6c 5c 66 52 2e 0a 2e 52 53 Ichannel\fR...RS
1410: 0a 2e 50 50 0a 49 66 20 6e 6f 20 5c 66 49 6f 70 ..PP.If no \fIop
1420: 74 69 6f 6e 4e 61 6d 65 5c 66 52 20 6f 72 20 5c tionName\fR or \
1430: 66 49 76 61 6c 75 65 5c 66 52 20 61 72 67 75 6d fIvalue\fR argum
1440: 65 6e 74 73 20 61 72 65 20 73 75 70 70 6c 69 65 ents are supplie
1450: 64 2c 20 74 68 65 0a 63 6f 6d 6d 61 6e 64 20 72 d, the.command r
1460: 65 74 75 72 6e 73 20 61 20 6c 69 73 74 20 63 6f eturns a list co
1470: 6e 74 61 69 6e 69 6e 67 20 61 6c 74 65 72 6e 61 ntaining alterna
1480: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 ting option name
1490: 73 20 61 6e 64 20 76 61 6c 75 65 73 0a 66 6f 72 s and values.for
14a0: 20 74 68 65 20 63 68 61 6e 6e 65 6c 2e 20 20 49 the channel. I
14b0: 66 20 5c 66 49 6f 70 74 69 6f 6e 4e 61 6d 65 5c f \fIoptionName\
14c0: 66 52 20 69 73 20 73 75 70 70 6c 69 65 64 20 62 fR is supplied b
14d0: 75 74 20 6e 6f 20 5c 66 49 76 61 6c 75 65 5c 66 ut no \fIvalue\f
14e0: 52 0a 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 61 R.then the comma
14f0: 6e 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 63 nd returns the c
1500: 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
1510: 74 68 65 20 67 69 76 65 6e 20 6f 70 74 69 6f 6e the given option
1520: 2e 20 20 49 66 0a 6f 6e 65 20 6f 72 20 6d 6f 72 . If.one or mor
1530: 65 20 70 61 69 72 73 20 6f 66 20 5c 66 49 6f 70 e pairs of \fIop
1540: 74 69 6f 6e 4e 61 6d 65 5c 66 52 20 61 6e 64 20 tionName\fR and
1550: 5c 66 49 76 61 6c 75 65 5c 66 52 20 61 72 65 20 \fIvalue\fR are
1560: 73 75 70 70 6c 69 65 64 2c 0a 74 68 65 20 63 6f supplied,.the co
1570: 6d 6d 61 6e 64 20 73 65 74 73 20 65 61 63 68 20 mmand sets each
1580: 6f 66 20 74 68 65 20 6e 61 6d 65 64 20 6f 70 74 of the named opt
1590: 69 6f 6e 73 20 74 6f 20 74 68 65 20 63 6f 72 72 ions to the corr
15a0: 65 73 70 6f 6e 64 69 6e 67 0a 5c 66 49 76 61 6c esponding.\fIval
15b0: 75 65 5c 66 52 3b 20 69 6e 20 74 68 69 73 20 63 ue\fR; in this c
15c0: 61 73 65 20 74 68 65 20 72 65 74 75 72 6e 20 76 ase the return v
15d0: 61 6c 75 65 20 69 73 20 61 6e 20 65 6d 70 74 79 alue is an empty
15e0: 20 73 74 72 69 6e 67 2e 0a 2e 50 50 0a 54 68 65 string...PP.The
15f0: 20 6f 70 74 69 6f 6e 73 20 64 65 73 63 72 69 62 options describ
1600: 65 64 20 62 65 6c 6f 77 20 61 72 65 20 73 75 70 ed below are sup
1610: 70 6f 72 74 65 64 20 66 6f 72 20 61 6c 6c 20 63 ported for all c
1620: 68 61 6e 6e 65 6c 73 2e 20 49 6e 0a 61 64 64 69 hannels. In.addi
1630: 74 69 6f 6e 2c 20 65 61 63 68 20 63 68 61 6e 6e tion, each chann
1640: 65 6c 20 74 79 70 65 20 6d 61 79 20 61 64 64 20 el type may add
1650: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 6f 6e 6c options that onl
1660: 79 20 69 74 20 73 75 70 70 6f 72 74 73 2e 20 53 y it supports. S
1670: 65 65 0a 74 68 65 20 6d 61 6e 75 61 6c 20 65 6e ee.the manual en
1680: 74 72 79 20 66 6f 72 20 74 68 65 20 63 6f 6d 6d try for the comm
1690: 61 6e 64 20 74 68 61 74 20 63 72 65 61 74 65 73 and that creates
16a0: 20 65 61 63 68 20 74 79 70 65 20 6f 66 20 63 68 each type of ch
16b0: 61 6e 6e 65 6c 0a 66 6f 72 20 74 68 65 20 6f 70 annel.for the op
16c0: 74 69 6f 6e 73 20 73 75 70 70 6f 72 74 65 64 20 tions supported
16d0: 62 79 20 74 68 61 74 20 73 70 65 63 69 66 69 63 by that specific
16e0: 20 74 79 70 65 20 6f 66 20 63 68 61 6e 6e 65 6c type of channel
16f0: 2e 20 46 6f 72 0a 65 78 61 6d 70 6c 65 2c 20 73 . For.example, s
1700: 65 65 20 74 68 65 20 6d 61 6e 75 61 6c 20 65 6e ee the manual en
1710: 74 72 79 20 66 6f 72 20 74 68 65 20 5c 66 42 73 try for the \fBs
1720: 6f 63 6b 65 74 5c 66 52 20 63 6f 6d 6d 61 6e 64 ocket\fR command
1730: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
1740: 6f 70 74 69 6f 6e 73 20 66 6f 72 20 73 6f 63 6b options for sock
1750: 65 74 73 2c 20 61 6e 64 20 74 68 65 20 5c 66 42 ets, and the \fB
1760: 6f 70 65 6e 5c 66 52 20 63 6f 6d 6d 61 6e 64 20 open\fR command
1770: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f for additional o
1780: 70 74 69 6f 6e 73 20 66 6f 72 0a 73 65 72 69 61 ptions for.seria
1790: 6c 20 64 65 76 69 63 65 73 2e 0a 2e 52 45 0a 2e l devices...RE..
17a0: 5c 22 20 4f 50 54 49 4f 4e 3a 20 2d 62 6c 6f 63 \" OPTION: -bloc
17b0: 6b 69 6e 67 0a 2e 54 50 0a 5c 66 42 5c 2d 62 6c king..TP.\fB\-bl
17c0: 6f 63 6b 69 6e 67 5c 66 49 20 62 6f 6f 6c 65 61 ocking\fI boolea
17d0: 6e 5c 66 52 0a 2e 0a 54 68 65 20 5c 66 42 5c 2d n\fR...The \fB\-
17e0: 62 6c 6f 63 6b 69 6e 67 5c 66 52 20 6f 70 74 69 blocking\fR opti
17f0: 6f 6e 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 on determines wh
1800: 65 74 68 65 72 20 49 2f 4f 20 6f 70 65 72 61 74 ether I/O operat
1810: 69 6f 6e 73 20 6f 6e 20 74 68 65 0a 63 68 61 6e ions on the.chan
1820: 6e 65 6c 20 63 61 6e 20 63 61 75 73 65 20 74 68 nel can cause th
1830: 65 20 70 72 6f 63 65 73 73 20 74 6f 20 62 6c 6f e process to blo
1840: 63 6b 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2e ck indefinitely.
1850: 20 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 The value of t
1860: 68 65 0a 6f 70 74 69 6f 6e 20 6d 75 73 74 20 62 he.option must b
1870: 65 20 61 20 70 72 6f 70 65 72 20 62 6f 6f 6c 65 e a proper boole
1880: 61 6e 20 76 61 6c 75 65 2e 20 20 43 68 61 6e 6e an value. Chann
1890: 65 6c 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 els are normally
18a0: 20 69 6e 0a 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 in.blocking mod
18b0: 65 3b 20 69 66 20 61 20 63 68 61 6e 6e 65 6c 20 e; if a channel
18c0: 69 73 20 70 6c 61 63 65 64 20 69 6e 74 6f 20 6e is placed into n
18d0: 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 on-blocking mode
18e0: 20 69 74 20 77 69 6c 6c 0a 61 66 66 65 63 74 20 it will.affect
18f0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 the operation of
1900: 20 74 68 65 20 5c 66 42 63 68 61 6e 20 67 65 74 the \fBchan get
1910: 73 5c 66 52 2c 20 5c 66 42 63 68 61 6e 20 72 65 s\fR, \fBchan re
1920: 61 64 5c 66 52 2c 20 5c 66 42 63 68 61 6e 0a 70 ad\fR, \fBchan.p
1930: 75 74 73 5c 66 52 2c 20 5c 66 42 63 68 61 6e 20 uts\fR, \fBchan
1940: 66 6c 75 73 68 5c 66 52 2c 20 61 6e 64 20 5c 66 flush\fR, and \f
1950: 42 63 68 61 6e 20 63 6c 6f 73 65 5c 66 52 20 63 Bchan close\fR c
1960: 6f 6d 6d 61 6e 64 73 3b 20 73 65 65 20 74 68 65 ommands; see the
1970: 0a 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 .documentation f
1980: 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 or those command
1990: 73 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 20 20 s for details.
19a0: 46 6f 72 20 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 For non-blocking
19b0: 20 6d 6f 64 65 20 74 6f 0a 77 6f 72 6b 20 63 6f mode to.work co
19c0: 72 72 65 63 74 6c 79 2c 20 74 68 65 20 61 70 70 rrectly, the app
19d0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 lication must be
19e0: 20 75 73 69 6e 67 20 74 68 65 20 54 63 6c 20 65 using the Tcl e
19f0: 76 65 6e 74 20 6c 6f 6f 70 0a 28 65 2e 67 2e 20 vent loop.(e.g.
1a00: 62 79 20 63 61 6c 6c 69 6e 67 20 5c 66 42 54 63 by calling \fBTc
1a10: 6c 5f 44 6f 4f 6e 65 45 76 65 6e 74 5c 66 52 20 l_DoOneEvent\fR
1a20: 6f 72 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 or invoking the
1a30: 5c 66 42 76 77 61 69 74 5c 66 52 0a 63 6f 6d 6d \fBvwait\fR.comm
1a40: 61 6e 64 29 2e 0a 2e 5c 22 20 4f 50 54 49 4f 4e and)...\" OPTION
1a50: 3a 20 2d 62 75 66 66 65 72 69 6e 67 0a 2e 54 50 : -buffering..TP
1a60: 0a 5c 66 42 5c 2d 62 75 66 66 65 72 69 6e 67 5c .\fB\-buffering\
1a70: 66 49 20 6e 65 77 56 61 6c 75 65 5c 66 52 0a 2e fI newValue\fR..
1a80: 0a 49 66 20 5c 66 49 6e 65 77 56 61 6c 75 65 5c .If \fInewValue\
1a90: 66 52 20 69 73 20 5c 66 42 66 75 6c 6c 5c 66 52 fR is \fBfull\fR
1aa0: 20 74 68 65 6e 20 74 68 65 20 49 2f 4f 20 73 79 then the I/O sy
1ab0: 73 74 65 6d 20 77 69 6c 6c 20 62 75 66 66 65 72 stem will buffer
1ac0: 20 6f 75 74 70 75 74 0a 75 6e 74 69 6c 20 69 74 output.until it
1ad0: 73 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 s internal buffe
1ae0: 72 20 69 73 20 66 75 6c 6c 20 6f 72 20 75 6e 74 r is full or unt
1af0: 69 6c 20 74 68 65 20 5c 66 42 63 68 61 6e 20 66 il the \fBchan f
1b00: 6c 75 73 68 5c 66 52 0a 63 6f 6d 6d 61 6e 64 20 lush\fR.command
1b10: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 49 66 20 5c is invoked. If \
1b20: 66 49 6e 65 77 56 61 6c 75 65 5c 66 52 20 69 73 fInewValue\fR is
1b30: 20 5c 66 42 6c 69 6e 65 5c 66 52 2c 20 74 68 65 \fBline\fR, the
1b40: 6e 20 74 68 65 20 49 2f 4f 0a 73 79 73 74 65 6d n the I/O.system
1b50: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
1b60: 6c 6c 79 20 66 6c 75 73 68 20 6f 75 74 70 75 74 lly flush output
1b70: 20 66 6f 72 20 74 68 65 20 63 68 61 6e 6e 65 6c for the channel
1b80: 20 77 68 65 6e 65 76 65 72 20 61 0a 6e 65 77 6c whenever a.newl
1b90: 69 6e 65 20 63 68 61 72 61 63 74 65 72 20 69 73 ine character is
1ba0: 20 6f 75 74 70 75 74 2e 20 49 66 20 5c 66 49 6e output. If \fIn
1bb0: 65 77 56 61 6c 75 65 5c 66 52 20 69 73 20 5c 66 ewValue\fR is \f
1bc0: 42 6e 6f 6e 65 5c 66 52 2c 20 74 68 65 20 49 2f Bnone\fR, the I/
1bd0: 4f 0a 73 79 73 74 65 6d 20 77 69 6c 6c 20 66 6c O.system will fl
1be0: 75 73 68 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ush automaticall
1bf0: 79 20 61 66 74 65 72 20 65 76 65 72 79 20 6f 75 y after every ou
1c00: 74 70 75 74 20 6f 70 65 72 61 74 69 6f 6e 2e 20 tput operation.
1c10: 20 54 68 65 0a 64 65 66 61 75 6c 74 20 69 73 20 The.default is
1c20: 66 6f 72 20 5c 66 42 5c 2d 62 75 66 66 65 72 69 for \fB\-bufferi
1c30: 6e 67 5c 66 52 20 74 6f 20 62 65 20 73 65 74 20 ng\fR to be set
1c40: 74 6f 20 5c 66 42 66 75 6c 6c 5c 66 52 20 65 78 to \fBfull\fR ex
1c50: 63 65 70 74 20 66 6f 72 0a 63 68 61 6e 6e 65 6c cept for.channel
1c60: 73 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 20 74 s that connect t
1c70: 6f 20 74 65 72 6d 69 6e 61 6c 2d 6c 69 6b 65 20 o terminal-like
1c80: 64 65 76 69 63 65 73 3b 20 66 6f 72 20 74 68 65 devices; for the
1c90: 73 65 20 63 68 61 6e 6e 65 6c 73 20 74 68 65 0a se channels the.
1ca0: 69 6e 69 74 69 61 6c 20 73 65 74 74 69 6e 67 20 initial setting
1cb0: 69 73 20 5c 66 42 6c 69 6e 65 5c 66 52 2e 20 20 is \fBline\fR.
1cc0: 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 5c 66 Additionally, \f
1cd0: 42 73 74 64 69 6e 5c 66 52 20 61 6e 64 0a 5c 66 Bstdin\fR and.\f
1ce0: 42 73 74 64 6f 75 74 5c 66 52 20 61 72 65 20 69 Bstdout\fR are i
1cf0: 6e 69 74 69 61 6c 6c 79 20 73 65 74 20 74 6f 20 nitially set to
1d00: 5c 66 42 6c 69 6e 65 5c 66 52 2c 20 61 6e 64 20 \fBline\fR, and
1d10: 5c 66 42 73 74 64 65 72 72 5c 66 52 20 69 73 20 \fBstderr\fR is
1d20: 73 65 74 0a 74 6f 20 5c 66 42 6e 6f 6e 65 5c 66 set.to \fBnone\f
1d30: 52 2e 0a 2e 5c 22 20 4f 50 54 49 4f 4e 3a 20 2d R...\" OPTION: -
1d40: 62 75 66 66 65 72 73 69 7a 65 0a 2e 54 50 0a 5c buffersize..TP.\
1d50: 66 42 5c 2d 62 75 66 66 65 72 73 69 7a 65 5c 66 fB\-buffersize\f
1d60: 49 20 6e 65 77 53 69 7a 65 5c 66 52 0a 2e 0a 5c I newSize\fR...\
1d70: 66 49 6e 65 77 53 69 7a 65 5c 66 52 20 6d 75 73 fInewSize\fR mus
1d80: 74 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 3b t be an integer;
1d90: 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 75 73 its value is us
1da0: 65 64 20 74 6f 20 73 65 74 20 74 68 65 20 73 69 ed to set the si
1db0: 7a 65 0a 6f 66 20 62 75 66 66 65 72 73 2c 20 69 ze.of buffers, i
1dc0: 6e 20 62 79 74 65 73 2c 20 73 75 62 73 65 71 75 n bytes, subsequ
1dd0: 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 20 ently allocated
1de0: 66 6f 72 20 74 68 69 73 20 63 68 61 6e 6e 65 6c for this channel
1df0: 20 74 6f 20 73 74 6f 72 65 0a 69 6e 70 75 74 20 to store.input
1e00: 6f 72 20 6f 75 74 70 75 74 2e 20 5c 66 49 6e 65 or output. \fIne
1e10: 77 53 69 7a 65 5c 66 52 20 6d 75 73 74 20 62 65 wSize\fR must be
1e20: 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6e 6f 20 a number of no
1e30: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 6d 69 more than one.mi
1e40: 6c 6c 69 6f 6e 2c 20 61 6c 6c 6f 77 69 6e 67 20 llion, allowing
1e50: 62 75 66 66 65 72 73 20 6f 66 20 75 70 20 74 6f buffers of up to
1e60: 20 6f 6e 65 20 6d 69 6c 6c 69 6f 6e 20 62 79 74 one million byt
1e70: 65 73 20 69 6e 20 73 69 7a 65 2e 0a 2e 5c 22 20 es in size...\"
1e80: 4f 50 54 49 4f 4e 3a 20 2d 65 6e 63 6f 64 69 6e OPTION: -encodin
1e90: 67 0a 2e 54 50 0a 5c 66 42 5c 2d 65 6e 63 6f 64 g..TP.\fB\-encod
1ea0: 69 6e 67 5c 66 52 20 5c 66 49 6e 61 6d 65 5c 66 ing\fR \fIname\f
1eb0: 52 0a 2e 0a 54 68 69 73 20 6f 70 74 69 6f 6e 20 R...This option
1ec0: 69 73 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 is used to speci
1ed0: 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 fy the encoding
1ee0: 6f 66 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 61 of the channel a
1ef0: 73 20 6f 6e 65 20 6f 66 0a 74 68 65 20 6e 61 6d s one of.the nam
1f00: 65 64 20 65 6e 63 6f 64 69 6e 67 73 20 72 65 74 ed encodings ret
1f10: 75 72 6e 65 64 20 62 79 20 5c 66 42 65 6e 63 6f urned by \fBenco
1f20: 64 69 6e 67 20 6e 61 6d 65 73 5c 66 52 20 6f 72 ding names\fR or
1f30: 20 74 68 65 20 73 70 65 63 69 61 6c 0a 76 61 6c the special.val
1f40: 75 65 20 5c 66 42 62 69 6e 61 72 79 5c 66 52 2c ue \fBbinary\fR,
1f50: 20 73 6f 20 74 68 61 74 20 74 68 65 20 64 61 74 so that the dat
1f60: 61 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 a can be convert
1f70: 65 64 20 74 6f 20 61 6e 64 20 66 72 6f 6d 0a 55 ed to and from.U
1f80: 6e 69 63 6f 64 65 20 66 6f 72 20 75 73 65 20 69 nicode for use i
1f90: 6e 20 54 63 6c 2e 20 20 46 6f 72 20 69 6e 73 74 n Tcl. For inst
1fa0: 61 6e 63 65 2c 20 69 6e 20 6f 72 64 65 72 20 66 ance, in order f
1fb0: 6f 72 20 54 63 6c 20 74 6f 20 72 65 61 64 0a 63 or Tcl to read.c
1fc0: 68 61 72 61 63 74 65 72 73 20 66 72 6f 6d 20 61 haracters from a
1fd0: 20 4a 61 70 61 6e 65 73 65 20 66 69 6c 65 20 69 Japanese file i
1fe0: 6e 20 5c 66 42 73 68 69 66 74 6a 69 73 5c 66 52 n \fBshiftjis\fR
1ff0: 20 61 6e 64 20 70 72 6f 70 65 72 6c 79 20 70 72 and properly pr
2000: 6f 63 65 73 73 0a 61 6e 64 20 64 69 73 70 6c 61 ocess.and displa
2010: 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 2c 20 y the contents,
2020: 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 77 6f 75 the encoding wou
2030: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 5c 66 42 ld be set to \fB
2040: 73 68 69 66 74 6a 69 73 5c 66 52 2e 0a 54 68 65 shiftjis\fR..The
2050: 72 65 61 66 74 65 72 2c 20 77 68 65 6e 20 72 65 reafter, when re
2060: 61 64 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 63 ading from the c
2070: 68 61 6e 6e 65 6c 2c 20 74 68 65 20 62 79 74 65 hannel, the byte
2080: 73 20 69 6e 20 74 68 65 20 4a 61 70 61 6e 65 73 s in the Japanes
2090: 65 0a 66 69 6c 65 20 77 6f 75 6c 64 20 62 65 20 e.file would be
20a0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 6e 69 converted to Uni
20b0: 63 6f 64 65 20 61 73 20 74 68 65 79 20 61 72 65 code as they are
20c0: 20 72 65 61 64 2e 20 20 57 72 69 74 69 6e 67 20 read. Writing
20d0: 69 73 20 61 6c 73 6f 0a 73 75 70 70 6f 72 74 65 is also.supporte
20e0: 64 20 5c 2d 20 61 73 20 54 63 6c 20 73 74 72 69 d \- as Tcl stri
20f0: 6e 67 73 20 61 72 65 20 77 72 69 74 74 65 6e 20 ngs are written
2100: 74 6f 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 74 to the channel t
2110: 68 65 79 20 77 69 6c 6c 0a 61 75 74 6f 6d 61 74 hey will.automat
2120: 69 63 61 6c 6c 79 20 62 65 20 63 6f 6e 76 65 72 ically be conver
2130: 74 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 ted to the speci
2140: 66 69 65 64 20 65 6e 63 6f 64 69 6e 67 20 6f 6e fied encoding on
2150: 20 6f 75 74 70 75 74 2e 0a 2e 52 53 0a 2e 50 50 output...RS..PP
2160: 0a 49 66 20 61 20 66 69 6c 65 20 63 6f 6e 74 61 .If a file conta
2170: 69 6e 73 20 70 75 72 65 20 62 69 6e 61 72 79 20 ins pure binary
2180: 64 61 74 61 20 28 66 6f 72 20 69 6e 73 74 61 6e data (for instan
2190: 63 65 2c 20 61 20 4a 50 45 47 20 69 6d 61 67 65 ce, a JPEG image
21a0: 29 2c 20 74 68 65 0a 65 6e 63 6f 64 69 6e 67 20 ), the.encoding
21b0: 66 6f 72 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 for the channel
21c0: 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 66 69 67 should be config
21d0: 75 72 65 64 20 74 6f 20 62 65 20 5c 66 42 62 69 ured to be \fBbi
21e0: 6e 61 72 79 5c 66 52 2e 20 20 54 63 6c 0a 77 69 nary\fR. Tcl.wi
21f0: 6c 6c 20 74 68 65 6e 20 61 73 73 69 67 6e 20 6e ll then assign n
2200: 6f 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e o interpretation
2210: 20 74 6f 20 74 68 65 20 64 61 74 61 20 69 6e 20 to the data in
2220: 74 68 65 20 66 69 6c 65 20 61 6e 64 20 73 69 6d the file and sim
2230: 70 6c 79 0a 72 65 61 64 20 6f 72 20 77 72 69 74 ply.read or writ
2240: 65 20 72 61 77 20 62 79 74 65 73 2e 20 20 54 68 e raw bytes. Th
2250: 65 20 54 63 6c 20 5c 66 42 62 69 6e 61 72 79 5c e Tcl \fBbinary\
2260: 66 52 20 63 6f 6d 6d 61 6e 64 20 63 61 6e 20 62 fR command can b
2270: 65 20 75 73 65 64 20 74 6f 0a 6d 61 6e 69 70 75 e used to.manipu
2280: 6c 61 74 65 20 74 68 69 73 20 62 79 74 65 2d 6f late this byte-o
2290: 72 69 65 6e 74 65 64 20 64 61 74 61 2e 20 20 49 riented data. I
22a0: 74 20 69 73 20 75 73 75 61 6c 6c 79 20 62 65 74 t is usually bet
22b0: 74 65 72 20 74 6f 20 73 65 74 20 74 68 65 0a 5c ter to set the.\
22c0: 66 42 5c 2d 74 72 61 6e 73 6c 61 74 69 6f 6e 5c fB\-translation\
22d0: 66 52 20 6f 70 74 69 6f 6e 20 74 6f 20 5c 66 42 fR option to \fB
22e0: 62 69 6e 61 72 79 5c 66 52 20 77 68 65 6e 20 79 binary\fR when y
22f0: 6f 75 20 77 61 6e 74 20 74 6f 20 74 72 61 6e 73 ou want to trans
2300: 66 65 72 0a 62 69 6e 61 72 79 20 64 61 74 61 2c fer.binary data,
2310: 20 61 73 20 74 68 69 73 20 74 75 72 6e 73 20 6f as this turns o
2320: 66 66 20 74 68 65 20 6f 74 68 65 72 20 61 75 74 ff the other aut
2330: 6f 6d 61 74 69 63 20 69 6e 74 65 72 70 72 65 74 omatic interpret
2340: 61 74 69 6f 6e 73 20 6f 66 0a 74 68 65 20 62 79 ations of.the by
2350: 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 65 61 tes in the strea
2360: 6d 20 61 73 20 77 65 6c 6c 2e 0a 2e 50 50 0a 54 m as well...PP.T
2370: 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
2380: 69 6e 67 20 66 6f 72 20 6e 65 77 6c 79 20 6f 70 ing for newly op
2390: 65 6e 65 64 20 63 68 61 6e 6e 65 6c 73 20 69 73 ened channels is
23a0: 20 74 68 65 20 73 61 6d 65 20 70 6c 61 74 66 6f the same platfo
23b0: 72 6d 2d 0a 61 6e 64 20 6c 6f 63 61 6c 65 2d 64 rm-.and locale-d
23c0: 65 70 65 6e 64 65 6e 74 20 73 79 73 74 65 6d 20 ependent system
23d0: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
23e0: 72 20 69 6e 74 65 72 66 61 63 69 6e 67 20 77 69 r interfacing wi
23f0: 74 68 20 74 68 65 0a 6f 70 65 72 61 74 69 6e 67 th the.operating
2400: 20 73 79 73 74 65 6d 2c 20 61 73 20 72 65 74 75 system, as retu
2410: 72 6e 65 64 20 62 79 20 5c 66 42 65 6e 63 6f 64 rned by \fBencod
2420: 69 6e 67 20 73 79 73 74 65 6d 5c 66 52 2e 0a 2e ing system\fR...
2430: 52 45 0a 2e 5c 22 20 4f 50 54 49 4f 4e 3a 20 2d RE..\" OPTION: -
2440: 65 6f 66 63 68 61 72 0a 2e 54 50 0a 5c 66 42 5c eofchar..TP.\fB\
2450: 2d 65 6f 66 63 68 61 72 5c 66 49 20 63 68 61 72 -eofchar\fI char
2460: 5c 66 52 0a 2e 0a 54 68 69 73 20 6f 70 74 69 6f \fR...This optio
2470: 6e 20 73 75 70 70 6f 72 74 73 20 44 4f 53 20 66 n supports DOS f
2480: 69 6c 65 20 73 79 73 74 65 6d 73 20 74 68 61 74 ile systems that
2490: 20 75 73 65 20 43 6f 6e 74 72 6f 6c 2d 7a 20 28 use Control-z (
24a0: 5c 65 78 31 41 29 20 61 73 20 61 6e 0a 65 6e 64 \ex1A) as an.end
24b0: 20 6f 66 20 66 69 6c 65 20 6d 61 72 6b 65 72 2e of file marker.
24c0: 20 20 49 66 20 5c 66 49 63 68 61 72 5c 66 52 20 If \fIchar\fR
24d0: 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 is not an empty
24e0: 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 69 string, then thi
24f0: 73 0a 63 68 61 72 61 63 74 65 72 20 73 69 67 6e s.character sign
2500: 61 6c 73 20 65 6e 64 2d 6f 66 2d 66 69 6c 65 20 als end-of-file
2510: 77 68 65 6e 20 69 74 20 69 73 20 65 6e 63 6f 75 when it is encou
2520: 6e 74 65 72 65 64 20 64 75 72 69 6e 67 20 69 6e ntered during in
2530: 70 75 74 2e 0a 4f 74 68 65 72 77 69 73 65 20 28 put..Otherwise (
2540: 74 68 65 20 64 65 66 61 75 6c 74 29 20 74 68 65 the default) the
2550: 72 65 20 69 73 20 6e 6f 20 73 70 65 63 69 61 6c re is no special
2560: 20 65 6e 64 20 6f 66 20 66 69 6c 65 20 63 68 61 end of file cha
2570: 72 61 63 74 65 72 20 6d 61 72 6b 65 72 2e 0a 54 racter marker..T
2580: 68 65 20 61 63 63 65 70 74 61 62 6c 65 20 72 61 he acceptable ra
2590: 6e 67 65 20 66 6f 72 20 5c 66 42 5c 2d 65 6f 66 nge for \fB\-eof
25a0: 63 68 61 72 5c 66 52 20 76 61 6c 75 65 73 20 69 char\fR values i
25b0: 73 20 5c 65 78 30 31 20 2d 20 5c 65 78 37 66 3b s \ex01 - \ex7f;
25c0: 0a 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 .attempting to s
25d0: 65 74 20 5c 66 42 5c 2d 65 6f 66 63 68 61 72 5c et \fB\-eofchar\
25e0: 66 52 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 75 fR to a value ou
25f0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 tside of this ra
2600: 6e 67 65 20 77 69 6c 6c 0a 67 65 6e 65 72 61 74 nge will.generat
2610: 65 20 61 6e 20 65 72 72 6f 72 2e 0a 2e 56 53 20 e an error...VS
2620: 22 54 43 4c 38 2e 37 20 54 49 50 36 35 36 22 0a "TCL8.7 TIP656".
2630: 2e 5c 22 20 4f 50 54 49 4f 4e 3a 20 2d 70 72 6f .\" OPTION: -pro
2640: 66 69 6c 65 0a 2e 54 50 0a 5c 66 42 5c 2d 70 72 file..TP.\fB\-pr
2650: 6f 66 69 6c 65 5c 66 49 20 70 72 6f 66 69 6c 65 ofile\fI profile
2660: 5c 66 52 0a 2e 0a 53 70 65 63 69 66 69 65 73 20 \fR...Specifies
2670: 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 70 72 6f the encoding pro
2680: 66 69 6c 65 20 74 6f 20 62 65 20 75 73 65 64 20 file to be used
2690: 6f 6e 20 74 68 65 20 63 68 61 6e 6e 65 6c 2e 20 on the channel.
26a0: 54 68 65 20 65 6e 63 6f 64 69 6e 67 0a 74 72 61 The encoding.tra
26b0: 6e 73 66 6f 72 6d 73 20 69 6e 20 75 73 65 20 66 nsforms in use f
26c0: 6f 72 20 74 68 65 20 63 68 61 6e 6e 65 6c 27 73 or the channel's
26d0: 20 69 6e 70 75 74 20 61 6e 64 20 6f 75 74 70 75 input and outpu
26e0: 74 20 77 69 6c 6c 20 74 68 65 6e 20 62 65 20 73 t will then be s
26f0: 75 62 6a 65 63 74 20 74 6f 20 74 68 65 0a 72 75 ubject to the.ru
2700: 6c 65 73 20 6f 66 20 74 68 61 74 20 70 72 6f 66 les of that prof
2710: 69 6c 65 2e 20 41 6e 79 20 66 61 69 6c 75 72 65 ile. Any failure
2720: 73 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e s will result in
2730: 20 61 20 63 68 61 6e 6e 65 6c 20 65 72 72 6f 72 a channel error
2740: 2e 20 53 65 65 0a 5c 66 42 50 52 4f 46 49 4c 45 . See.\fBPROFILE
2750: 53 5c 66 52 20 69 6e 20 74 68 65 20 5c 66 42 65 S\fR in the \fBe
2760: 6e 63 6f 64 69 6e 67 28 6e 29 5c 66 52 20 64 6f ncoding(n)\fR do
2770: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
2780: 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 65 6e details about en
2790: 63 6f 64 69 6e 67 0a 70 72 6f 66 69 6c 65 73 2e coding.profiles.
27a0: 0a 2e 56 45 20 22 54 43 4c 38 2e 37 20 54 49 50 ..VE "TCL8.7 TIP
27b0: 36 35 36 22 0a 2e 5c 22 20 4f 50 54 49 4f 4e 3a 656"..\" OPTION:
27c0: 20 2d 74 72 61 6e 73 6c 61 74 69 6f 6e 0a 2e 54 -translation..T
27d0: 50 0a 5c 66 42 5c 2d 74 72 61 6e 73 6c 61 74 69 P.\fB\-translati
27e0: 6f 6e 5c 66 49 20 74 72 61 6e 73 6c 61 74 69 6f on\fI translatio
27f0: 6e 5c 66 52 0a 2e 54 50 0a 5c 66 42 5c 2d 74 72 n\fR..TP.\fB\-tr
2800: 61 6e 73 6c 61 74 69 6f 6e 5c 66 52 20 5c 66 42 anslation\fR \fB
2810: 7b 5c 66 49 69 6e 54 72 61 6e 73 6c 61 74 69 6f {\fIinTranslatio
2820: 6e 20 6f 75 74 54 72 61 6e 73 6c 61 74 69 6f 6e n outTranslation
2830: 5c 66 42 7d 5c 66 52 0a 2e 0a 49 6e 20 54 63 6c \fB}\fR...In Tcl
2840: 20 73 63 72 69 70 74 73 20 74 68 65 20 65 6e 64 scripts the end
2850: 20 6f 66 20 61 20 6c 69 6e 65 20 69 73 20 61 6c of a line is al
2860: 77 61 79 73 20 72 65 70 72 65 73 65 6e 74 65 64 ways represented
2870: 20 75 73 69 6e 67 20 61 20 73 69 6e 67 6c 65 0a using a single.
2880: 6e 65 77 6c 69 6e 65 20 63 68 61 72 61 63 74 65 newline characte
2890: 72 20 28 5c 65 6e 29 2e 20 20 48 6f 77 65 76 65 r (\en). Howeve
28a0: 72 2c 20 69 6e 20 61 63 74 75 61 6c 20 66 69 6c r, in actual fil
28b0: 65 73 20 61 6e 64 20 64 65 76 69 63 65 73 20 74 es and devices t
28c0: 68 65 20 65 6e 64 0a 6f 66 20 61 20 6c 69 6e 65 he end.of a line
28d0: 20 6d 61 79 20 62 65 20 72 65 70 72 65 73 65 6e may be represen
28e0: 74 65 64 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ted differently
28f0: 6f 6e 20 64 69 66 66 65 72 65 6e 74 20 70 6c 61 on different pla
2900: 74 66 6f 72 6d 73 2c 20 6f 72 0a 65 76 65 6e 20 tforms, or.even
2910: 66 6f 72 20 64 69 66 66 65 72 65 6e 74 20 64 65 for different de
2920: 76 69 63 65 73 20 6f 6e 20 74 68 65 20 73 61 6d vices on the sam
2930: 65 20 70 6c 61 74 66 6f 72 6d 2e 20 20 46 6f 72 e platform. For
2940: 20 65 78 61 6d 70 6c 65 2c 20 75 6e 64 65 72 0a example, under.
2950: 55 4e 49 58 20 6e 65 77 6c 69 6e 65 73 20 61 72 UNIX newlines ar
2960: 65 20 75 73 65 64 20 69 6e 20 66 69 6c 65 73 2c e used in files,
2970: 20 77 68 65 72 65 61 73 20 63 61 72 72 69 61 67 whereas carriag
2980: 65 2d 72 65 74 75 72 6e 2d 6c 69 6e 65 66 65 65 e-return-linefee
2990: 64 0a 73 65 71 75 65 6e 63 65 73 20 61 72 65 20 d.sequences are
29a0: 6e 6f 72 6d 61 6c 6c 79 20 75 73 65 64 20 69 6e normally used in
29b0: 20 6e 65 74 77 6f 72 6b 20 63 6f 6e 6e 65 63 74 network connect
29c0: 69 6f 6e 73 2e 20 20 4f 6e 20 69 6e 70 75 74 20 ions. On input
29d0: 28 69 2e 65 2e 2c 0a 77 69 74 68 20 5c 66 42 63 (i.e.,.with \fBc
29e0: 68 61 6e 20 67 65 74 73 5c 66 52 20 61 6e 64 20 han gets\fR and
29f0: 5c 66 42 63 68 61 6e 20 72 65 61 64 5c 66 52 29 \fBchan read\fR)
2a00: 20 74 68 65 20 54 63 6c 20 49 2f 4f 20 73 79 73 the Tcl I/O sys
2a10: 74 65 6d 0a 61 75 74 6f 6d 61 74 69 63 61 6c 6c tem.automaticall
2a20: 79 20 74 72 61 6e 73 6c 61 74 65 73 20 74 68 65 y translates the
2a30: 20 65 78 74 65 72 6e 61 6c 20 65 6e 64 2d 6f 66 external end-of
2a40: 2d 6c 69 6e 65 20 72 65 70 72 65 73 65 6e 74 61 -line representa
2a50: 74 69 6f 6e 20 69 6e 74 6f 0a 6e 65 77 6c 69 6e tion into.newlin
2a60: 65 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 55 e characters. U
2a70: 70 6f 6e 20 6f 75 74 70 75 74 20 28 69 2e 65 2e pon output (i.e.
2a80: 2c 20 77 69 74 68 20 5c 66 42 63 68 61 6e 20 70 , with \fBchan p
2a90: 75 74 73 5c 66 52 29 2c 20 74 68 65 20 49 2f 4f uts\fR), the I/O
2aa0: 0a 73 79 73 74 65 6d 20 74 72 61 6e 73 6c 61 74 .system translat
2ab0: 65 73 20 6e 65 77 6c 69 6e 65 73 20 74 6f 20 74 es newlines to t
2ac0: 68 65 20 65 78 74 65 72 6e 61 6c 20 65 6e 64 2d he external end-
2ad0: 6f 66 2d 6c 69 6e 65 20 72 65 70 72 65 73 65 6e of-line represen
2ae0: 74 61 74 69 6f 6e 2e 0a 54 68 65 20 64 65 66 61 tation..The defa
2af0: 75 6c 74 20 74 72 61 6e 73 6c 61 74 69 6f 6e 20 ult translation
2b00: 6d 6f 64 65 2c 20 5c 66 42 61 75 74 6f 5c 66 52 mode, \fBauto\fR
2b10: 2c 20 68 61 6e 64 6c 65 73 20 61 6c 6c 20 74 68 , handles all th
2b20: 65 20 63 6f 6d 6d 6f 6e 20 63 61 73 65 73 0a 61 e common cases.a
2b30: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2c 20 62 75 utomatically, bu
2b40: 74 20 74 68 65 20 5c 66 42 5c 2d 74 72 61 6e 73 t the \fB\-trans
2b50: 6c 61 74 69 6f 6e 5c 66 52 20 6f 70 74 69 6f 6e lation\fR option
2b60: 20 70 72 6f 76 69 64 65 73 20 65 78 70 6c 69 63 provides explic
2b70: 69 74 0a 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 it.control over
2b80: 74 68 65 20 65 6e 64 20 6f 66 20 6c 69 6e 65 20 the end of line
2b90: 74 72 61 6e 73 6c 61 74 69 6f 6e 73 2e 0a 2e 52 translations...R
2ba0: 53 0a 2e 50 50 0a 54 68 65 20 76 61 6c 75 65 20 S..PP.The value
2bb0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2bc0: 5c 66 42 5c 2d 74 72 61 6e 73 6c 61 74 69 6f 6e \fB\-translation
2bd0: 5c 66 52 20 69 73 20 61 20 73 69 6e 67 6c 65 20 \fR is a single
2be0: 69 74 65 6d 20 66 6f 72 0a 72 65 61 64 2d 6f 6e item for.read-on
2bf0: 6c 79 20 61 6e 64 20 77 72 69 74 65 2d 6f 6e 6c ly and write-onl
2c00: 79 20 63 68 61 6e 6e 65 6c 73 2e 20 20 54 68 65 y channels. The
2c10: 20 76 61 6c 75 65 20 69 73 20 61 20 74 77 6f 2d value is a two-
2c20: 65 6c 65 6d 65 6e 74 20 6c 69 73 74 20 66 6f 72 element list for
2c30: 0a 72 65 61 64 2d 77 72 69 74 65 20 63 68 61 6e .read-write chan
2c40: 6e 65 6c 73 3b 20 74 68 65 20 72 65 61 64 20 74 nels; the read t
2c50: 72 61 6e 73 6c 61 74 69 6f 6e 20 6d 6f 64 65 20 ranslation mode
2c60: 69 73 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 is the first ele
2c70: 6d 65 6e 74 20 6f 66 0a 74 68 65 20 6c 69 73 74 ment of.the list
2c80: 2c 20 61 6e 64 20 74 68 65 20 77 72 69 74 65 20 , and the write
2c90: 74 72 61 6e 73 6c 61 74 69 6f 6e 20 6d 6f 64 65 translation mode
2ca0: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 65 is the second e
2cb0: 6c 65 6d 65 6e 74 2e 20 20 41 73 20 61 0a 63 6f lement. As a.co
2cc0: 6e 76 65 6e 69 65 6e 63 65 2c 20 77 68 65 6e 20 nvenience, when
2cd0: 73 65 74 74 69 6e 67 20 74 68 65 20 74 72 61 6e setting the tran
2ce0: 73 6c 61 74 69 6f 6e 20 6d 6f 64 65 20 66 6f 72 slation mode for
2cf0: 20 61 20 72 65 61 64 2d 77 72 69 74 65 20 63 68 a read-write ch
2d00: 61 6e 6e 65 6c 0a 79 6f 75 20 63 61 6e 20 73 70 annel.you can sp
2d10: 65 63 69 66 79 20 61 20 73 69 6e 67 6c 65 20 76 ecify a single v
2d20: 61 6c 75 65 20 74 68 61 74 20 77 69 6c 6c 20 61 alue that will a
2d30: 70 70 6c 79 20 74 6f 20 62 6f 74 68 20 72 65 61 pply to both rea
2d40: 64 69 6e 67 20 61 6e 64 0a 77 72 69 74 69 6e 67 ding and.writing
2d50: 2e 20 20 57 68 65 6e 20 71 75 65 72 79 69 6e 67 . When querying
2d60: 20 74 68 65 20 74 72 61 6e 73 6c 61 74 69 6f 6e the translation
2d70: 20 6d 6f 64 65 20 6f 66 20 61 20 72 65 61 64 2d mode of a read-
2d80: 77 72 69 74 65 20 63 68 61 6e 6e 65 6c 2c 20 61 write channel, a
2d90: 0a 74 77 6f 2d 65 6c 65 6d 65 6e 74 20 6c 69 73 .two-element lis
2da0: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 t will always be
2db0: 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
2dc0: 66 6f 6c 6c 6f 77 69 6e 67 20 76 61 6c 75 65 73 following values
2dd0: 20 61 72 65 0a 63 75 72 72 65 6e 74 6c 79 20 73 are.currently s
2de0: 75 70 70 6f 72 74 65 64 3a 0a 2e 49 50 20 5c 66 upported:..IP \f
2df0: 42 61 75 74 6f 5c 66 52 0a 41 73 20 74 68 65 20 Bauto\fR.As the
2e00: 69 6e 70 75 74 20 74 72 61 6e 73 6c 61 74 69 6f input translatio
2e10: 6e 20 6d 6f 64 65 2c 20 5c 66 42 61 75 74 6f 5c n mode, \fBauto\
2e20: 66 52 20 74 72 65 61 74 73 20 61 6e 79 20 6f 66 fR treats any of
2e30: 20 6e 65 77 6c 69 6e 65 0a 28 5c 66 42 6c 66 5c newline.(\fBlf\
2e40: 66 52 29 2c 20 63 61 72 72 69 61 67 65 20 72 65 fR), carriage re
2e50: 74 75 72 6e 20 28 5c 66 42 63 72 5c 66 52 29 2c turn (\fBcr\fR),
2e60: 20 6f 72 20 63 61 72 72 69 61 67 65 20 72 65 74 or carriage ret
2e70: 75 72 6e 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a urn followed by.
2e80: 61 20 6e 65 77 6c 69 6e 65 20 28 5c 66 42 63 72 a newline (\fBcr
2e90: 6c 66 5c 66 52 29 20 61 73 20 74 68 65 20 65 6e lf\fR) as the en
2ea0: 64 20 6f 66 20 6c 69 6e 65 20 72 65 70 72 65 73 d of line repres
2eb0: 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 65 entation. The e
2ec0: 6e 64 20 6f 66 0a 6c 69 6e 65 20 72 65 70 72 65 nd of.line repre
2ed0: 73 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 65 76 sentation can ev
2ee0: 65 6e 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6c en change from l
2ef0: 69 6e 65 2d 74 6f 2d 6c 69 6e 65 2c 20 61 6e 64 ine-to-line, and
2f00: 20 61 6c 6c 20 63 61 73 65 73 0a 61 72 65 20 74 all cases.are t
2f10: 72 61 6e 73 6c 61 74 65 64 20 74 6f 20 61 20 6e ranslated to a n
2f20: 65 77 6c 69 6e 65 2e 20 20 41 73 20 74 68 65 20 ewline. As the
2f30: 6f 75 74 70 75 74 20 74 72 61 6e 73 6c 61 74 69 output translati
2f40: 6f 6e 20 6d 6f 64 65 2c 0a 5c 66 42 61 75 74 6f on mode,.\fBauto
2f50: 5c 66 52 20 63 68 6f 6f 73 65 73 20 61 20 70 6c \fR chooses a pl
2f60: 61 74 66 6f 72 6d 20 73 70 65 63 69 66 69 63 20 atform specific
2f70: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 3b 20 representation;
2f80: 66 6f 72 20 73 6f 63 6b 65 74 73 20 6f 6e 0a 61 for sockets on.a
2f90: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 20 54 63 6c ll platforms Tcl
2fa0: 20 63 68 6f 6f 73 65 73 20 5c 66 42 63 72 6c 66 chooses \fBcrlf
2fb0: 5c 66 52 2c 20 66 6f 72 20 61 6c 6c 20 55 6e 69 \fR, for all Uni
2fc0: 78 20 66 6c 61 76 6f 72 73 2c 20 69 74 20 63 68 x flavors, it ch
2fd0: 6f 6f 73 65 73 0a 5c 66 42 6c 66 5c 66 52 2c 20 ooses.\fBlf\fR,
2fe0: 61 6e 64 20 66 6f 72 20 74 68 65 20 76 61 72 69 and for the vari
2ff0: 6f 75 73 20 66 6c 61 76 6f 72 73 20 6f 66 20 57 ous flavors of W
3000: 69 6e 64 6f 77 73 20 69 74 20 63 68 6f 6f 73 65 indows it choose
3010: 73 0a 5c 66 42 63 72 6c 66 5c 66 52 2e 20 20 54 s.\fBcrlf\fR. T
3020: 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
3030: 6e 67 20 66 6f 72 20 5c 66 42 5c 2d 74 72 61 6e ng for \fB\-tran
3040: 73 6c 61 74 69 6f 6e 5c 66 52 20 69 73 20 5c 66 slation\fR is \f
3050: 42 61 75 74 6f 5c 66 52 0a 66 6f 72 20 62 6f 74 Bauto\fR.for bot
3060: 68 20 69 6e 70 75 74 20 61 6e 64 20 6f 75 74 70 h input and outp
3070: 75 74 2e 0a 2e 49 50 20 5c 66 42 62 69 6e 61 72 ut...IP \fBbinar
3080: 79 5c 66 52 0a 4c 69 6b 65 20 5c 66 42 6c 66 5c y\fR.Like \fBlf\
3090: 66 52 2c 20 6e 6f 20 65 6e 64 2d 6f 66 2d 6c 69 fR, no end-of-li
30a0: 6e 65 20 74 72 61 6e 73 6c 61 74 69 6f 6e 20 69 ne translation i
30b0: 73 20 70 65 72 66 6f 72 6d 65 64 2c 20 62 75 74 s performed, but
30c0: 20 69 6e 20 61 64 64 69 74 69 6f 6e 2c 20 73 65 in addition, se
30d0: 74 73 0a 5c 66 42 5c 2d 65 6f 66 63 68 61 72 5c ts.\fB\-eofchar\
30e0: 66 52 20 74 6f 20 74 68 65 20 65 6d 70 74 79 20 fR to the empty
30f0: 73 74 72 69 6e 67 20 74 6f 20 64 69 73 61 62 6c string to disabl
3100: 65 20 69 74 2c 20 61 6e 64 20 73 65 74 73 20 5c e it, and sets \
3110: 66 42 5c 2d 65 6e 63 6f 64 69 6e 67 5c 66 52 0a fB\-encoding\fR.
3120: 74 6f 20 5c 66 42 69 73 6f 38 38 35 39 2d 31 5c to \fBiso8859-1\
3130: 66 52 2e 20 20 57 69 74 68 20 74 68 69 73 20 6f fR. With this o
3140: 6e 65 20 73 65 74 74 69 6e 67 2c 20 61 20 63 68 ne setting, a ch
3150: 61 6e 6e 65 6c 20 69 73 20 66 75 6c 6c 79 20 63 annel is fully c
3160: 6f 6e 66 69 67 75 72 65 64 0a 66 6f 72 20 62 69 onfigured.for bi
3170: 6e 61 72 79 20 69 6e 70 75 74 20 61 6e 64 20 6f nary input and o
3180: 75 74 70 75 74 3a 20 20 45 61 63 68 20 62 79 74 utput: Each byt
3190: 65 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 e read from the
31a0: 63 68 61 6e 6e 65 6c 0a 62 65 63 6f 6d 65 73 20 channel.becomes
31b0: 74 68 65 20 55 6e 69 63 6f 64 65 20 63 68 61 72 the Unicode char
31c0: 61 63 74 65 72 20 68 61 76 69 6e 67 20 74 68 65 acter having the
31d0: 20 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 same value as t
31e0: 68 61 74 20 62 79 74 65 2c 20 61 6e 64 20 65 61 hat byte, and ea
31f0: 63 68 0a 63 68 61 72 61 63 74 65 72 20 77 72 69 ch.character wri
3200: 74 74 65 6e 20 74 6f 20 74 68 65 20 63 68 61 6e tten to the chan
3210: 6e 65 6c 20 62 65 63 6f 6d 65 73 20 61 20 73 69 nel becomes a si
3220: 6e 67 6c 65 20 62 79 74 65 20 69 6e 20 74 68 65 ngle byte in the
3230: 20 6f 75 74 70 75 74 2e 20 20 54 68 69 73 0a 6d output. This.m
3240: 61 6b 65 73 20 69 74 20 70 6f 73 73 69 62 6c 65 akes it possible
3250: 20 74 6f 20 77 6f 72 6b 20 73 65 61 6d 6c 65 73 to work seamles
3260: 73 6c 79 20 77 69 74 68 20 62 69 6e 61 72 79 20 sly with binary
3270: 64 61 74 61 20 61 73 20 6c 6f 6e 67 20 61 73 20 data as long as
3280: 65 61 63 68 20 63 68 61 72 61 63 74 65 72 0a 69 each character.i
3290: 6e 20 74 68 65 20 64 61 74 61 20 72 65 6d 61 69 n the data remai
32a0: 6e 73 20 69 6e 20 74 68 65 20 72 61 6e 67 65 20 ns in the range
32b0: 6f 66 20 30 20 74 6f 20 32 35 35 20 73 6f 20 74 of 0 to 255 so t
32c0: 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hat there is no
32d0: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 62 65 74 77 distinction.betw
32e0: 65 65 6e 20 62 69 6e 61 72 79 20 64 61 74 61 20 een binary data
32f0: 61 6e 64 20 74 65 78 74 2e 20 20 46 6f 72 20 65 and text. For e
3300: 78 61 6d 70 6c 65 2c 20 41 20 4a 50 45 47 20 69 xample, A JPEG i
3310: 6d 61 67 65 20 63 61 6e 20 62 65 20 72 65 61 64 mage can be read
3320: 20 66 72 6f 6d 20 61 0a 73 75 63 68 20 61 20 63 from a.such a c
3330: 68 61 6e 6e 65 6c 2c 20 6d 61 6e 69 70 75 6c 61 hannel, manipula
3340: 74 65 64 2c 20 61 6e 64 20 74 68 65 6e 20 77 72 ted, and then wr
3350: 69 74 74 65 6e 20 62 61 63 6b 20 74 6f 20 73 75 itten back to su
3360: 63 68 20 61 20 63 68 61 6e 6e 65 6c 2e 0a 2e 49 ch a channel...I
3370: 50 20 5c 66 42 63 72 5c 66 52 0a 54 68 65 20 65 P \fBcr\fR.The e
3380: 6e 64 20 6f 66 20 61 20 6c 69 6e 65 20 69 6e 20 nd of a line in
3390: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 66 the underlying f
33a0: 69 6c 65 20 6f 72 20 64 65 76 69 63 65 20 69 73 ile or device is
33b0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
33c0: 61 0a 73 69 6e 67 6c 65 20 63 61 72 72 69 61 67 a.single carriag
33d0: 65 20 72 65 74 75 72 6e 20 63 68 61 72 61 63 74 e return charact
33e0: 65 72 2e 20 20 41 73 20 74 68 65 20 69 6e 70 75 er. As the inpu
33f0: 74 20 74 72 61 6e 73 6c 61 74 69 6f 6e 20 6d 6f t translation mo
3400: 64 65 2c 0a 5c 66 42 63 72 5c 66 52 20 6d 6f 64 de,.\fBcr\fR mod
3410: 65 20 63 6f 6e 76 65 72 74 73 20 63 61 72 72 69 e converts carri
3420: 61 67 65 20 72 65 74 75 72 6e 73 20 74 6f 20 6e age returns to n
3430: 65 77 6c 69 6e 65 20 63 68 61 72 61 63 74 65 72 ewline character
3440: 73 2e 20 20 41 73 20 74 68 65 0a 6f 75 74 70 75 s. As the.outpu
3450: 74 20 74 72 61 6e 73 6c 61 74 69 6f 6e 20 6d 6f t translation mo
3460: 64 65 2c 20 5c 66 42 63 72 5c 66 52 20 6d 6f 64 de, \fBcr\fR mod
3470: 65 20 74 72 61 6e 73 6c 61 74 65 73 20 6e 65 77 e translates new
3480: 6c 69 6e 65 20 63 68 61 72 61 63 74 65 72 73 0a line characters.
3490: 74 6f 20 63 61 72 72 69 61 67 65 20 72 65 74 75 to carriage retu
34a0: 72 6e 73 2e 0a 2e 49 50 20 5c 66 42 63 72 6c 66 rns...IP \fBcrlf
34b0: 5c 66 52 0a 54 68 65 20 65 6e 64 20 6f 66 20 61 \fR.The end of a
34c0: 20 6c 69 6e 65 20 69 6e 20 74 68 65 20 75 6e 64 line in the und
34d0: 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 6f 72 20 erlying file or
34e0: 64 65 76 69 63 65 20 69 73 20 72 65 70 72 65 73 device is repres
34f0: 65 6e 74 65 64 20 62 79 20 61 0a 63 61 72 72 69 ented by a.carri
3500: 61 67 65 20 72 65 74 75 72 6e 20 63 68 61 72 61 age return chara
3510: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 cter followed by
3520: 20 61 20 6c 69 6e 65 66 65 65 64 20 63 68 61 72 a linefeed char
3530: 61 63 74 65 72 2e 20 20 41 73 20 74 68 65 0a 69 acter. As the.i
3540: 6e 70 75 74 20 74 72 61 6e 73 6c 61 74 69 6f 6e nput translation
3550: 20 6d 6f 64 65 2c 20 5c 66 42 63 72 6c 66 5c 66 mode, \fBcrlf\f
3560: 52 20 6d 6f 64 65 20 63 6f 6e 76 65 72 74 73 0a R mode converts.
3570: 63 61 72 72 69 61 67 65 2d 72 65 74 75 72 6e 2d carriage-return-
3580: 6c 69 6e 65 66 65 65 64 20 73 65 71 75 65 6e 63 linefeed sequenc
3590: 65 73 20 74 6f 20 6e 65 77 6c 69 6e 65 20 63 68 es to newline ch
35a0: 61 72 61 63 74 65 72 73 2e 20 20 41 73 20 74 68 aracters. As th
35b0: 65 0a 6f 75 74 70 75 74 20 74 72 61 6e 73 6c 61 e.output transla
35c0: 74 69 6f 6e 20 6d 6f 64 65 2c 20 5c 66 42 63 72 tion mode, \fBcr
35d0: 6c 66 5c 66 52 20 6d 6f 64 65 20 74 72 61 6e 73 lf\fR mode trans
35e0: 6c 61 74 65 73 20 6e 65 77 6c 69 6e 65 20 63 68 lates newline ch
35f0: 61 72 61 63 74 65 72 73 0a 74 6f 20 63 61 72 72 aracters.to carr
3600: 69 61 67 65 2d 72 65 74 75 72 6e 2d 6c 69 6e 65 iage-return-line
3610: 66 65 65 64 20 73 65 71 75 65 6e 63 65 73 2e 20 feed sequences.
3620: 20 54 68 69 73 20 6d 6f 64 65 20 69 73 20 74 79 This mode is ty
3630: 70 69 63 61 6c 6c 79 20 75 73 65 64 20 6f 6e 0a pically used on.
3640: 57 69 6e 64 6f 77 73 20 70 6c 61 74 66 6f 72 6d Windows platform
3650: 73 20 61 6e 64 20 66 6f 72 20 6e 65 74 77 6f 72 s and for networ
3660: 6b 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2e k connections...
3670: 49 50 20 5c 66 42 6c 66 5c 66 52 0a 54 68 65 20 IP \fBlf\fR.The
3680: 65 6e 64 20 6f 66 20 61 20 6c 69 6e 65 20 69 6e end of a line in
3690: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
36a0: 66 69 6c 65 20 6f 72 20 64 65 76 69 63 65 20 69 file or device i
36b0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
36c0: 20 61 0a 73 69 6e 67 6c 65 20 6e 65 77 6c 69 6e a.single newlin
36d0: 65 20 28 6c 69 6e 65 66 65 65 64 29 20 63 68 61 e (linefeed) cha
36e0: 72 61 63 74 65 72 2e 20 20 49 6e 20 74 68 69 73 racter. In this
36f0: 20 6d 6f 64 65 20 6e 6f 20 74 72 61 6e 73 6c 61 mode no transla
3700: 74 69 6f 6e 73 0a 6f 63 63 75 72 20 64 75 72 69 tions.occur duri
3710: 6e 67 20 65 69 74 68 65 72 20 69 6e 70 75 74 20 ng either input
3720: 6f 72 20 6f 75 74 70 75 74 2e 20 20 54 68 69 73 or output. This
3730: 20 6d 6f 64 65 20 69 73 20 74 79 70 69 63 61 6c mode is typical
3740: 6c 79 20 75 73 65 64 20 6f 6e 0a 55 4e 49 58 20 ly used on.UNIX
3750: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2e 52 45 0a 2e platforms...RE..
3760: 5c 22 20 4d 45 54 48 4f 44 3a 20 63 6f 70 79 0a \" METHOD: copy.
3770: 2e 54 50 0a 5c 66 42 63 68 61 6e 20 63 6f 70 79 .TP.\fBchan copy
3780: 20 5c 66 49 69 6e 70 75 74 43 68 61 6e 20 6f 75 \fIinputChan ou
3790: 74 70 75 74 43 68 61 6e 5c 66 52 20 3f 5c 66 42 tputChan\fR ?\fB
37a0: 5c 2d 73 69 7a 65 20 5c 66 49 73 69 7a 65 5c 66 \-size \fIsize\f
37b0: 52 3f 20 3f 5c 66 42 5c 2d 63 6f 6d 6d 61 6e 64 R? ?\fB\-command
37c0: 20 5c 66 49 63 61 6c 6c 62 61 63 6b 5c 66 52 3f \fIcallback\fR?
37d0: 0a 2e 0a 52 65 61 64 73 20 63 68 61 72 61 63 74 ...Reads charact
37e0: 65 72 73 20 66 72 6f 6d 20 5c 66 49 69 6e 70 75 ers from \fIinpu
37f0: 74 43 68 61 6e 5c 66 52 20 61 6e 64 20 77 72 69 tChan\fR and wri
3800: 74 65 73 20 74 68 65 6d 20 74 6f 20 5c 66 49 6f tes them to \fIo
3810: 75 74 70 75 74 43 68 61 6e 5c 66 52 20 75 6e 74 utputChan\fR unt
3820: 69 6c 0a 61 6c 6c 20 63 68 61 72 61 63 74 65 72 il.all character
3830: 73 20 61 72 65 20 63 6f 70 69 65 64 2c 20 62 6c s are copied, bl
3840: 6f 63 6b 69 6e 67 20 75 6e 74 69 6c 20 74 68 65 ocking until the
3850: 20 63 6f 70 79 20 69 73 20 63 6f 6d 70 6c 65 74 copy is complet
3860: 65 20 61 6e 64 20 72 65 74 75 72 6e 69 6e 67 0a e and returning.
3870: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
3880: 61 72 61 63 74 65 72 73 20 63 6f 70 69 65 64 2e aracters copied.
3890: 20 20 4c 65 76 65 72 61 67 65 73 20 69 6e 74 65 Leverages inte
38a0: 72 6e 61 6c 20 62 75 66 66 65 72 73 20 74 6f 20 rnal buffers to
38b0: 61 76 6f 69 64 20 65 78 74 72 61 0a 63 6f 70 69 avoid extra.copi
38c0: 65 73 20 61 6e 64 20 74 6f 20 61 76 6f 69 64 20 es and to avoid
38d0: 62 75 66 66 65 72 69 6e 67 20 74 6f 6f 20 6d 75 buffering too mu
38e0: 63 68 20 64 61 74 61 20 69 6e 20 6d 61 69 6e 20 ch data in main
38f0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 63 6f 70 79 memory when copy
3900: 69 6e 67 20 6c 61 72 67 65 0a 66 69 6c 65 73 20 ing large.files
3910: 74 6f 20 73 6c 6f 77 20 64 65 73 74 69 6e 61 74 to slow destinat
3920: 69 6f 6e 73 20 6c 69 6b 65 20 6e 65 74 77 6f 72 ions like networ
3930: 6b 20 73 6f 63 6b 65 74 73 2e 0a 2e 52 53 0a 2e k sockets...RS..
3940: 50 50 0a 5c 66 42 5c 2d 73 69 7a 65 5c 66 52 20 PP.\fB\-size\fR
3950: 6c 69 6d 69 74 73 20 74 68 65 20 6e 75 6d 62 65 limits the numbe
3960: 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
3970: 63 6f 70 69 65 64 2e 0a 2e 50 50 0a 49 66 20 5c copied...PP.If \
3980: 66 42 5c 2d 63 6f 6d 6d 61 6e 64 5c 66 52 20 69 fB\-command\fR i
3990: 73 20 67 69 76 65 6e 2c 20 5c 66 42 63 68 61 6e s given, \fBchan
39a0: 20 63 6f 70 79 5c 66 52 20 72 65 74 75 72 6e 73 copy\fR returns
39b0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 77 6f immediately, wo
39c0: 72 6b 73 20 69 6e 20 74 68 65 0a 62 61 63 6b 67 rks in the.backg
39d0: 72 6f 75 6e 64 2c 20 61 6e 64 20 63 61 6c 6c 73 round, and calls
39e0: 20 5c 66 49 63 61 6c 6c 62 61 63 6b 5c 66 52 20 \fIcallback\fR
39f0: 77 68 65 6e 20 74 68 65 20 63 6f 70 79 20 63 6f when the copy co
3a00: 6d 70 6c 65 74 65 73 2c 20 70 72 6f 76 69 64 69 mpletes, providi
3a10: 6e 67 20 61 73 20 61 6e 0a 61 64 64 69 74 69 6f ng as an.additio
3a20: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 68 65 nal argument the
3a30: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
3a40: 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 74 6f cters written to
3a50: 20 5c 66 49 6f 75 74 70 75 74 43 68 61 6e 5c 66 \fIoutputChan\f
3a60: 52 2e 20 20 49 66 0a 61 6e 20 65 72 72 6f 72 20 R. If.an error
3a70: 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
3a80: 65 20 62 61 63 6b 67 72 6f 75 6e 64 20 63 6f 70 e background cop
3a90: 79 2c 20 61 6e 6f 74 68 65 72 20 61 72 67 75 6d y, another argum
3aa0: 65 6e 74 20 70 72 6f 76 69 64 65 73 20 6d 65 73 ent provides mes
3ab0: 73 61 67 65 0a 66 6f 72 20 74 68 65 20 65 72 72 sage.for the err
3ac0: 6f 72 2e 20 20 5c 66 49 69 6e 70 75 74 43 68 61 or. \fIinputCha
3ad0: 6e 5c 66 52 20 61 6e 64 20 5c 66 49 6f 75 74 70 n\fR and \fIoutp
3ae0: 75 74 43 68 61 6e 5c 66 52 20 61 72 65 20 61 75 utChan\fR are au
3af0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 63 6f 6e 66 tomatically.conf
3b00: 69 67 75 72 65 64 20 66 6f 72 20 6e 6f 6e 2d 62 igured for non-b
3b10: 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 20 69 66 20 locking mode if
3b20: 6e 65 65 64 65 64 2e 20 20 42 61 63 6b 67 72 6f needed. Backgro
3b30: 75 6e 64 20 63 6f 70 79 69 6e 67 20 6f 6e 6c 79 und copying only
3b40: 20 77 6f 72 6b 73 0a 63 6f 72 72 65 63 74 6c 79 works.correctly
3b50: 20 69 66 20 65 76 65 6e 74 73 20 61 72 65 20 62 if events are b
3b60: 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2c 20 eing processed,
3b70: 65 2e 67 2e 20 76 69 61 20 5c 66 42 76 77 61 69 e.g. via \fBvwai
3b80: 74 5c 66 52 20 6f 72 20 54 6b 2e 0a 2e 50 50 0a t\fR or Tk...PP.
3b90: 44 75 72 69 6e 67 20 61 20 62 61 63 6b 67 72 6f During a backgro
3ba0: 75 6e 64 20 63 6f 70 79 20 6e 6f 20 6f 74 68 65 und copy no othe
3bb0: 72 20 72 65 61 64 20 6f 70 65 72 61 74 69 6f 6e r read operation
3bc0: 20 6d 61 79 20 62 65 20 70 65 72 66 6f 72 6d 65 may be performe
3bd0: 64 20 6f 6e 0a 5c 66 49 69 6e 70 75 74 43 68 61 d on.\fIinputCha
3be0: 6e 5c 66 52 2c 20 61 6e 64 20 6e 6f 20 77 72 69 n\fR, and no wri
3bf0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 te operation may
3c00: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e be performed on
3c10: 0a 5c 66 49 6f 75 74 70 75 74 43 68 61 6e 5c 66 .\fIoutputChan\f
3c20: 52 2e 20 20 48 6f 77 65 76 65 72 2c 20 77 72 69 R. However, wri
3c30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 6d 61 te operations ma
3c40: 79 20 62 79 20 70 65 72 66 6f 72 6d 65 64 20 6f y by performed o
3c50: 6e 0a 5c 66 49 69 6e 70 75 74 43 68 61 6e 5c 66 n.\fIinputChan\f
3c60: 52 20 61 6e 64 20 72 65 61 64 20 6f 70 65 72 61 R and read opera
3c70: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 70 65 72 tions may be per
3c80: 66 6f 72 6d 65 64 20 6f 6e 20 5c 66 49 6f 75 74 formed on \fIout
3c90: 70 75 74 43 68 61 6e 5c 66 52 2c 20 61 73 0a 65 putChan\fR, as.e
3ca0: 78 68 69 62 69 74 65 64 20 62 79 20 74 68 65 20 xhibited by the
3cb0: 62 69 64 69 72 65 63 74 69 6f 6e 61 6c 20 63 6f bidirectional co
3cc0: 70 79 20 65 78 61 6d 70 6c 65 20 62 65 6c 6f 77 py example below
3cd0: 2e 0a 2e 50 50 0a 49 66 20 65 69 74 68 65 72 20 ...PP.If either
3ce0: 5c 66 49 69 6e 70 75 74 43 68 61 6e 5c 66 52 20 \fIinputChan\fR
3cf0: 6f 72 20 5c 66 49 6f 75 74 70 75 74 43 68 61 6e or \fIoutputChan
3d00: 5c 66 52 20 69 73 20 63 6c 6f 73 65 64 20 77 68 \fR is closed wh
3d10: 69 6c 65 20 74 68 65 20 63 6f 70 79 20 69 73 20 ile the copy is
3d20: 69 6e 0a 70 72 6f 67 72 65 73 73 2c 20 63 6f 70 in.progress, cop
3d30: 79 69 6e 67 20 63 65 61 73 65 73 20 61 6e 64 20 ying ceases and
3d40: 5c 66 42 6e 6f 5c 66 52 20 63 61 6c 6c 62 61 63 \fBno\fR callbac
3d50: 6b 20 69 73 20 6d 61 64 65 2e 20 20 49 66 20 5c k is made. If \
3d60: 66 49 69 6e 70 75 74 43 68 61 6e 5c 66 52 20 69 fIinputChan\fR i
3d70: 73 0a 63 6c 6f 73 65 64 20 61 6c 6c 20 64 61 74 s.closed all dat
3d80: 61 20 61 6c 72 65 61 64 79 20 71 75 65 75 65 64 a already queued
3d90: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 5c is written to \
3da0: 66 49 6f 75 74 70 75 74 43 68 61 6e 5c 66 52 2e fIoutputChan\fR.
3db0: 0a 2e 50 50 0a 54 68 65 72 65 20 73 68 6f 75 6c ..PP.There shoul
3dc0: 64 20 62 65 20 6e 6f 20 65 76 65 6e 74 20 68 61 d be no event ha
3dd0: 6e 64 6c 65 72 20 65 73 74 61 62 6c 69 73 68 65 ndler establishe
3de0: 64 20 66 6f 72 20 5c 66 49 69 6e 70 75 74 43 68 d for \fIinputCh
3df0: 61 6e 5c 66 52 20 20 62 65 63 61 75 73 65 20 69 an\fR because i
3e00: 74 0a 6d 61 79 20 62 65 63 6f 6d 65 20 72 65 61 t.may become rea
3e10: 64 61 62 6c 65 20 64 75 72 69 6e 67 20 61 20 62 dable during a b
3e20: 61 63 6b 67 72 6f 75 6e 64 20 63 6f 70 79 2e 20 ackground copy.
3e30: 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 An attempt to r
3e40: 65 61 64 20 6f 72 20 77 72 69 74 65 20 66 72 6f ead or write fro
3e50: 6d 0a 77 69 74 68 69 6e 20 61 6e 20 65 76 65 6e m.within an even
3e60: 74 20 68 61 6e 64 6c 65 72 20 72 65 73 75 6c 74 t handler result
3e70: 73 20 72 65 73 75 6c 74 20 69 6e 20 74 68 65 20 s result in the
3e80: 65 72 72 6f 72 2c 20 20 22 63 68 61 6e 6e 65 6c error, "channel
3e90: 20 62 75 73 79 22 2e 20 20 41 6e 79 0a 77 72 6f busy". Any.wro
3ea0: 6e 67 2d 73 69 64 65 64 20 49 2f 4f 20 61 74 74 ng-sided I/O att
3eb0: 65 6d 70 74 65 64 20 28 62 79 20 61 20 5c 66 42 empted (by a \fB
3ec0: 63 68 61 6e 20 65 76 65 6e 74 5c 66 52 20 68 61 chan event\fR ha
3ed0: 6e 64 6c 65 72 20 6f 72 20 6f 74 68 65 72 77 69 ndler or otherwi
3ee0: 73 65 29 20 72 65 73 75 6c 74 73 0a 69 6e 20 61 se) results.in a
3ef0: 0a 2e 51 57 20 22 63 68 61 6e 6e 65 6c 20 62 75 ..QW "channel bu
3f00: 73 79 22 0a 65 72 72 6f 72 2e 0a 2e 52 45 0a 2e sy".error...RE..
3f10: 5c 22 20 4d 45 54 48 4f 44 3a 20 63 72 65 61 74 \" METHOD: creat
3f20: 65 0a 2e 54 50 0a 5c 66 42 63 68 61 6e 20 63 72 e..TP.\fBchan cr
3f30: 65 61 74 65 20 5c 66 49 6d 6f 64 65 20 63 6d 64 eate \fImode cmd
3f40: 50 72 65 66 69 78 5c 66 52 0a 2e 0a 54 68 69 73 Prefix\fR...This
3f50: 20 73 75 62 63 6f 6d 6d 61 6e 64 20 63 72 65 61 subcommand crea
3f60: 74 65 73 20 61 20 6e 65 77 20 73 63 72 69 70 74 tes a new script
3f70: 20 6c 65 76 65 6c 20 63 68 61 6e 6e 65 6c 20 75 level channel u
3f80: 73 69 6e 67 20 74 68 65 20 63 6f 6d 6d 61 6e 64 sing the command
3f90: 0a 70 72 65 66 69 78 20 5c 66 49 63 6d 64 50 72 .prefix \fIcmdPr
3fa0: 65 66 69 78 5c 66 52 20 61 73 20 69 74 73 20 68 efix\fR as its h
3fb0: 61 6e 64 6c 65 72 2e 20 41 6e 79 20 73 75 63 68 andler. Any such
3fc0: 20 63 68 61 6e 6e 65 6c 20 69 73 20 63 61 6c 6c channel is call
3fd0: 65 64 20 61 0a 5c 66 42 72 65 66 6c 65 63 74 65 ed a.\fBreflecte
3fe0: 64 5c 66 52 20 63 68 61 6e 6e 65 6c 2e 20 54 68 d\fR channel. Th
3ff0: 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6d 6d e specified comm
4000: 61 6e 64 20 70 72 65 66 69 78 2c 20 5c 66 42 63 and prefix, \fBc
4010: 6d 64 50 72 65 66 69 78 5c 66 52 2c 0a 6d 75 73 mdPrefix\fR,.mus
4020: 74 20 62 65 20 61 20 6e 6f 6e 2d 65 6d 70 74 79 t be a non-empty
4030: 20 6c 69 73 74 2c 20 61 6e 64 20 73 68 6f 75 6c list, and shoul
4040: 64 20 70 72 6f 76 69 64 65 20 74 68 65 20 41 50 d provide the AP
4050: 49 20 64 65 73 63 72 69 62 65 64 20 69 6e 20 74 I described in t
4060: 68 65 0a 5c 66 42 72 65 66 63 68 61 6e 5c 66 52 he.\fBrefchan\fR
4070: 20 6d 61 6e 75 61 6c 20 70 61 67 65 2e 20 54 68 manual page. Th
4080: 65 20 68 61 6e 64 6c 65 20 6f 66 20 74 68 65 20 e handle of the
4090: 6e 65 77 20 63 68 61 6e 6e 65 6c 20 69 73 0a 72 new channel is.r
40a0: 65 74 75 72 6e 65 64 20 61 73 20 74 68 65 20 72 eturned as the r
40b0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 5c 66 42 esult of the \fB
40c0: 63 68 61 6e 20 63 72 65 61 74 65 5c 66 52 20 63 chan create\fR c
40d0: 6f 6d 6d 61 6e 64 2c 20 61 6e 64 20 74 68 65 0a ommand, and the.
40e0: 63 68 61 6e 6e 65 6c 20 69 73 20 6f 70 65 6e 2e channel is open.
40f0: 20 55 73 65 20 65 69 74 68 65 72 20 5c 66 42 63 Use either \fBc
4100: 6c 6f 73 65 5c 66 52 20 6f 72 20 5c 66 42 63 68 lose\fR or \fBch
4110: 61 6e 20 63 6c 6f 73 65 5c 66 52 20 74 6f 20 72 an close\fR to r
4120: 65 6d 6f 76 65 0a 74 68 65 20 63 68 61 6e 6e 65 emove.the channe
4130: 6c 2e 0a 2e 52 53 0a 2e 50 50 0a 54 68 65 20 61 l...RS..PP.The a
4140: 72 67 75 6d 65 6e 74 20 5c 66 49 6d 6f 64 65 5c rgument \fImode\
4150: 66 52 20 73 70 65 63 69 66 69 65 73 20 69 66 20 fR specifies if
4160: 74 68 65 20 6e 65 77 20 63 68 61 6e 6e 65 6c 20 the new channel
4170: 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 0a 72 65 is opened for.re
4180: 61 64 69 6e 67 2c 20 77 72 69 74 69 6e 67 2c 20 ading, writing,
4190: 6f 72 20 62 6f 74 68 2e 20 49 74 20 68 61 73 20 or both. It has
41a0: 74 6f 20 62 65 20 61 20 6c 69 73 74 20 63 6f 6e to be a list con
41b0: 74 61 69 6e 69 6e 67 20 61 6e 79 20 6f 66 20 74 taining any of t
41c0: 68 65 0a 73 74 72 69 6e 67 73 0a 2e 51 57 20 5c he.strings..QW \
41d0: 66 42 72 65 61 64 5c 66 52 0a 6f 72 0a 2e 51 57 fBread\fR.or..QW
41e0: 20 5c 66 42 77 72 69 74 65 5c 66 52 20 2c 0a 54 \fBwrite\fR ,.T
41f0: 68 65 20 6c 69 73 74 20 6d 75 73 74 20 68 61 76 he list must hav
4200: 65 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 0a 65 e at least one.e
4210: 6c 65 6d 65 6e 74 2c 20 61 73 20 61 20 63 68 61 lement, as a cha
4220: 6e 6e 65 6c 20 79 6f 75 20 63 61 6e 20 6e 65 69 nnel you can nei
4230: 74 68 65 72 20 77 72 69 74 65 20 74 6f 20 6e 6f ther write to no
4240: 72 20 72 65 61 64 20 66 72 6f 6d 20 6d 61 6b 65 r read from make
4250: 73 20 6e 6f 0a 73 65 6e 73 65 2e 20 54 68 65 20 s no.sense. The
4260: 68 61 6e 64 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 handler command
4270: 66 6f 72 20 74 68 65 20 6e 65 77 20 63 68 61 6e for the new chan
4280: 6e 65 6c 20 6d 75 73 74 20 73 75 70 70 6f 72 74 nel must support
4290: 20 74 68 65 20 63 68 6f 73 65 6e 0a 6d 6f 64 65 the chosen.mode
42a0: 2c 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 , or an error is
42b0: 20 74 68 72 6f 77 6e 2e 0a 2e 50 50 0a 54 68 65 thrown...PP.The
42c0: 20 63 6f 6d 6d 61 6e 64 20 70 72 65 66 69 78 20 command prefix
42d0: 69 73 20 65 78 65 63 75 74 65 64 20 69 6e 20 74 is executed in t
42e0: 68 65 20 67 6c 6f 62 61 6c 20 6e 61 6d 65 73 70 he global namesp
42f0: 61 63 65 2c 20 61 74 20 74 68 65 20 74 6f 70 20 ace, at the top
4300: 6f 66 0a 63 61 6c 6c 20 73 74 61 63 6b 2c 20 66 of.call stack, f
4310: 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 61 70 70 ollowing the app
4320: 65 6e 64 69 6e 67 20 6f 66 20 61 72 67 75 6d 65 ending of argume
4330: 6e 74 73 20 61 73 20 64 65 73 63 72 69 62 65 64 nts as described
4340: 20 69 6e 20 74 68 65 0a 5c 66 42 72 65 66 63 68 in the.\fBrefch
4350: 61 6e 5c 66 52 20 6d 61 6e 75 61 6c 20 70 61 67 an\fR manual pag
4360: 65 2e 20 43 6f 6d 6d 61 6e 64 20 72 65 73 6f 6c e. Command resol
4370: 75 74 69 6f 6e 20 68 61 70 70 65 6e 73 20 61 74 ution happens at
4380: 20 74 68 65 0a 74 69 6d 65 20 6f 66 20 74 68 65 the.time of the
4390: 20 63 61 6c 6c 2e 20 52 65 6e 61 6d 69 6e 67 20 call. Renaming
43a0: 74 68 65 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 the command, or
43b0: 64 65 73 74 72 6f 79 69 6e 67 20 69 74 20 6d 65 destroying it me
43c0: 61 6e 73 20 74 68 61 74 0a 74 68 65 20 6e 65 78 ans that.the nex
43d0: 74 20 63 61 6c 6c 20 6f 66 20 61 20 68 61 6e 64 t call of a hand
43e0: 6c 65 72 20 6d 65 74 68 6f 64 20 6d 61 79 20 66 ler method may f
43f0: 61 69 6c 2c 20 63 61 75 73 69 6e 67 20 74 68 65 ail, causing the
4400: 20 63 68 61 6e 6e 65 6c 0a 63 6f 6d 6d 61 6e 64 channel.command
4410: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 68 61 invoking the ha
4420: 6e 64 6c 65 72 20 74 6f 20 66 61 69 6c 20 61 73 ndler to fail as
4430: 20 77 65 6c 6c 2e 20 44 65 70 65 6e 64 69 6e 67 well. Depending
4440: 20 6f 6e 20 74 68 65 0a 73 75 62 63 6f 6d 6d 61 on the.subcomma
4450: 6e 64 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64 nd being invoked
4460: 2c 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 , the error mess
4470: 61 67 65 20 6d 61 79 20 6e 6f 74 20 62 65 20 61 age may not be a
4480: 62 6c 65 20 74 6f 20 65 78 70 6c 61 69 6e 0a 74 ble to explain.t
4490: 68 65 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 he reason for th
44a0: 61 74 20 66 61 69 6c 75 72 65 2e 0a 2e 50 50 0a at failure...PP.
44b0: 45 76 65 72 79 20 63 68 61 6e 6e 65 6c 20 63 72 Every channel cr
44c0: 65 61 74 65 64 20 77 69 74 68 20 74 68 69 73 20 eated with this
44d0: 73 75 62 63 6f 6d 6d 61 6e 64 20 6b 6e 6f 77 73 subcommand knows
44e0: 20 77 68 69 63 68 20 69 6e 74 65 72 70 72 65 74 which interpret
44f0: 65 72 20 69 74 0a 77 61 73 20 63 72 65 61 74 65 er it.was create
4500: 64 20 69 6e 2c 20 61 6e 64 20 6f 6e 6c 79 20 65 d in, and only e
4510: 76 65 72 20 65 78 65 63 75 74 65 73 20 69 74 73 ver executes its
4520: 20 68 61 6e 64 6c 65 72 20 63 6f 6d 6d 61 6e 64 handler command
4530: 20 69 6e 20 74 68 61 74 0a 69 6e 74 65 72 70 72 in that.interpr
4540: 65 74 65 72 2c 20 65 76 65 6e 20 69 66 20 74 68 eter, even if th
4550: 65 20 63 68 61 6e 6e 65 6c 20 77 61 73 20 73 68 e channel was sh
4560: 61 72 65 64 20 77 69 74 68 20 61 6e 64 2f 6f 72 ared with and/or
4570: 20 77 61 73 20 6d 6f 76 65 64 20 69 6e 74 6f 0a was moved into.
4580: 61 20 64 69 66 66 65 72 65 6e 74 20 69 6e 74 65 a different inte
4590: 72 70 72 65 74 65 72 2e 20 45 61 63 68 20 72 65 rpreter. Each re
45a0: 66 6c 65 63 74 65 64 20 63 68 61 6e 6e 65 6c 20 flected channel
45b0: 61 6c 73 6f 20 6b 6e 6f 77 73 20 74 68 65 20 74 also knows the t
45c0: 68 72 65 61 64 0a 69 74 20 77 61 73 20 63 72 65 hread.it was cre
45d0: 61 74 65 64 20 69 6e 2c 20 61 6e 64 20 65 78 65 ated in, and exe
45e0: 63 75 74 65 73 20 69 74 73 20 68 61 6e 64 6c 65 cutes its handle
45f0: 72 20 63 6f 6d 6d 61 6e 64 20 6f 6e 6c 79 20 69 r command only i
4600: 6e 20 74 68 61 74 0a 74 68 72 65 61 64 2c 20 65 n that.thread, e
4610: 76 65 6e 20 69 66 20 74 68 65 20 63 68 61 6e 6e ven if the chann
4620: 65 6c 20 77 61 73 20 6d 6f 76 65 64 20 69 6e 74 el was moved int
4630: 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 o a different th
4640: 72 65 61 64 2e 20 54 6f 20 74 68 69 73 0a 65 6e read. To this.en
4650: 64 20 61 6c 6c 20 69 6e 76 6f 63 61 74 69 6f 6e d all invocation
4660: 73 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 72 s of the handler
4670: 20 61 72 65 20 66 6f 72 77 61 72 64 65 64 20 74 are forwarded t
4680: 6f 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 74 o the original.t
4690: 68 72 65 61 64 20 62 79 20 70 6f 73 74 69 6e 67 hread by posting
46a0: 20 73 70 65 63 69 61 6c 20 65 76 65 6e 74 73 20 special events
46b0: 74 6f 20 69 74 2e 20 54 68 69 73 20 6d 65 61 6e to it. This mean
46c0: 73 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 s that the origi
46d0: 6e 61 6c 0a 74 68 72 65 61 64 20 28 69 2e 65 2e nal.thread (i.e.
46e0: 20 74 68 65 20 74 68 72 65 61 64 20 74 68 61 74 the thread that
46f0: 20 65 78 65 63 75 74 65 64 20 74 68 65 20 5c 66 executed the \f
4700: 42 63 68 61 6e 20 63 72 65 61 74 65 5c 66 52 20 Bchan create\fR
4710: 63 6f 6d 6d 61 6e 64 29 0a 6d 75 73 74 20 68 61 command).must ha
4720: 76 65 20 61 6e 20 61 63 74 69 76 65 20 65 76 65 ve an active eve
4730: 6e 74 20 6c 6f 6f 70 2c 20 69 2e 65 2e 20 69 74 nt loop, i.e. it
4740: 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f must be able to
4750: 20 70 72 6f 63 65 73 73 20 73 75 63 68 0a 65 76 process such.ev
4760: 65 6e 74 73 2e 20 4f 74 68 65 72 77 69 73 65 20 ents. Otherwise
4770: 74 68 65 20 74 68 72 65 61 64 20 73 65 6e 64 69 the thread sendi
4780: 6e 67 20 74 68 65 6d 20 77 69 6c 6c 20 5c 66 49 ng them will \fI
4790: 62 6c 6f 63 6b 0a 69 6e 64 65 66 69 6e 69 74 65 block.indefinite
47a0: 6c 79 5c 66 52 2e 20 44 65 61 64 6c 6f 63 6b 20 ly\fR. Deadlock
47b0: 6d 61 79 20 6f 63 63 75 72 2e 0a 2e 50 50 0a 4e may occur...PP.N
47c0: 6f 74 65 20 74 68 61 74 20 74 68 69 73 20 70 65 ote that this pe
47d0: 72 6d 69 74 73 20 74 68 65 20 63 72 65 61 74 69 rmits the creati
47e0: 6f 6e 20 6f 66 20 61 20 63 68 61 6e 6e 65 6c 20 on of a channel
47f0: 77 68 6f 73 65 20 74 77 6f 20 65 6e 64 70 6f 69 whose two endpoi
4800: 6e 74 73 0a 6c 69 76 65 20 69 6e 20 74 77 6f 20 nts.live in two
4810: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
4820: 73 2c 20 70 72 6f 76 69 64 69 6e 67 20 61 20 73 s, providing a s
4830: 74 72 65 61 6d 2d 6f 72 69 65 6e 74 65 64 20 62 tream-oriented b
4840: 72 69 64 67 65 0a 62 65 74 77 65 65 6e 20 74 68 ridge.between th
4850: 65 73 65 20 74 68 72 65 61 64 73 2e 20 49 6e 20 ese threads. In
4860: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 77 65 20 other words, we
4870: 63 61 6e 20 70 72 6f 76 69 64 65 20 61 20 77 61 can provide a wa
4880: 79 20 66 6f 72 0a 72 65 67 75 6c 61 72 20 73 74 y for.regular st
4890: 72 65 61 6d 20 63 6f 6d 6d 75 6e 69 63 61 74 69 ream communicati
48a0: 6f 6e 20 62 65 74 77 65 65 6e 20 74 68 72 65 61 on between threa
48b0: 64 73 20 69 6e 73 74 65 61 64 20 6f 66 20 68 61 ds instead of ha
48c0: 76 69 6e 67 20 74 6f 20 73 65 6e 64 0a 63 6f 6d ving to send.com
48d0: 6d 61 6e 64 73 2e 0a 2e 50 50 0a 57 68 65 6e 20 mands...PP.When
48e0: 61 20 74 68 72 65 61 64 20 6f 72 20 69 6e 74 65 a thread or inte
48f0: 72 70 72 65 74 65 72 20 69 73 20 64 65 6c 65 74 rpreter is delet
4900: 65 64 2c 20 61 6c 6c 20 63 68 61 6e 6e 65 6c 73 ed, all channels
4910: 20 63 72 65 61 74 65 64 20 77 69 74 68 0a 74 68 created with.th
4920: 69 73 20 73 75 62 63 6f 6d 6d 61 6e 64 20 61 6e is subcommand an
4930: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 68 72 d using this thr
4940: 65 61 64 2f 69 6e 74 65 72 70 72 65 74 65 72 20 ead/interpreter
4950: 61 73 20 74 68 65 69 72 20 63 6f 6d 70 75 74 69 as their computi
4960: 6e 67 0a 62 61 73 65 20 61 72 65 20 64 65 6c 65 ng.base are dele
4970: 74 65 64 20 61 73 20 77 65 6c 6c 2c 20 69 6e 20 ted as well, in
4980: 61 6c 6c 20 69 6e 74 65 72 70 72 65 74 65 72 73 all interpreters
4990: 20 74 68 65 79 20 68 61 76 65 20 62 65 65 6e 20 they have been
49a0: 73 68 61 72 65 64 0a 77 69 74 68 20 6f 72 20 6d shared.with or m
49b0: 6f 76 65 64 20 69 6e 74 6f 2c 20 61 6e 64 20 69 oved into, and i
49c0: 6e 20 77 68 61 74 65 76 65 72 20 74 68 72 65 61 n whatever threa
49d0: 64 20 74 68 65 79 20 68 61 76 65 20 62 65 65 6e d they have been
49e0: 20 74 72 61 6e 73 66 65 72 72 65 64 0a 74 6f 2e transferred.to.
49f0: 20 57 68 69 6c 65 20 74 68 69 73 20 70 75 6c 6c While this pull
4a00: 73 20 74 68 65 20 72 75 67 20 6f 75 74 20 75 6e s the rug out un
4a10: 64 65 72 20 74 68 65 20 6f 74 68 65 72 20 74 68 der the other th
4a20: 72 65 61 64 28 73 29 20 61 6e 64 2f 6f 72 0a 69 read(s) and/or.i
4a30: 6e 74 65 72 70 72 65 74 65 72 28 73 29 2c 20 74 nterpreter(s), t
4a40: 68 69 73 20 63 61 6e 6e 6f 74 20 62 65 20 61 76 his cannot be av
4a50: 6f 69 64 65 64 2e 20 54 72 79 69 6e 67 20 74 6f oided. Trying to
4a60: 20 75 73 65 20 73 75 63 68 20 61 20 63 68 61 6e use such a chan
4a70: 6e 65 6c 0a 77 69 6c 6c 20 63 61 75 73 65 20 74 nel.will cause t
4a80: 68 65 20 67 65 6e 65 72 61 74 69 6f 6e 20 6f 66 he generation of
4a90: 20 61 20 72 65 67 75 6c 61 72 20 65 72 72 6f 72 a regular error
4aa0: 20 61 62 6f 75 74 20 75 6e 6b 6e 6f 77 6e 20 63 about unknown c
4ab0: 68 61 6e 6e 65 6c 0a 68 61 6e 64 6c 65 73 2e 0a hannel.handles..
4ac0: 2e 50 50 0a 54 68 69 73 20 73 75 62 63 6f 6d 6d .PP.This subcomm
4ad0: 61 6e 64 20 69 73 20 5c 66 42 73 61 66 65 5c 66 and is \fBsafe\f
4ae0: 52 20 61 6e 64 20 6d 61 64 65 20 61 63 63 65 73 R and made acces
4af0: 73 69 62 6c 65 20 74 6f 20 73 61 66 65 0a 69 6e sible to safe.in
4b00: 74 65 72 70 72 65 74 65 72 73 2e 20 20 57 68 69 terpreters. Whi
4b10: 6c 65 20 69 74 20 61 72 72 61 6e 67 65 73 20 66 le it arranges f
4b20: 6f 72 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e or the execution
4b30: 20 6f 66 20 61 72 62 69 74 72 61 72 79 20 54 63 of arbitrary Tc
4b40: 6c 0a 63 6f 64 65 20 74 68 65 20 73 79 73 74 65 l.code the syste
4b50: 6d 20 61 6c 73 6f 20 6d 61 6b 65 73 20 73 75 72 m also makes sur
4b60: 65 20 74 68 61 74 20 74 68 65 20 63 6f 64 65 20 e that the code
4b70: 69 73 20 61 6c 77 61 79 73 20 65 78 65 63 75 74 is always execut
4b80: 65 64 0a 77 69 74 68 69 6e 20 74 68 65 20 73 61 ed.within the sa
4b90: 66 65 20 69 6e 74 65 72 70 72 65 74 65 72 2e 0a fe interpreter..
4ba0: 2e 52 45 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a 20 .RE..\" METHOD:
4bb0: 65 6f 66 0a 2e 54 50 0a 5c 66 42 63 68 61 6e 20 eof..TP.\fBchan
4bc0: 65 6f 66 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 eof \fIchannel\f
4bd0: 52 0a 2e 0a 54 65 73 74 20 77 68 65 74 68 65 72 R...Test whether
4be0: 20 74 68 65 20 6c 61 73 74 20 69 6e 70 75 74 20 the last input
4bf0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 20 74 68 65 operation on the
4c00: 20 63 68 61 6e 6e 65 6c 20 63 61 6c 6c 65 64 0a channel called.
4c10: 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 20 66 61 \fIchannel\fR fa
4c20: 69 6c 65 64 20 62 65 63 61 75 73 65 20 74 68 65 iled because the
4c30: 20 65 6e 64 20 6f 66 20 74 68 65 20 64 61 74 61 end of the data
4c40: 20 73 74 72 65 61 6d 20 77 61 73 20 72 65 61 63 stream was reac
4c50: 68 65 64 2c 0a 72 65 74 75 72 6e 69 6e 67 20 31 hed,.returning 1
4c60: 20 69 66 20 65 6e 64 2d 6f 66 2d 66 69 6c 65 20 if end-of-file
4c70: 77 61 73 20 72 65 61 63 68 65 64 2c 20 61 6e 64 was reached, and
4c80: 20 30 20 6f 74 68 65 72 77 69 73 65 2e 0a 2e 5c 0 otherwise...\
4c90: 22 20 4d 45 54 48 4f 44 3a 20 65 76 65 6e 74 0a " METHOD: event.
4ca0: 2e 54 50 0a 5c 66 42 63 68 61 6e 20 65 76 65 6e .TP.\fBchan even
4cb0: 74 20 5c 66 49 63 68 61 6e 6e 65 6c 20 65 76 65 t \fIchannel eve
4cc0: 6e 74 5c 66 52 20 3f 5c 66 49 73 63 72 69 70 74 nt\fR ?\fIscript
4cd0: 5c 66 52 3f 0a 2e 0a 41 72 72 61 6e 67 65 20 66 \fR?...Arrange f
4ce0: 6f 72 20 74 68 65 20 54 63 6c 20 73 63 72 69 70 or the Tcl scrip
4cf0: 74 20 5c 66 49 73 63 72 69 70 74 5c 66 52 20 74 t \fIscript\fR t
4d00: 6f 20 62 65 20 69 6e 73 74 61 6c 6c 65 64 20 61 o be installed a
4d10: 73 20 61 20 5c 66 49 66 69 6c 65 0a 65 76 65 6e s a \fIfile.even
4d20: 74 20 68 61 6e 64 6c 65 72 5c 66 52 20 74 6f 20 t handler\fR to
4d30: 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 be called whenev
4d40: 65 72 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 63 er the channel c
4d50: 61 6c 6c 65 64 0a 5c 66 49 63 68 61 6e 6e 65 6c alled.\fIchannel
4d60: 5c 66 52 20 65 6e 74 65 72 73 20 74 68 65 20 73 \fR enters the s
4d70: 74 61 74 65 20 64 65 73 63 72 69 62 65 64 20 62 tate described b
4d80: 79 20 5c 66 49 65 76 65 6e 74 5c 66 52 20 28 77 y \fIevent\fR (w
4d90: 68 69 63 68 20 6d 75 73 74 0a 62 65 20 65 69 74 hich must.be eit
4da0: 68 65 72 20 5c 66 42 72 65 61 64 61 62 6c 65 5c her \fBreadable\
4db0: 66 52 20 6f 72 20 5c 66 42 77 72 69 74 61 62 6c fR or \fBwritabl
4dc0: 65 5c 66 52 29 3b 20 6f 6e 6c 79 20 6f 6e 65 20 e\fR); only one
4dd0: 73 75 63 68 20 68 61 6e 64 6c 65 72 20 6d 61 79 such handler may
4de0: 0a 62 65 20 69 6e 73 74 61 6c 6c 65 64 20 70 65 .be installed pe
4df0: 72 20 65 76 65 6e 74 20 70 65 72 20 63 68 61 6e r event per chan
4e00: 6e 65 6c 20 61 74 20 61 20 74 69 6d 65 2e 20 20 nel at a time.
4e10: 49 66 20 5c 66 49 73 63 72 69 70 74 5c 66 52 20 If \fIscript\fR
4e20: 69 73 20 74 68 65 0a 65 6d 70 74 79 20 73 74 72 is the.empty str
4e30: 69 6e 67 2c 20 74 68 65 20 63 75 72 72 65 6e 74 ing, the current
4e40: 20 68 61 6e 64 6c 65 72 20 69 73 20 64 65 6c 65 handler is dele
4e50: 74 65 64 20 28 74 68 69 73 20 61 6c 73 6f 20 68 ted (this also h
4e60: 61 70 70 65 6e 73 20 69 66 20 74 68 65 0a 63 68 appens if the.ch
4e70: 61 6e 6e 65 6c 20 69 73 20 63 6c 6f 73 65 64 20 annel is closed
4e80: 6f 72 20 74 68 65 20 69 6e 74 65 72 70 72 65 74 or the interpret
4e90: 65 72 20 64 65 6c 65 74 65 64 29 2e 20 20 49 66 er deleted). If
4ea0: 20 5c 66 49 73 63 72 69 70 74 5c 66 52 20 69 73 \fIscript\fR is
4eb0: 0a 6f 6d 69 74 74 65 64 2c 20 74 68 65 20 63 75 .omitted, the cu
4ec0: 72 72 65 6e 74 6c 79 20 69 6e 73 74 61 6c 6c 65 rrently installe
4ed0: 64 20 73 63 72 69 70 74 20 69 73 20 72 65 74 75 d script is retu
4ee0: 72 6e 65 64 20 28 6f 72 20 61 6e 20 65 6d 70 74 rned (or an empt
4ef0: 79 0a 73 74 72 69 6e 67 20 69 66 20 6e 6f 20 73 y.string if no s
4f00: 75 63 68 20 68 61 6e 64 6c 65 72 20 69 73 20 69 uch handler is i
4f10: 6e 73 74 61 6c 6c 65 64 29 2e 20 20 54 68 65 20 nstalled). The
4f20: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6f 6e 6c 79 callback is only
4f30: 0a 70 65 72 66 6f 72 6d 65 64 20 69 66 20 74 68 .performed if th
4f40: 65 20 65 76 65 6e 74 20 6c 6f 6f 70 20 69 73 20 e event loop is
4f50: 62 65 69 6e 67 20 73 65 72 76 69 63 65 64 20 28 being serviced (
4f60: 65 2e 67 2e 20 76 69 61 20 5c 66 42 76 77 61 69 e.g. via \fBvwai
4f70: 74 5c 66 52 20 6f 72 0a 5c 66 42 75 70 64 61 74 t\fR or.\fBupdat
4f80: 65 5c 66 52 29 2e 0a 2e 52 53 0a 2e 50 50 0a 41 e\fR)...RS..PP.A
4f90: 20 66 69 6c 65 20 65 76 65 6e 74 20 68 61 6e 64 file event hand
4fa0: 6c 65 72 20 69 73 20 61 20 62 69 6e 64 69 6e 67 ler is a binding
4fb0: 20 62 65 74 77 65 65 6e 20 61 20 63 68 61 6e 6e between a chann
4fc0: 65 6c 20 61 6e 64 20 61 20 73 63 72 69 70 74 2c el and a script,
4fd0: 20 73 75 63 68 0a 74 68 61 74 20 74 68 65 20 73 such.that the s
4fe0: 63 72 69 70 74 20 69 73 20 65 76 61 6c 75 61 74 cript is evaluat
4ff0: 65 64 20 77 68 65 6e 65 76 65 72 20 74 68 65 20 ed whenever the
5000: 63 68 61 6e 6e 65 6c 20 62 65 63 6f 6d 65 73 20 channel becomes
5010: 72 65 61 64 61 62 6c 65 20 6f 72 0a 77 72 69 74 readable or.writ
5020: 61 62 6c 65 2e 20 20 46 69 6c 65 20 65 76 65 6e able. File even
5030: 74 20 68 61 6e 64 6c 65 72 73 20 61 72 65 20 6d t handlers are m
5040: 6f 73 74 20 63 6f 6d 6d 6f 6e 6c 79 20 75 73 65 ost commonly use
5050: 64 20 74 6f 20 61 6c 6c 6f 77 20 64 61 74 61 20 d to allow data
5060: 74 6f 0a 62 65 20 72 65 63 65 69 76 65 64 20 66 to.be received f
5070: 72 6f 6d 20 61 6e 6f 74 68 65 72 20 70 72 6f 63 rom another proc
5080: 65 73 73 20 6f 6e 20 61 6e 20 65 76 65 6e 74 2d ess on an event-
5090: 64 72 69 76 65 6e 20 62 61 73 69 73 2c 20 73 6f driven basis, so
50a0: 20 74 68 61 74 20 74 68 65 0a 72 65 63 65 69 76 that the.receiv
50b0: 65 72 20 63 61 6e 20 63 6f 6e 74 69 6e 75 65 20 er can continue
50c0: 74 6f 20 69 6e 74 65 72 61 63 74 20 77 69 74 68 to interact with
50d0: 20 74 68 65 20 75 73 65 72 20 6f 72 20 77 69 74 the user or wit
50e0: 68 20 6f 74 68 65 72 20 63 68 61 6e 6e 65 6c 73 h other channels
50f0: 0a 77 68 69 6c 65 20 77 61 69 74 69 6e 67 20 66 .while waiting f
5100: 6f 72 20 74 68 65 20 64 61 74 61 20 74 6f 20 61 or the data to a
5110: 72 72 69 76 65 2e 20 20 49 66 20 61 6e 20 61 70 rrive. If an ap
5120: 70 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 plication invoke
5130: 73 0a 5c 66 42 63 68 61 6e 20 67 65 74 73 5c 66 s.\fBchan gets\f
5140: 52 20 6f 72 20 5c 66 42 63 68 61 6e 20 72 65 61 R or \fBchan rea
5150: 64 5c 66 52 20 6f 6e 20 61 20 62 6c 6f 63 6b 69 d\fR on a blocki
5160: 6e 67 20 63 68 61 6e 6e 65 6c 20 77 68 65 6e 20 ng channel when
5170: 74 68 65 72 65 20 69 73 0a 6e 6f 20 69 6e 70 75 there is.no inpu
5180: 74 20 64 61 74 61 20 61 76 61 69 6c 61 62 6c 65 t data available
5190: 2c 20 74 68 65 20 70 72 6f 63 65 73 73 20 77 69 , the process wi
51a0: 6c 6c 20 62 6c 6f 63 6b 3b 20 75 6e 74 69 6c 20 ll block; until
51b0: 74 68 65 20 69 6e 70 75 74 20 64 61 74 61 0a 61 the input data.a
51c0: 72 72 69 76 65 73 2c 20 69 74 20 77 69 6c 6c 20 rrives, it will
51d0: 6e 6f 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 not be able to s
51e0: 65 72 76 69 63 65 20 6f 74 68 65 72 20 65 76 65 ervice other eve
51f0: 6e 74 73 2c 20 73 6f 20 69 74 20 77 69 6c 6c 0a nts, so it will.
5200: 61 70 70 65 61 72 20 74 6f 20 74 68 65 20 75 73 appear to the us
5210: 65 72 20 74 6f 0a 2e 51 57 20 22 66 72 65 65 7a er to..QW "freez
5220: 65 20 75 70 22 0a 5c 26 2e 0a 57 69 74 68 20 5c e up".\&..With \
5230: 66 42 63 68 61 6e 20 65 76 65 6e 74 5c 66 52 2c fBchan event\fR,
5240: 20 74 68 65 0a 70 72 6f 63 65 73 73 20 63 61 6e the.process can
5250: 20 74 65 6c 6c 20 77 68 65 6e 20 64 61 74 61 20 tell when data
5260: 69 73 20 70 72 65 73 65 6e 74 20 61 6e 64 20 6f is present and o
5270: 6e 6c 79 20 69 6e 76 6f 6b 65 20 5c 66 42 63 68 nly invoke \fBch
5280: 61 6e 20 67 65 74 73 5c 66 52 0a 6f 72 20 5c 66 an gets\fR.or \f
5290: 42 63 68 61 6e 20 72 65 61 64 5c 66 52 20 77 68 Bchan read\fR wh
52a0: 65 6e 20 74 68 65 79 20 77 69 6c 6c 20 6e 6f 74 en they will not
52b0: 20 62 6c 6f 63 6b 2e 0a 2e 50 50 0a 41 20 63 68 block...PP.A ch
52c0: 61 6e 6e 65 6c 20 69 73 20 63 6f 6e 73 69 64 65 annel is conside
52d0: 72 65 64 20 74 6f 20 62 65 20 72 65 61 64 61 62 red to be readab
52e0: 6c 65 20 69 66 20 74 68 65 72 65 20 69 73 20 75 le if there is u
52f0: 6e 72 65 61 64 20 64 61 74 61 0a 61 76 61 69 6c nread data.avail
5300: 61 62 6c 65 20 6f 6e 20 74 68 65 20 75 6e 64 65 able on the unde
5310: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 2e 20 20 rlying device.
5320: 41 20 63 68 61 6e 6e 65 6c 20 69 73 20 61 6c 73 A channel is als
5330: 6f 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a o considered to.
5340: 62 65 20 72 65 61 64 61 62 6c 65 20 69 66 20 74 be readable if t
5350: 68 65 72 65 20 69 73 20 75 6e 72 65 61 64 20 64 here is unread d
5360: 61 74 61 20 69 6e 20 61 6e 20 69 6e 70 75 74 20 ata in an input
5370: 62 75 66 66 65 72 2c 20 65 78 63 65 70 74 20 69 buffer, except i
5380: 6e 20 74 68 65 0a 73 70 65 63 69 61 6c 20 63 61 n the.special ca
5390: 73 65 20 77 68 65 72 65 20 74 68 65 20 6d 6f 73 se where the mos
53a0: 74 20 72 65 63 65 6e 74 20 61 74 74 65 6d 70 74 t recent attempt
53b0: 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 74 68 to read from th
53c0: 65 20 63 68 61 6e 6e 65 6c 0a 77 61 73 20 61 20 e channel.was a
53d0: 5c 66 42 63 68 61 6e 20 67 65 74 73 5c 66 52 20 \fBchan gets\fR
53e0: 63 61 6c 6c 20 74 68 61 74 20 63 6f 75 6c 64 20 call that could
53f0: 6e 6f 74 20 66 69 6e 64 20 61 20 63 6f 6d 70 6c not find a compl
5400: 65 74 65 20 6c 69 6e 65 20 69 6e 20 74 68 65 0a ete line in the.
5410: 69 6e 70 75 74 20 62 75 66 66 65 72 2e 20 20 54 input buffer. T
5420: 68 69 73 20 66 65 61 74 75 72 65 20 61 6c 6c 6f his feature allo
5430: 77 73 20 61 20 66 69 6c 65 20 74 6f 20 62 65 20 ws a file to be
5440: 72 65 61 64 20 61 20 6c 69 6e 65 20 61 74 20 61 read a line at a
5450: 20 74 69 6d 65 0a 69 6e 20 6e 6f 6e 2d 62 6c 6f time.in non-blo
5460: 63 6b 69 6e 67 20 6d 6f 64 65 20 75 73 69 6e 67 cking mode using
5470: 20 65 76 65 6e 74 73 2e 20 20 41 20 63 68 61 6e events. A chan
5480: 6e 65 6c 20 69 73 20 61 6c 73 6f 20 63 6f 6e 73 nel is also cons
5490: 69 64 65 72 65 64 20 74 6f 20 62 65 0a 72 65 61 idered to be.rea
54a0: 64 61 62 6c 65 20 69 66 20 61 6e 20 65 6e 64 20 dable if an end
54b0: 6f 66 20 66 69 6c 65 20 6f 72 20 65 72 72 6f 72 of file or error
54c0: 20 63 6f 6e 64 69 74 69 6f 6e 20 69 73 20 70 72 condition is pr
54d0: 65 73 65 6e 74 20 6f 6e 20 74 68 65 0a 75 6e 64 esent on the.und
54e0: 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 6f 72 20 erlying file or
54f0: 64 65 76 69 63 65 2e 20 20 49 74 20 69 73 20 69 device. It is i
5500: 6d 70 6f 72 74 61 6e 74 20 66 6f 72 20 5c 66 49 mportant for \fI
5510: 73 63 72 69 70 74 5c 66 52 20 74 6f 20 63 68 65 script\fR to che
5520: 63 6b 0a 66 6f 72 20 74 68 65 73 65 20 63 6f 6e ck.for these con
5530: 64 69 74 69 6f 6e 73 20 61 6e 64 20 68 61 6e 64 ditions and hand
5540: 6c 65 20 74 68 65 6d 20 61 70 70 72 6f 70 72 69 le them appropri
5550: 61 74 65 6c 79 3b 20 66 6f 72 20 65 78 61 6d 70 ately; for examp
5560: 6c 65 2c 20 69 66 0a 74 68 65 72 65 20 69 73 20 le, if.there is
5570: 6e 6f 20 73 70 65 63 69 61 6c 20 63 68 65 63 6b no special check
5580: 20 66 6f 72 20 65 6e 64 20 6f 66 20 66 69 6c 65 for end of file
5590: 2c 20 61 6e 20 69 6e 66 69 6e 69 74 65 20 6c 6f , an infinite lo
55a0: 6f 70 20 6d 61 79 20 6f 63 63 75 72 0a 77 68 65 op may occur.whe
55b0: 72 65 20 5c 66 49 73 63 72 69 70 74 5c 66 52 20 re \fIscript\fR
55c0: 72 65 61 64 73 20 6e 6f 20 64 61 74 61 2c 20 72 reads no data, r
55d0: 65 74 75 72 6e 73 2c 20 61 6e 64 20 69 73 20 69 eturns, and is i
55e0: 6d 6d 65 64 69 61 74 65 6c 79 20 69 6e 76 6f 6b mmediately invok
55f0: 65 64 0a 61 67 61 69 6e 2e 0a 2e 50 50 0a 41 20 ed.again...PP.A
5600: 63 68 61 6e 6e 65 6c 20 69 73 20 63 6f 6e 73 69 channel is consi
5610: 64 65 72 65 64 20 74 6f 20 62 65 20 77 72 69 74 dered to be writ
5620: 61 62 6c 65 20 69 66 20 61 74 20 6c 65 61 73 74 able if at least
5630: 20 6f 6e 65 20 62 79 74 65 20 6f 66 20 64 61 74 one byte of dat
5640: 61 0a 63 61 6e 20 62 65 20 77 72 69 74 74 65 6e a.can be written
5650: 20 74 6f 20 74 68 65 20 75 6e 64 65 72 6c 79 69 to the underlyi
5660: 6e 67 20 66 69 6c 65 20 6f 72 20 64 65 76 69 63 ng file or devic
5670: 65 20 77 69 74 68 6f 75 74 20 62 6c 6f 63 6b 69 e without blocki
5680: 6e 67 2c 20 6f 72 0a 69 66 20 61 6e 20 65 72 72 ng, or.if an err
5690: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 20 69 73 20 or condition is
56a0: 70 72 65 73 65 6e 74 20 6f 6e 20 74 68 65 20 75 present on the u
56b0: 6e 64 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 6f nderlying file o
56c0: 72 20 64 65 76 69 63 65 2e 0a 4e 6f 74 65 20 74 r device..Note t
56d0: 68 61 74 20 63 6c 69 65 6e 74 20 73 6f 63 6b 65 hat client socke
56e0: 74 73 20 6f 70 65 6e 65 64 20 69 6e 20 61 73 79 ts opened in asy
56f0: 6e 63 68 72 6f 6e 6f 75 73 20 6d 6f 64 65 20 62 nchronous mode b
5700: 65 63 6f 6d 65 20 77 72 69 74 61 62 6c 65 0a 77 ecome writable.w
5710: 68 65 6e 20 74 68 65 79 20 62 65 63 6f 6d 65 20 hen they become
5720: 63 6f 6e 6e 65 63 74 65 64 20 6f 72 20 69 66 20 connected or if
5730: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 66 the connection f
5740: 61 69 6c 73 2e 0a 2e 50 50 0a 45 76 65 6e 74 2d ails...PP.Event-
5750: 64 72 69 76 65 6e 20 49 2f 4f 20 77 6f 72 6b 73 driven I/O works
5760: 20 62 65 73 74 20 66 6f 72 20 63 68 61 6e 6e 65 best for channe
5770: 6c 73 20 74 68 61 74 20 68 61 76 65 20 62 65 65 ls that have bee
5780: 6e 20 70 6c 61 63 65 64 20 69 6e 74 6f 0a 6e 6f n placed into.no
5790: 6e 2d 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 20 n-blocking mode
57a0: 77 69 74 68 20 74 68 65 20 5c 66 42 63 68 61 6e with the \fBchan
57b0: 20 63 6f 6e 66 69 67 75 72 65 5c 66 52 20 63 6f configure\fR co
57c0: 6d 6d 61 6e 64 2e 20 20 49 6e 20 62 6c 6f 63 6b mmand. In block
57d0: 69 6e 67 0a 6d 6f 64 65 2c 20 61 20 5c 66 42 63 ing.mode, a \fBc
57e0: 68 61 6e 20 70 75 74 73 5c 66 52 20 63 6f 6d 6d han puts\fR comm
57f0: 61 6e 64 20 6d 61 79 20 62 6c 6f 63 6b 20 69 66 and may block if
5800: 20 79 6f 75 20 67 69 76 65 20 69 74 20 6d 6f 72 you give it mor
5810: 65 20 64 61 74 61 0a 74 68 61 6e 20 74 68 65 20 e data.than the
5820: 75 6e 64 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 underlying file
5830: 6f 72 20 64 65 76 69 63 65 20 63 61 6e 20 61 63 or device can ac
5840: 63 65 70 74 2c 20 61 6e 64 20 61 20 5c 66 42 63 cept, and a \fBc
5850: 68 61 6e 20 67 65 74 73 5c 66 52 0a 6f 72 20 5c han gets\fR.or \
5860: 66 42 63 68 61 6e 20 72 65 61 64 5c 66 52 20 63 fBchan read\fR c
5870: 6f 6d 6d 61 6e 64 20 77 69 6c 6c 20 62 6c 6f 63 ommand will bloc
5880: 6b 20 69 66 20 79 6f 75 20 61 74 74 65 6d 70 74 k if you attempt
5890: 20 74 6f 20 72 65 61 64 20 6d 6f 72 65 20 64 61 to read more da
58a0: 74 61 0a 74 68 61 6e 20 69 73 20 72 65 61 64 79 ta.than is ready
58b0: 3b 20 6e 6f 20 65 76 65 6e 74 73 20 77 69 6c 6c ; no events will
58c0: 20 62 65 20 70 72 6f 63 65 73 73 65 64 20 77 68 be processed wh
58d0: 69 6c 65 20 74 68 65 20 63 6f 6d 6d 61 6e 64 73 ile the commands
58e0: 20 62 6c 6f 63 6b 2e 0a 49 6e 20 6e 6f 6e 2d 62 block..In non-b
58f0: 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 20 5c 66 42 locking mode \fB
5900: 63 68 61 6e 20 70 75 74 73 5c 66 52 2c 20 5c 66 chan puts\fR, \f
5910: 42 63 68 61 6e 20 72 65 61 64 5c 66 52 2c 20 61 Bchan read\fR, a
5920: 6e 64 20 5c 66 42 63 68 61 6e 0a 67 65 74 73 5c nd \fBchan.gets\
5930: 66 52 20 6e 65 76 65 72 20 62 6c 6f 63 6b 2e 0a fR never block..
5940: 2e 50 50 0a 54 68 65 20 73 63 72 69 70 74 20 66 .PP.The script f
5950: 6f 72 20 61 20 66 69 6c 65 20 65 76 65 6e 74 20 or a file event
5960: 69 73 20 65 78 65 63 75 74 65 64 20 61 74 20 67 is executed at g
5970: 6c 6f 62 61 6c 20 6c 65 76 65 6c 20 28 6f 75 74 lobal level (out
5980: 73 69 64 65 20 74 68 65 0a 63 6f 6e 74 65 78 74 side the.context
5990: 20 6f 66 20 61 6e 79 20 54 63 6c 20 70 72 6f 63 of any Tcl proc
59a0: 65 64 75 72 65 29 20 69 6e 20 74 68 65 20 69 6e edure) in the in
59b0: 74 65 72 70 72 65 74 65 72 20 69 6e 20 77 68 69 terpreter in whi
59c0: 63 68 20 74 68 65 20 5c 66 42 63 68 61 6e 0a 65 ch the \fBchan.e
59d0: 76 65 6e 74 5c 66 52 20 63 6f 6d 6d 61 6e 64 20 vent\fR command
59e0: 77 61 73 20 69 6e 76 6f 6b 65 64 2e 20 20 49 66 was invoked. If
59f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
5a00: 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e 67 while executing
5a10: 20 74 68 65 0a 73 63 72 69 70 74 20 74 68 65 6e the.script then
5a20: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 65 67 the command reg
5a30: 69 73 74 65 72 65 64 20 77 69 74 68 20 5c 66 42 istered with \fB
5a40: 69 6e 74 65 72 70 20 62 67 65 72 72 6f 72 5c 66 interp bgerror\f
5a50: 52 20 69 73 20 75 73 65 64 0a 74 6f 20 72 65 70 R is used.to rep
5a60: 6f 72 74 20 74 68 65 20 65 72 72 6f 72 2e 20 20 ort the error.
5a70: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 In addition, the
5a80: 20 66 69 6c 65 20 65 76 65 6e 74 20 68 61 6e 64 file event hand
5a90: 6c 65 72 20 69 73 20 64 65 6c 65 74 65 64 0a 69 ler is deleted.i
5aa0: 66 20 69 74 20 65 76 65 72 20 72 65 74 75 72 6e f it ever return
5ab0: 73 20 61 6e 20 65 72 72 6f 72 3b 20 74 68 69 73 s an error; this
5ac0: 20 69 73 20 64 6f 6e 65 20 69 6e 20 6f 72 64 65 is done in orde
5ad0: 72 20 74 6f 20 70 72 65 76 65 6e 74 20 69 6e 66 r to prevent inf
5ae0: 69 6e 69 74 65 0a 6c 6f 6f 70 73 20 64 75 65 20 inite.loops due
5af0: 74 6f 20 62 75 67 67 79 20 68 61 6e 64 6c 65 72 to buggy handler
5b00: 73 2e 0a 2e 52 45 0a 2e 5c 22 20 4d 45 54 48 4f s...RE..\" METHO
5b10: 44 3a 20 66 6c 75 73 68 0a 2e 54 50 0a 5c 66 42 D: flush..TP.\fB
5b20: 63 68 61 6e 20 66 6c 75 73 68 20 5c 66 49 63 68 chan flush \fIch
5b30: 61 6e 6e 65 6c 5c 66 52 0a 2e 0a 45 6e 73 75 72 annel\fR...Ensur
5b40: 65 73 20 74 68 61 74 20 61 6c 6c 20 70 65 6e 64 es that all pend
5b50: 69 6e 67 20 6f 75 74 70 75 74 20 66 6f 72 20 74 ing output for t
5b60: 68 65 20 63 68 61 6e 6e 65 6c 20 63 61 6c 6c 65 he channel calle
5b70: 64 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 0a d \fIchannel\fR.
5b80: 69 73 20 77 72 69 74 74 65 6e 2e 0a 2e 52 53 0a is written...RS.
5b90: 2e 50 50 0a 49 66 20 74 68 65 20 63 68 61 6e 6e .PP.If the chann
5ba0: 65 6c 20 69 73 20 69 6e 20 62 6c 6f 63 6b 69 6e el is in blockin
5bb0: 67 20 6d 6f 64 65 20 74 68 65 20 63 6f 6d 6d 61 g mode the comma
5bc0: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 nd does not retu
5bd0: 72 6e 20 75 6e 74 69 6c 0a 61 6c 6c 20 74 68 65 rn until.all the
5be0: 20 62 75 66 66 65 72 65 64 20 6f 75 74 70 75 74 buffered output
5bf0: 20 68 61 73 20 62 65 65 6e 20 66 6c 75 73 68 65 has been flushe
5c00: 64 20 74 6f 20 74 68 65 20 63 68 61 6e 6e 65 6c d to the channel
5c10: 2e 20 49 66 20 74 68 65 0a 63 68 61 6e 6e 65 6c . If the.channel
5c20: 20 69 73 20 69 6e 20 6e 6f 6e 2d 62 6c 6f 63 6b is in non-block
5c30: 69 6e 67 20 6d 6f 64 65 2c 20 74 68 65 20 63 6f ing mode, the co
5c40: 6d 6d 61 6e 64 20 6d 61 79 20 72 65 74 75 72 6e mmand may return
5c50: 20 62 65 66 6f 72 65 20 61 6c 6c 0a 62 75 66 66 before all.buff
5c60: 65 72 65 64 20 6f 75 74 70 75 74 20 68 61 73 20 ered output has
5c70: 62 65 65 6e 20 66 6c 75 73 68 65 64 3b 20 74 68 been flushed; th
5c80: 65 20 72 65 6d 61 69 6e 64 65 72 20 77 69 6c 6c e remainder will
5c90: 20 62 65 20 66 6c 75 73 68 65 64 20 69 6e 20 74 be flushed in t
5ca0: 68 65 0a 62 61 63 6b 67 72 6f 75 6e 64 20 61 73 he.background as
5cb0: 20 66 61 73 74 20 61 73 20 74 68 65 20 75 6e 64 fast as the und
5cc0: 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 6f 72 20 erlying file or
5cd0: 64 65 76 69 63 65 20 69 73 20 61 62 6c 65 20 74 device is able t
5ce0: 6f 20 61 62 73 6f 72 62 0a 69 74 2e 0a 2e 52 45 o absorb.it...RE
5cf0: 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a 20 67 65 74 ..\" METHOD: get
5d00: 73 0a 2e 54 50 0a 5c 66 42 63 68 61 6e 20 67 65 s..TP.\fBchan ge
5d10: 74 73 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 ts \fIchannel\fR
5d20: 20 3f 5c 66 49 76 61 72 4e 61 6d 65 5c 66 52 3f ?\fIvarName\fR?
5d30: 0a 2e 0a 52 65 61 64 73 20 61 20 6c 69 6e 65 20 ...Reads a line
5d40: 66 72 6f 6d 20 74 68 65 20 63 68 61 6e 6e 65 6c from the channel
5d50: 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 61 consisting of a
5d60: 6c 6c 20 63 68 61 72 61 63 74 65 72 73 20 75 70 ll characters up
5d70: 20 74 6f 20 74 68 65 20 6e 65 78 74 0a 65 6e 64 to the next.end
5d80: 2d 6f 66 2d 6c 69 6e 65 20 73 65 71 75 65 6e 63 -of-line sequenc
5d90: 65 20 6f 72 20 75 6e 74 69 6c 20 65 6e 64 20 6f e or until end o
5da0: 66 20 66 69 6c 65 20 69 73 20 73 65 65 6e 2e 20 f file is seen.
5db0: 54 68 65 20 6c 69 6e 65 20 66 65 65 64 20 63 68 The line feed ch
5dc0: 61 72 61 63 74 65 72 0a 63 6f 72 72 65 73 70 6f aracter.correspo
5dd0: 6e 64 69 6e 67 20 74 6f 20 65 6e 64 2d 6f 66 2d nding to end-of-
5de0: 6c 69 6e 65 20 73 65 71 75 65 6e 63 65 20 69 73 line sequence is
5df0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 61 73 not included as
5e00: 20 70 61 72 74 20 6f 66 20 74 68 65 20 6c 69 6e part of the lin
5e10: 65 2e 0a 49 66 20 74 68 65 20 5c 66 49 76 61 72 e..If the \fIvar
5e20: 4e 61 6d 65 5c 66 52 20 61 72 67 75 6d 65 6e 74 Name\fR argument
5e30: 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
5e40: 68 65 20 6c 69 6e 65 20 69 73 20 73 74 6f 72 65 he line is store
5e50: 64 20 69 6e 20 74 68 65 20 76 61 72 69 61 62 6c d in the variabl
5e60: 65 0a 6f 66 20 74 68 61 74 20 6e 61 6d 65 20 61 e.of that name a
5e70: 6e 64 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 nd the command r
5e80: 65 74 75 72 6e 73 20 74 68 65 20 6c 65 6e 67 74 eturns the lengt
5e90: 68 20 6f 66 20 74 68 65 20 6c 69 6e 65 2e 20 49 h of the line. I
5ea0: 66 20 5c 66 49 76 61 72 4e 61 6d 65 5c 66 52 0a f \fIvarName\fR.
5eb0: 69 73 20 6e 6f 74 20 73 70 65 63 69 66 69 65 64 is not specified
5ec0: 2c 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 65 , the command re
5ed0: 74 75 72 6e 73 20 74 68 65 20 6c 69 6e 65 20 69 turns the line i
5ee0: 74 73 65 6c 66 20 61 73 20 74 68 65 20 72 65 73 tself as the res
5ef0: 75 6c 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 61 ult of the comma
5f00: 6e 64 2e 0a 2e 52 53 0a 2e 50 50 0a 49 66 20 61 nd...RS..PP.If a
5f10: 20 63 6f 6d 70 6c 65 74 65 20 6c 69 6e 65 20 69 complete line i
5f20: 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
5f30: 61 6e 64 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 and the channel
5f40: 69 73 20 6e 6f 74 20 61 74 20 45 4f 46 2c 20 74 is not at EOF, t
5f50: 68 65 20 63 6f 6d 6d 61 6e 64 0a 77 69 6c 6c 20 he command.will
5f60: 62 6c 6f 63 6b 20 69 6e 20 74 68 65 20 63 61 73 block in the cas
5f70: 65 20 6f 66 20 61 20 62 6c 6f 63 6b 69 6e 67 20 e of a blocking
5f80: 63 68 61 6e 6e 65 6c 2e 20 46 6f 72 20 6e 6f 6e channel. For non
5f90: 2d 62 6c 6f 63 6b 69 6e 67 20 63 68 61 6e 6e 65 -blocking channe
5fa0: 6c 73 2c 20 74 68 65 0a 63 6f 6d 6d 61 6e 64 20 ls, the.command
5fb0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
5fc0: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 61 73 20 empty string as
5fd0: 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 74 68 the result in th
5fe0: 65 20 63 61 73 65 20 6f 66 20 5c 66 49 76 61 72 e case of \fIvar
5ff0: 4e 61 6d 65 5c 66 52 0a 6e 6f 74 20 73 70 65 63 Name\fR.not spec
6000: 69 66 69 65 64 20 61 6e 64 20 2d 31 20 69 66 20 ified and -1 if
6010: 69 74 20 69 73 2e 0a 2e 52 45 0a 2e 52 53 0a 2e it is...RE..RS..
6020: 50 50 0a 49 66 20 61 20 62 6c 6f 63 6b 69 6e 67 PP.If a blocking
6030: 20 63 68 61 6e 6e 65 6c 20 69 73 20 61 6c 72 65 channel is alre
6040: 61 64 79 20 61 74 20 45 4f 46 2c 20 74 68 65 20 ady at EOF, the
6050: 63 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e 73 20 command returns
6060: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
6070: 69 66 0a 5c 66 49 76 61 72 4e 61 6d 65 5c 66 52 if.\fIvarName\fR
6080: 20 69 73 20 6e 6f 74 20 73 70 65 63 69 66 69 65 is not specifie
6090: 64 2e 20 4e 6f 74 65 20 61 6e 20 65 6d 70 74 79 d. Note an empty
60a0: 20 73 74 72 69 6e 67 20 72 65 73 75 6c 74 20 63 string result c
60b0: 61 6e 20 61 6c 73 6f 20 62 65 20 72 65 74 75 72 an also be retur
60c0: 6e 65 64 0a 77 68 65 6e 20 61 20 62 6c 61 6e 6b ned.when a blank
60d0: 20 6c 69 6e 65 20 28 6e 6f 20 63 68 61 72 61 63 line (no charac
60e0: 74 65 72 73 20 62 65 66 6f 72 65 20 74 68 65 20 ters before the
60f0: 6e 65 78 74 20 65 6e 64 20 6f 66 20 6c 69 6e 65 next end of line
6100: 20 73 65 71 75 65 6e 63 65 29 2e 20 54 68 65 20 sequence). The
6110: 74 77 6f 0a 63 61 73 65 73 20 63 61 6e 20 62 65 two.cases can be
6120: 20 64 69 73 74 69 6e 67 75 69 73 68 65 64 20 62 distinguished b
6130: 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 5c 66 y calling the \f
6140: 42 63 68 61 6e 20 65 6f 66 5c 66 52 20 63 6f 6d Bchan eof\fR com
6150: 6d 61 6e 64 20 74 6f 20 63 68 65 63 6b 20 66 6f mand to check fo
6160: 72 0a 65 6e 64 20 6f 66 20 66 69 6c 65 2e 20 49 r.end of file. I
6170: 66 20 5c 66 49 76 61 72 4e 61 6d 65 5c 66 52 20 f \fIvarName\fR
6180: 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 is specified, th
6190: 65 20 63 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e e command return
61a0: 73 20 2d 31 20 6f 6e 20 65 6e 64 20 6f 66 20 66 s -1 on end of f
61b0: 69 6c 65 2e 0a 54 68 65 72 65 20 69 73 20 6e 6f ile..There is no
61c0: 20 61 6d 62 69 67 75 69 74 79 20 69 6e 20 74 68 ambiguity in th
61d0: 69 73 20 63 61 73 65 20 62 65 63 61 75 73 65 20 is case because
61e0: 62 6c 61 6e 6b 20 6c 69 6e 65 73 20 72 65 73 75 blank lines resu
61f0: 6c 74 20 69 6e 20 30 20 62 65 69 6e 67 20 72 65 lt in 0 being re
6200: 74 75 72 6e 65 64 2e 0a 2e 52 45 0a 2e 52 53 0a turned...RE..RS.
6210: 2e 50 50 0a 49 66 20 61 20 6e 6f 6e 2d 62 6c 6f .PP.If a non-blo
6220: 63 6b 69 6e 67 20 63 68 61 6e 6e 65 6c 20 69 73 cking channel is
6230: 20 61 6c 72 65 61 64 79 20 61 74 20 45 4f 46 2c already at EOF,
6240: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 65 74 the command ret
6250: 75 72 6e 73 20 61 6e 20 65 6d 70 74 79 20 6c 69 urns an empty li
6260: 6e 65 0a 69 66 20 5c 66 49 76 61 72 4e 61 6d 65 ne.if \fIvarName
6270: 5c 66 52 20 69 73 20 6e 6f 74 20 73 70 65 63 69 \fR is not speci
6280: 66 69 65 64 2e 20 54 68 69 73 20 63 61 6e 20 62 fied. This can b
6290: 65 20 64 69 73 74 69 6e 67 75 69 73 68 65 64 20 e distinguished
62a0: 66 72 6f 6d 20 61 6e 20 65 6d 70 74 79 20 6c 69 from an empty li
62b0: 6e 65 0a 62 65 69 6e 67 20 72 65 74 75 72 6e 65 ne.being returne
62c0: 64 20 62 79 20 65 69 74 68 65 72 20 61 20 62 6c d by either a bl
62d0: 61 6e 6b 20 6c 69 6e 65 20 62 65 69 6e 67 20 72 ank line being r
62e0: 65 61 64 20 6f 72 20 61 20 66 75 6c 6c 20 6c 69 ead or a full li
62f0: 6e 65 20 6e 6f 74 20 62 65 69 6e 67 20 61 76 61 ne not being ava
6300: 69 6c 61 62 6c 65 0a 74 68 72 6f 75 67 68 20 74 ilable.through t
6310: 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5c 66 he use of the \f
6320: 42 63 68 61 6e 20 65 6f 66 5c 66 52 20 61 6e 64 Bchan eof\fR and
6330: 20 5c 66 42 63 68 61 6e 20 62 6c 6f 63 6b 65 64 \fBchan blocked
6340: 5c 66 52 20 63 6f 6d 6d 61 6e 64 73 2e 20 49 66 \fR commands. If
6350: 0a 5c 66 42 63 68 61 6e 20 65 6f 66 5c 66 52 20 .\fBchan eof\fR
6360: 72 65 74 75 72 6e 73 20 74 72 75 65 2c 20 74 68 returns true, th
6370: 65 20 63 68 61 6e 6e 65 6c 20 69 73 20 61 74 20 e channel is at
6380: 45 4f 46 2e 20 49 66 20 5c 66 42 63 68 61 6e 20 EOF. If \fBchan
6390: 62 6c 6f 63 6b 65 64 5c 66 52 20 72 65 74 75 72 blocked\fR retur
63a0: 6e 73 0a 74 72 75 65 2c 20 61 20 66 75 6c 6c 20 ns.true, a full
63b0: 6c 69 6e 65 20 77 61 73 20 6e 6f 74 20 61 76 61 line was not ava
63c0: 69 6c 61 62 6c 65 2e 20 49 66 20 62 6f 74 68 20 ilable. If both
63d0: 63 6f 6d 6d 61 6e 64 73 20 72 65 74 75 72 6e 20 commands return
63e0: 66 61 6c 73 65 2c 20 61 6e 20 65 6d 70 74 79 0a false, an empty.
63f0: 6c 69 6e 65 20 77 61 73 20 72 65 61 64 2e 20 49 line was read. I
6400: 66 20 5c 66 49 76 61 72 4e 61 6d 65 5c 66 52 20 f \fIvarName\fR
6410: 77 61 73 20 73 70 65 63 69 66 69 65 64 20 66 6f was specified fo
6420: 72 20 61 20 6e 6f 6e 2d 62 6f 63 6b 69 6e 67 20 r a non-bocking
6430: 63 68 61 6e 6e 65 6c 20 61 74 20 45 4f 46 2c 0a channel at EOF,.
6440: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 65 74 75 the command retu
6450: 72 6e 73 20 2d 31 2e 20 54 68 69 73 20 63 61 6e rns -1. This can
6460: 20 62 65 20 64 69 73 74 69 6e 67 75 69 73 68 65 be distinguishe
6470: 64 20 66 72 6f 6d 20 66 75 6c 6c 20 6c 69 6e 65 d from full line
6480: 20 6e 6f 74 20 62 65 69 6e 67 0a 61 76 61 69 6c not being.avail
6490: 61 62 6c 65 20 65 69 74 68 65 72 20 62 79 20 5c able either by \
64a0: 66 42 63 68 61 6e 20 65 6f 66 5c 66 52 20 6f 72 fBchan eof\fR or
64b0: 20 5c 66 42 63 68 61 6e 20 62 6c 6f 63 6b 65 64 \fBchan blocked
64c0: 5c 66 52 20 61 73 20 61 62 6f 76 65 2e 20 4e 6f \fR as above. No
64d0: 74 65 20 74 68 61 74 0a 77 68 65 6e 20 5c 66 49 te that.when \fI
64e0: 76 61 72 4e 61 6d 65 5c 66 52 20 69 73 20 73 70 varName\fR is sp
64f0: 65 63 69 66 69 65 64 2c 20 74 68 65 72 65 20 69 ecified, there i
6500: 73 20 6e 6f 20 6e 65 65 64 20 74 6f 20 64 69 73 s no need to dis
6510: 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e tinguish between
6520: 20 65 6f 66 0a 61 6e 64 20 62 6c 61 6e 6b 20 6c eof.and blank l
6530: 69 6e 65 73 20 61 73 20 74 68 65 20 6c 61 74 74 ines as the latt
6540: 65 72 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 er will result i
6550: 6e 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 72 65 n the command re
6560: 74 75 72 6e 69 6e 67 20 30 2e 0a 2e 50 50 0a 49 turning 0...PP.I
6570: 66 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 70 f the encoding p
6580: 72 6f 66 69 6c 65 20 5c 66 42 73 74 72 69 63 74 rofile \fBstrict
6590: 5c 66 52 20 69 73 20 69 6e 20 65 66 66 65 63 74 \fR is in effect
65a0: 20 66 6f 72 20 74 68 65 20 63 68 61 6e 6e 65 6c for the channel
65b0: 2c 20 74 68 65 20 63 6f 6d 6d 61 6e 64 0a 77 69 , the command.wi
65c0: 6c 6c 20 72 61 69 73 65 20 61 6e 20 65 78 63 65 ll raise an exce
65d0: 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 50 ption with the P
65e0: 4f 53 49 58 20 65 72 72 6f 72 20 63 6f 64 65 20 OSIX error code
65f0: 5c 66 42 45 49 4c 53 45 51 5c 66 52 20 69 66 20 \fBEILSEQ\fR if
6600: 61 6e 79 20 65 6e 63 6f 64 69 6e 67 0a 65 72 72 any encoding.err
6610: 6f 72 73 20 61 72 65 20 65 6e 63 6f 75 6e 74 65 ors are encounte
6620: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 6e 6e red in the chann
6630: 65 6c 20 69 6e 70 75 74 20 64 61 74 61 2e 20 54 el input data. T
6640: 68 65 20 66 69 6c 65 20 70 6f 69 6e 74 65 72 20 he file pointer
6650: 72 65 6d 61 69 6e 73 0a 75 6e 63 68 61 6e 67 65 remains.unchange
6660: 64 20 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73 d and it is poss
6670: 69 62 6c 65 20 74 6f 20 69 6e 74 72 6f 73 70 65 ible to introspe
6680: 63 74 2c 20 61 6e 64 20 69 6e 20 73 6f 6d 65 20 ct, and in some
6690: 63 61 73 65 73 20 72 65 63 6f 76 65 72 2c 20 62 cases recover, b
66a0: 79 0a 63 68 61 6e 67 69 6e 67 20 74 68 65 20 65 y.changing the e
66b0: 6e 63 6f 64 69 6e 67 20 69 6e 20 75 73 65 2e 20 ncoding in use.
66c0: 53 65 65 20 5c 66 42 45 4e 43 4f 44 49 4e 47 20 See \fBENCODING
66d0: 45 52 52 4f 52 20 45 58 41 4d 50 4c 45 53 5c 66 ERROR EXAMPLES\f
66e0: 52 20 6c 61 74 65 72 2e 0a 2e 52 45 0a 2e 5c 22 R later...RE..\"
66f0: 20 4d 45 54 48 4f 44 3a 20 6e 61 6d 65 73 0a 2e METHOD: names..
6700: 54 50 0a 5c 66 42 63 68 61 6e 20 6e 61 6d 65 73 TP.\fBchan names
6710: 5c 66 52 20 3f 5c 66 49 70 61 74 74 65 72 6e 5c \fR ?\fIpattern\
6720: 66 52 3f 0a 2e 0a 50 72 6f 64 75 63 65 73 20 61 fR?...Produces a
6730: 20 6c 69 73 74 20 6f 66 20 61 6c 6c 20 63 68 61 list of all cha
6740: 6e 6e 65 6c 20 6e 61 6d 65 73 2e 20 49 66 20 5c nnel names. If \
6750: 66 49 70 61 74 74 65 72 6e 5c 66 52 20 69 73 20 fIpattern\fR is
6760: 73 70 65 63 69 66 69 65 64 2c 0a 6f 6e 6c 79 20 specified,.only
6770: 74 68 6f 73 65 20 63 68 61 6e 6e 65 6c 20 6e 61 those channel na
6780: 6d 65 73 20 74 68 61 74 20 6d 61 74 63 68 20 69 mes that match i
6790: 74 20 28 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 t (according to
67a0: 74 68 65 20 72 75 6c 65 73 20 6f 66 0a 5c 66 42 the rules of.\fB
67b0: 73 74 72 69 6e 67 20 6d 61 74 63 68 5c 66 52 29 string match\fR)
67c0: 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 will be returne
67d0: 64 2e 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a 20 70 d...\" METHOD: p
67e0: 65 6e 64 69 6e 67 0a 2e 54 50 0a 5c 66 42 63 68 ending..TP.\fBch
67f0: 61 6e 20 70 65 6e 64 69 6e 67 20 5c 66 49 6d 6f an pending \fImo
6800: 64 65 20 63 68 61 6e 6e 65 6c 5c 66 52 0a 2e 0a de channel\fR...
6810: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 65 Depending on whe
6820: 74 68 65 72 20 5c 66 49 6d 6f 64 65 5c 66 52 20 ther \fImode\fR
6830: 69 73 20 5c 66 42 69 6e 70 75 74 5c 66 52 20 6f is \fBinput\fR o
6840: 72 20 5c 66 42 6f 75 74 70 75 74 5c 66 52 2c 0a r \fBoutput\fR,.
6850: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
6860: 65 72 20 6f 66 0a 62 79 74 65 73 20 6f 66 20 69 er of.bytes of i
6870: 6e 70 75 74 20 6f 72 20 6f 75 74 70 75 74 20 28 nput or output (
6880: 72 65 73 70 65 63 74 69 76 65 6c 79 29 20 63 75 respectively) cu
6890: 72 72 65 6e 74 6c 79 20 62 75 66 66 65 72 65 64 rrently buffered
68a0: 0a 69 6e 74 65 72 6e 61 6c 6c 79 20 66 6f 72 20 .internally for
68b0: 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 20 28 65 \fIchannel\fR (e
68c0: 73 70 65 63 69 61 6c 6c 79 20 75 73 65 66 75 6c specially useful
68d0: 20 69 6e 20 61 20 72 65 61 64 61 62 6c 65 20 65 in a readable e
68e0: 76 65 6e 74 0a 63 61 6c 6c 62 61 63 6b 20 74 6f vent.callback to
68f0: 20 69 6d 70 6f 73 65 20 61 70 70 6c 69 63 61 74 impose applicat
6900: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 6c 69 6d ion-specific lim
6910: 69 74 73 20 6f 6e 20 69 6e 70 75 74 20 6c 69 6e its on input lin
6920: 65 20 6c 65 6e 67 74 68 73 20 74 6f 20 61 76 6f e lengths to avo
6930: 69 64 0a 61 20 70 6f 74 65 6e 74 69 61 6c 20 64 id.a potential d
6940: 65 6e 69 61 6c 2d 6f 66 2d 73 65 72 76 69 63 65 enial-of-service
6950: 20 61 74 74 61 63 6b 20 77 68 65 72 65 20 61 20 attack where a
6960: 68 6f 73 74 69 6c 65 20 75 73 65 72 20 63 72 61 hostile user cra
6970: 66 74 73 0a 61 6e 20 65 78 74 72 65 6d 65 6c 79 fts.an extremely
6980: 20 6c 6f 6e 67 20 6c 69 6e 65 20 74 68 61 74 20 long line that
6990: 65 78 63 65 65 64 73 20 74 68 65 20 61 76 61 69 exceeds the avai
69a0: 6c 61 62 6c 65 20 6d 65 6d 6f 72 79 20 74 6f 20 lable memory to
69b0: 62 75 66 66 65 72 20 69 74 29 2e 0a 52 65 74 75 buffer it)..Retu
69c0: 72 6e 73 20 2d 31 20 69 66 20 74 68 65 20 63 68 rns -1 if the ch
69d0: 61 6e 6e 65 6c 20 77 61 73 20 6e 6f 74 20 6f 70 annel was not op
69e0: 65 6e 65 64 20 66 6f 72 20 74 68 65 20 6d 6f 64 ened for the mod
69f0: 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 0a 2e e in question...
6a00: 5c 22 20 4d 45 54 48 4f 44 3a 20 70 69 70 65 0a \" METHOD: pipe.
6a10: 2e 54 50 0a 5c 66 42 63 68 61 6e 20 70 69 70 65 .TP.\fBchan pipe
6a20: 5c 66 52 0a 2e 0a 43 72 65 61 74 65 73 20 61 20 \fR...Creates a
6a30: 73 74 61 6e 64 61 6c 6f 6e 65 20 70 69 70 65 20 standalone pipe
6a40: 77 68 6f 73 65 20 72 65 61 64 2d 20 61 6e 64 20 whose read- and
6a50: 77 72 69 74 65 2d 73 69 64 65 20 63 68 61 6e 6e write-side chann
6a60: 65 6c 73 20 61 72 65 0a 72 65 74 75 72 6e 65 64 els are.returned
6a70: 20 61 73 20 61 20 32 2d 65 6c 65 6d 65 6e 74 20 as a 2-element
6a80: 6c 69 73 74 2c 20 74 68 65 20 66 69 72 73 74 20 list, the first
6a90: 65 6c 65 6d 65 6e 74 20 62 65 69 6e 67 20 74 68 element being th
6aa0: 65 20 72 65 61 64 20 73 69 64 65 20 61 6e 64 0a e read side and.
6ab0: 74 68 65 20 73 65 63 6f 6e 64 20 74 68 65 20 77 the second the w
6ac0: 72 69 74 65 20 73 69 64 65 2e 20 43 61 6e 20 62 rite side. Can b
6ad0: 65 20 75 73 65 66 75 6c 20 65 2e 67 2e 20 74 6f e useful e.g. to
6ae0: 20 72 65 64 69 72 65 63 74 0a 73 65 70 61 72 61 redirect.separa
6af0: 74 65 6c 79 20 5c 66 42 73 74 64 65 72 72 5c 66 tely \fBstderr\f
6b00: 52 20 61 6e 64 20 5c 66 42 73 74 64 6f 75 74 5c R and \fBstdout\
6b10: 66 52 20 66 72 6f 6d 20 61 20 73 75 62 70 72 6f fR from a subpro
6b20: 63 65 73 73 2e 20 54 6f 20 64 6f 0a 74 68 69 73 cess. To do.this
6b30: 2c 20 73 70 61 77 6e 20 77 69 74 68 20 22 32 3e , spawn with "2>
6b40: 40 22 20 6f 72 0a 22 3e 40 22 20 72 65 64 69 72 @" or.">@" redir
6b50: 65 63 74 69 6f 6e 20 6f 70 65 72 61 74 6f 72 73 ection operators
6b60: 20 6f 6e 74 6f 20 74 68 65 20 77 72 69 74 65 20 onto the write
6b70: 73 69 64 65 20 6f 66 20 61 20 70 69 70 65 2c 20 side of a pipe,
6b80: 61 6e 64 20 74 68 65 6e 0a 69 6d 6d 65 64 69 61 and then.immedia
6b90: 74 65 6c 79 20 63 6c 6f 73 65 20 69 74 20 69 6e tely close it in
6ba0: 20 74 68 65 20 70 61 72 65 6e 74 2e 20 54 68 69 the parent. Thi
6bb0: 73 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 s is necessary t
6bc0: 6f 20 67 65 74 20 61 6e 20 45 4f 46 20 6f 6e 0a o get an EOF on.
6bd0: 74 68 65 20 72 65 61 64 20 73 69 64 65 20 6f 6e the read side on
6be0: 63 65 20 74 68 65 20 63 68 69 6c 64 20 68 61 73 ce the child has
6bf0: 20 65 78 69 74 65 64 20 6f 72 20 6f 74 68 65 72 exited or other
6c00: 77 69 73 65 20 63 6c 6f 73 65 64 20 69 74 73 20 wise closed its
6c10: 6f 75 74 70 75 74 2e 0a 2e 52 53 0a 2e 50 50 0a output...RS..PP.
6c20: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 70 69 Note that the pi
6c30: 70 65 20 62 75 66 66 65 72 69 6e 67 20 73 65 6d pe buffering sem
6c40: 61 6e 74 69 63 73 20 63 61 6e 20 76 61 72 79 20 antics can vary
6c50: 61 74 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 at the operating
6c60: 20 73 79 73 74 65 6d 20 6c 65 76 65 6c 0a 73 75 system level.su
6c70: 62 73 74 61 6e 74 69 61 6c 6c 79 3b 20 69 74 20 bstantially; it
6c80: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 61 is not safe to a
6c90: 73 73 75 6d 65 20 74 68 61 74 20 61 20 77 72 69 ssume that a wri
6ca0: 74 65 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 te performed on
6cb0: 74 68 65 20 6f 75 74 70 75 74 0a 73 69 64 65 20 the output.side
6cc0: 6f 66 20 74 68 65 20 70 69 70 65 20 77 69 6c 6c of the pipe will
6cd0: 20 61 70 70 65 61 72 20 69 6e 73 74 61 6e 74 6c appear instantl
6ce0: 79 20 74 6f 20 74 68 65 20 69 6e 70 75 74 20 73 y to the input s
6cf0: 69 64 65 2e 20 54 68 69 73 20 69 73 20 61 0a 66 ide. This is a.f
6d00: 75 6e 64 61 6d 65 6e 74 61 6c 20 64 69 66 66 65 undamental diffe
6d10: 72 65 6e 63 65 20 61 6e 64 20 54 63 6c 20 63 61 rence and Tcl ca
6d20: 6e 6e 6f 74 20 63 6f 6e 63 65 61 6c 20 69 74 2e nnot conceal it.
6d30: 20 54 68 65 20 6f 76 65 72 61 6c 6c 20 73 74 72 The overall str
6d40: 65 61 6d 20 73 65 6d 61 6e 74 69 63 73 0a 5c 66 eam semantics.\f
6d50: 49 61 72 65 5c 66 52 20 63 6f 6d 70 61 74 69 62 Iare\fR compatib
6d60: 6c 65 2c 20 73 6f 20 62 6c 6f 63 6b 69 6e 67 20 le, so blocking
6d70: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
6d80: 20 77 69 6c 6c 20 6e 6f 74 20 73 65 65 20 6d 6f will not see mo
6d90: 73 74 20 6f 66 20 74 68 65 0a 64 69 66 66 65 72 st of the.differ
6da0: 65 6e 63 65 73 2c 20 62 75 74 20 74 68 65 20 64 ences, but the d
6db0: 65 74 61 69 6c 73 20 6f 66 20 77 68 61 74 20 65 etails of what e
6dc0: 78 61 63 74 6c 79 20 67 65 74 73 20 77 72 69 74 xactly gets writ
6dd0: 74 65 6e 20 77 68 65 6e 20 61 72 65 20 6e 6f 74 ten when are not
6de0: 2e 20 54 68 69 73 0a 69 73 20 6d 6f 73 74 20 6c . This.is most l
6df0: 69 6b 65 6c 79 20 74 6f 20 73 68 6f 77 20 75 70 ikely to show up
6e00: 20 77 68 65 6e 20 75 73 69 6e 67 20 70 69 70 65 when using pipe
6e10: 6c 69 6e 65 73 20 66 6f 72 20 74 65 73 74 69 6e lines for testin
6e20: 67 3b 20 63 61 72 65 20 73 68 6f 75 6c 64 20 62 g; care should b
6e30: 65 0a 74 61 6b 65 6e 20 74 6f 20 65 6e 73 75 72 e.taken to ensur
6e40: 65 20 74 68 61 74 20 64 65 61 64 6c 6f 63 6b 73 e that deadlocks
6e50: 20 64 6f 20 6e 6f 74 20 6f 63 63 75 72 20 61 6e do not occur an
6e60: 64 20 74 68 61 74 20 70 6f 74 65 6e 74 69 61 6c d that potential
6e70: 20 73 68 6f 72 74 20 72 65 61 64 73 20 61 72 65 short reads are
6e80: 0a 61 6c 6c 6f 77 65 64 20 66 6f 72 2e 0a 2e 52 .allowed for...R
6e90: 45 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a 20 70 6f E..\" METHOD: po
6ea0: 70 0a 2e 54 50 0a 5c 66 42 63 68 61 6e 20 70 6f p..TP.\fBchan po
6eb0: 70 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 0a p \fIchannel\fR.
6ec0: 2e 0a 52 65 6d 6f 76 65 73 20 74 68 65 20 74 6f ..Removes the to
6ed0: 70 6d 6f 73 74 20 74 72 61 6e 73 66 6f 72 6d 61 pmost transforma
6ee0: 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 63 68 tion from the ch
6ef0: 61 6e 6e 65 6c 20 5c 66 49 63 68 61 6e 6e 65 6c annel \fIchannel
6f00: 5c 66 52 2c 20 69 66 20 74 68 65 72 65 0a 69 73 \fR, if there.is
6f10: 20 61 6e 79 2e 20 49 66 20 74 68 65 72 65 20 61 any. If there a
6f20: 72 65 20 6e 6f 20 74 72 61 6e 73 66 6f 72 6d 61 re no transforma
6f30: 74 69 6f 6e 73 20 61 64 64 65 64 20 74 6f 20 5c tions added to \
6f40: 66 49 63 68 61 6e 6e 65 6c 5c 66 52 2c 20 74 68 fIchannel\fR, th
6f50: 69 73 20 69 73 0a 65 71 75 69 76 61 6c 65 6e 74 is is.equivalent
6f60: 20 74 6f 20 5c 66 42 63 68 61 6e 20 63 6c 6f 73 to \fBchan clos
6f70: 65 5c 66 52 20 6f 66 20 74 68 61 74 20 63 68 61 e\fR of that cha
6f80: 6e 6e 65 6c 2e 20 54 68 65 20 72 65 73 75 6c 74 nnel. The result
6f90: 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 74 68 65 is normally the
6fa0: 0a 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 62 .empty string, b
6fb0: 75 74 20 63 61 6e 20 62 65 20 61 6e 20 65 72 72 ut can be an err
6fc0: 6f 72 20 69 6e 20 73 6f 6d 65 20 73 69 74 75 61 or in some situa
6fd0: 74 69 6f 6e 73 20 28 69 2e 65 2e 20 77 68 65 72 tions (i.e. wher
6fe0: 65 20 74 68 65 0a 75 6e 64 65 72 6c 79 69 6e 67 e the.underlying
6ff0: 20 73 79 73 74 65 6d 20 73 74 72 65 61 6d 20 69 system stream i
7000: 73 20 63 6c 6f 73 65 64 20 61 6e 64 20 74 68 61 s closed and tha
7010: 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 t results in an
7020: 65 72 72 6f 72 29 2e 0a 2e 5c 22 20 4d 45 54 48 error)...\" METH
7030: 4f 44 3a 20 70 6f 73 74 65 76 65 6e 74 0a 2e 54 OD: postevent..T
7040: 50 0a 5c 66 42 63 68 61 6e 20 70 6f 73 74 65 76 P.\fBchan postev
7050: 65 6e 74 20 5c 66 49 63 68 61 6e 6e 65 6c 20 65 ent \fIchannel e
7060: 76 65 6e 74 53 70 65 63 5c 66 52 0a 2e 0a 54 68 ventSpec\fR...Th
7070: 69 73 20 73 75 62 63 6f 6d 6d 61 6e 64 20 69 73 is subcommand is
7080: 20 75 73 65 64 20 62 79 20 63 6f 6d 6d 61 6e 64 used by command
7090: 20 68 61 6e 64 6c 65 72 73 20 73 70 65 63 69 66 handlers specif
70a0: 69 65 64 20 77 69 74 68 20 5c 66 42 63 68 61 6e ied with \fBchan
70b0: 0a 63 72 65 61 74 65 5c 66 52 2e 20 49 74 20 6e .create\fR. It n
70c0: 6f 74 69 66 69 65 73 20 74 68 65 20 63 68 61 6e otifies the chan
70d0: 6e 65 6c 20 72 65 70 72 65 73 65 6e 74 65 64 20 nel represented
70e0: 62 79 20 74 68 65 20 68 61 6e 64 6c 65 0a 5c 66 by the handle.\f
70f0: 49 63 68 61 6e 6e 65 6c 5c 66 52 20 74 68 61 74 Ichannel\fR that
7100: 20 74 68 65 20 65 76 65 6e 74 28 73 29 20 6c 69 the event(s) li
7110: 73 74 65 64 20 69 6e 20 74 68 65 20 5c 66 49 65 sted in the \fIe
7120: 76 65 6e 74 53 70 65 63 5c 66 52 20 68 61 76 65 ventSpec\fR have
7130: 0a 6f 63 63 75 72 72 65 64 2e 20 54 68 65 20 61 .occurred. The a
7140: 72 67 75 6d 65 6e 74 20 68 61 73 20 74 6f 20 62 rgument has to b
7150: 65 20 61 20 6c 69 73 74 20 63 6f 6e 74 61 69 6e e a list contain
7160: 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 73 ing any of the s
7170: 74 72 69 6e 67 73 0a 5c 66 42 72 65 61 64 5c 66 trings.\fBread\f
7180: 52 20 61 6e 64 20 5c 66 42 77 72 69 74 65 5c 66 R and \fBwrite\f
7190: 52 2e 20 54 68 65 20 6c 69 73 74 20 6d 75 73 74 R. The list must
71a0: 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61 73 contain at leas
71b0: 74 20 6f 6e 65 0a 65 6c 65 6d 65 6e 74 20 61 73 t one.element as
71c0: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b it does not mak
71d0: 65 20 73 65 6e 73 65 20 74 6f 20 69 6e 76 6f 6b e sense to invok
71e0: 65 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 69 66 e the command if
71f0: 20 74 68 65 72 65 20 61 72 65 0a 6e 6f 20 65 76 there are.no ev
7200: 65 6e 74 73 20 74 6f 20 70 6f 73 74 2e 0a 2e 52 ents to post...R
7210: 53 0a 2e 50 50 0a 4e 6f 74 65 20 74 68 61 74 20 S..PP.Note that
7220: 74 68 69 73 20 73 75 62 63 6f 6d 6d 61 6e 64 20 this subcommand
7230: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 can only be used
7240: 20 77 69 74 68 20 63 68 61 6e 6e 65 6c 20 68 61 with channel ha
7250: 6e 64 6c 65 73 20 74 68 61 74 0a 77 65 72 65 20 ndles that.were
7260: 63 72 65 61 74 65 64 2f 6f 70 65 6e 65 64 20 62 created/opened b
7270: 79 20 5c 66 42 63 68 61 6e 20 63 72 65 61 74 65 y \fBchan create
7280: 5c 66 52 2e 20 41 6c 6c 20 6f 74 68 65 72 20 63 \fR. All other c
7290: 68 61 6e 6e 65 6c 73 20 77 69 6c 6c 0a 63 61 75 hannels will.cau
72a0: 73 65 20 74 68 69 73 20 73 75 62 63 6f 6d 6d 61 se this subcomma
72b0: 6e 64 20 74 6f 20 72 65 70 6f 72 74 20 61 6e 20 nd to report an
72c0: 65 72 72 6f 72 2e 0a 2e 50 50 0a 41 73 20 6f 6e error...PP.As on
72d0: 6c 79 20 74 68 65 20 54 63 6c 20 6c 65 76 65 6c ly the Tcl level
72e0: 20 6f 66 20 61 20 63 68 61 6e 6e 65 6c 2c 20 69 of a channel, i
72f0: 2e 65 2e 20 69 74 73 20 63 6f 6d 6d 61 6e 64 20 .e. its command
7300: 68 61 6e 64 6c 65 72 2c 20 73 68 6f 75 6c 64 0a handler, should.
7310: 70 6f 73 74 20 65 76 65 6e 74 73 20 74 6f 20 69 post events to i
7320: 74 20 77 65 20 61 6c 73 6f 20 72 65 73 74 72 69 t we also restri
7330: 63 74 20 74 68 65 20 75 73 61 67 65 20 6f 66 20 ct the usage of
7340: 74 68 69 73 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 this command to
7350: 74 68 65 0a 69 6e 74 65 72 70 72 65 74 65 72 20 the.interpreter
7360: 74 68 61 74 20 63 72 65 61 74 65 64 20 74 68 65 that created the
7370: 20 63 68 61 6e 6e 65 6c 2e 20 49 6e 20 6f 74 68 channel. In oth
7380: 65 72 20 77 6f 72 64 73 2c 20 70 6f 73 74 69 6e er words, postin
7390: 67 20 65 76 65 6e 74 73 0a 74 6f 20 61 20 72 65 g events.to a re
73a0: 66 6c 65 63 74 65 64 20 63 68 61 6e 6e 65 6c 20 flected channel
73b0: 66 72 6f 6d 20 61 6e 20 69 6e 74 65 72 70 72 65 from an interpre
73c0: 74 65 72 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ter that does no
73d0: 74 20 63 6f 6e 74 61 69 6e 20 69 74 27 73 0a 69 t contain it's.i
73e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
73f0: 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 2e 20 41 74 not allowed. At
7400: 74 65 6d 70 74 69 6e 67 20 74 6f 20 70 6f 73 74 tempting to post
7410: 20 61 6e 20 65 76 65 6e 74 20 66 72 6f 6d 20 61 an event from a
7420: 6e 79 0a 6f 74 68 65 72 20 69 6e 74 65 72 70 72 ny.other interpr
7430: 65 74 65 72 20 77 69 6c 6c 20 63 61 75 73 65 20 eter will cause
7440: 74 68 69 73 20 73 75 62 63 6f 6d 6d 61 6e 64 20 this subcommand
7450: 74 6f 20 72 65 70 6f 72 74 20 61 6e 20 65 72 72 to report an err
7460: 6f 72 2e 0a 2e 50 50 0a 41 6e 6f 74 68 65 72 20 or...PP.Another
7470: 72 65 73 74 72 69 63 74 69 6f 6e 20 69 73 20 74 restriction is t
7480: 68 61 74 20 69 74 20 69 73 20 6e 6f 74 20 70 6f hat it is not po
7490: 73 73 69 62 6c 65 20 74 6f 20 70 6f 73 74 20 65 ssible to post e
74a0: 76 65 6e 74 73 20 74 68 61 74 20 74 68 65 0a 49 vents that the.I
74b0: 2f 4f 20 63 6f 72 65 20 68 61 73 20 6e 6f 74 20 /O core has not
74c0: 72 65 67 69 73 74 65 72 65 64 20 61 6e 20 69 6e registered an in
74d0: 74 65 72 65 73 74 20 69 6e 2e 20 54 72 79 69 6e terest in. Tryin
74e0: 67 20 74 6f 20 64 6f 20 73 6f 20 77 69 6c 6c 20 g to do so will
74f0: 63 61 75 73 65 0a 74 68 65 20 6d 65 74 68 6f 64 cause.the method
7500: 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 to throw an err
7510: 6f 72 2e 20 53 65 65 20 74 68 65 20 63 6f 6d 6d or. See the comm
7520: 61 6e 64 20 68 61 6e 64 6c 65 72 20 6d 65 74 68 and handler meth
7530: 6f 64 0a 5c 66 42 77 61 74 63 68 5c 66 52 20 64 od.\fBwatch\fR d
7540: 65 73 63 72 69 62 65 64 20 69 6e 20 5c 66 42 72 escribed in \fBr
7550: 65 66 63 68 61 6e 5c 66 52 2c 20 74 68 65 20 64 efchan\fR, the d
7560: 6f 63 75 6d 65 6e 74 20 73 70 65 63 69 66 79 69 ocument specifyi
7570: 6e 67 0a 74 68 65 20 41 50 49 20 6f 66 20 63 6f ng.the API of co
7580: 6d 6d 61 6e 64 20 68 61 6e 64 6c 65 72 73 20 66 mmand handlers f
7590: 6f 72 20 72 65 66 6c 65 63 74 65 64 20 63 68 61 or reflected cha
75a0: 6e 6e 65 6c 73 2e 0a 2e 50 50 0a 54 68 69 73 20 nnels...PP.This
75b0: 63 6f 6d 6d 61 6e 64 20 69 73 20 5c 66 42 73 61 command is \fBsa
75c0: 66 65 5c 66 52 20 61 6e 64 20 6d 61 64 65 20 61 fe\fR and made a
75d0: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 73 61 66 ccessible to saf
75e0: 65 20 69 6e 74 65 72 70 72 65 74 65 72 73 2e 0a e interpreters..
75f0: 49 74 20 63 61 6e 20 74 72 69 67 67 65 72 20 74 It can trigger t
7600: 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
7610: 5c 66 42 63 68 61 6e 20 65 76 65 6e 74 5c 66 52 \fBchan event\fR
7620: 20 68 61 6e 64 6c 65 72 73 2c 20 77 68 65 74 68 handlers, wheth
7630: 65 72 20 69 6e 20 74 68 65 0a 63 75 72 72 65 6e er in the.curren
7640: 74 20 69 6e 74 65 72 70 72 65 74 65 72 20 6f 72 t interpreter or
7650: 20 69 6e 20 6f 74 68 65 72 20 69 6e 74 65 72 70 in other interp
7660: 72 65 74 65 72 73 20 6f 72 20 6f 74 68 65 72 20 reters or other
7670: 74 68 72 65 61 64 73 2c 20 65 76 65 6e 0a 77 68 threads, even.wh
7680: 65 72 65 20 74 68 65 20 65 76 65 6e 74 20 69 73 ere the event is
7690: 20 70 6f 73 74 65 64 20 66 72 6f 6d 20 61 20 73 posted from a s
76a0: 61 66 65 20 69 6e 74 65 72 70 72 65 74 65 72 20 afe interpreter
76b0: 61 6e 64 20 6c 69 73 74 65 6e 65 64 20 66 6f 72 and listened for
76c0: 20 62 79 0a 61 20 74 72 75 73 74 65 64 20 69 6e by.a trusted in
76d0: 74 65 72 70 72 65 74 65 72 2e 20 5c 66 42 43 68 terpreter. \fBCh
76e0: 61 6e 20 65 76 65 6e 74 5c 66 52 20 68 61 6e 64 an event\fR hand
76f0: 6c 65 72 73 20 61 72 65 20 5c 66 49 61 6c 77 61 lers are \fIalwa
7700: 79 73 5c 66 52 0a 65 78 65 63 75 74 65 64 20 69 ys\fR.executed i
7710: 6e 20 74 68 65 20 69 6e 74 65 72 70 72 65 74 65 n the interprete
7720: 72 20 74 68 61 74 20 73 65 74 20 74 68 65 6d 20 r that set them
7730: 75 70 2e 0a 2e 52 45 0a 2e 5c 22 20 4d 45 54 48 up...RE..\" METH
7740: 4f 44 3a 20 70 75 73 68 0a 2e 54 50 0a 5c 66 42 OD: push..TP.\fB
7750: 63 68 61 6e 20 70 75 73 68 20 5c 66 49 63 68 61 chan push \fIcha
7760: 6e 6e 65 6c 20 63 6d 64 50 72 65 66 69 78 5c 66 nnel cmdPrefix\f
7770: 52 0a 2e 0a 41 64 64 73 20 61 20 6e 65 77 20 74 R...Adds a new t
7780: 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e ransformation on
7790: 20 74 6f 70 20 6f 66 20 74 68 65 20 63 68 61 6e top of the chan
77a0: 6e 65 6c 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 nel \fIchannel\f
77b0: 52 2e 20 54 68 65 0a 5c 66 49 63 6d 64 50 72 65 R. The.\fIcmdPre
77c0: 66 69 78 5c 66 52 20 61 72 67 75 6d 65 6e 74 20 fix\fR argument
77d0: 64 65 73 63 72 69 62 65 73 20 61 20 6c 69 73 74 describes a list
77e0: 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
77f0: 77 6f 72 64 73 20 77 68 69 63 68 20 72 65 70 72 words which repr
7800: 65 73 65 6e 74 0a 61 20 68 61 6e 64 6c 65 72 20 esent.a handler
7810: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
7820: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 d to implement t
7830: 68 65 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f he transformatio
7840: 6e 2e 20 54 68 65 20 63 6f 6d 6d 61 6e 64 0a 70 n. The command.p
7850: 72 65 66 69 78 20 6d 75 73 74 20 70 72 6f 76 69 refix must provi
7860: 64 65 20 74 68 65 20 41 50 49 20 64 65 73 63 72 de the API descr
7870: 69 62 65 64 20 69 6e 20 74 68 65 20 5c 66 42 74 ibed in the \fBt
7880: 72 61 6e 73 63 68 61 6e 5c 66 52 20 6d 61 6e 75 ranschan\fR manu
7890: 61 6c 20 70 61 67 65 2e 0a 54 68 65 20 72 65 73 al page..The res
78a0: 75 6c 74 20 6f 66 20 74 68 69 73 20 73 75 62 63 ult of this subc
78b0: 6f 6d 6d 61 6e 64 20 69 73 20 61 20 68 61 6e 64 ommand is a hand
78c0: 6c 65 20 74 6f 20 74 68 65 20 74 72 61 6e 73 66 le to the transf
78d0: 6f 72 6d 61 74 69 6f 6e 2e 20 4e 6f 74 65 20 74 ormation. Note t
78e0: 68 61 74 20 69 74 0a 69 73 20 69 6d 70 6f 72 74 hat it.is import
78f0: 61 6e 74 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ant to make sure
7900: 20 74 68 61 74 20 74 68 65 20 74 72 61 6e 73 66 that the transf
7910: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 63 61 70 61 ormation is capa
7920: 62 6c 65 20 6f 66 20 73 75 70 70 6f 72 74 69 6e ble of supportin
7930: 67 20 74 68 65 0a 63 68 61 6e 6e 65 6c 20 6d 6f g the.channel mo
7940: 64 65 20 74 68 61 74 20 69 74 20 69 73 20 75 73 de that it is us
7950: 65 64 20 77 69 74 68 20 6f 72 20 74 68 69 73 20 ed with or this
7960: 63 61 6e 20 6d 61 6b 65 20 74 68 65 20 63 68 61 can make the cha
7970: 6e 6e 65 6c 20 6e 65 69 74 68 65 72 0a 72 65 61 nnel neither.rea
7980: 64 61 62 6c 65 20 6e 6f 72 20 77 72 69 74 61 62 dable nor writab
7990: 6c 65 2e 0a 2e 5c 22 20 4d 45 54 48 4f 44 3a 20 le...\" METHOD:
79a0: 70 75 74 73 0a 2e 54 50 0a 5c 66 42 63 68 61 6e puts..TP.\fBchan
79b0: 20 70 75 74 73 5c 66 52 20 3f 5c 66 42 5c 2d 6e puts\fR ?\fB\-n
79c0: 6f 6e 65 77 6c 69 6e 65 5c 66 52 3f 20 3f 5c 66 onewline\fR? ?\f
79d0: 49 63 68 61 6e 6e 65 6c 5c 66 52 3f 20 5c 66 49 Ichannel\fR? \fI
79e0: 73 74 72 69 6e 67 5c 66 52 0a 2e 0a 57 72 69 74 string\fR...Writ
79f0: 65 73 20 5c 66 49 73 74 72 69 6e 67 5c 66 52 20 es \fIstring\fR
7a00: 74 6f 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 6e to the channel n
7a10: 61 6d 65 64 20 5c 66 49 63 68 61 6e 6e 65 6c 5c amed \fIchannel\
7a20: 66 52 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 fR followed by a
7a30: 0a 6e 65 77 6c 69 6e 65 20 63 68 61 72 61 63 74 .newline charact
7a40: 65 72 2e 20 41 20 74 72 61 69 6c 69 6e 67 20 6e er. A trailing n
7a50: 65 77 6c 69 6e 65 20 63 68 61 72 61 63 74 65 72 ewline character
7a60: 20 69 73 20 77 72 69 74 74 65 6e 20 75 6e 6c 65 is written unle
7a70: 73 73 20 74 68 65 0a 6f 70 74 69 6f 6e 61 6c 20 ss the.optional
7a80: 66 6c 61 67 20 5c 66 42 5c 2d 6e 6f 6e 65 77 6c flag \fB\-nonewl
7a90: 69 6e 65 5c 66 52 20 69 73 20 67 69 76 65 6e 2e ine\fR is given.
7aa0: 20 49 66 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 If \fIchannel\f
7ab0: 52 20 69 73 0a 6f 6d 69 74 74 65 64 2c 20 74 68 R is.omitted, th
7ac0: 65 20 73 74 72 69 6e 67 20 69 73 20 77 72 69 74 e string is writ
7ad0: 74 65 6e 20 74 6f 20 74 68 65 20 73 74 61 6e 64 ten to the stand
7ae0: 61 72 64 20 6f 75 74 70 75 74 20 63 68 61 6e 6e ard output chann
7af0: 65 6c 2c 0a 5c 66 42 73 74 64 6f 75 74 5c 66 52 el,.\fBstdout\fR
7b00: 2e 0a 2e 52 53 0a 2e 50 50 0a 4e 65 77 6c 69 6e ...RS..PP.Newlin
7b10: 65 20 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 e characters in
7b20: 74 68 65 20 6f 75 74 70 75 74 20 61 72 65 20 74 the output are t
7b30: 72 61 6e 73 6c 61 74 65 64 20 62 79 20 5c 66 42 ranslated by \fB
7b40: 63 68 61 6e 20 70 75 74 73 5c 66 52 20 74 6f 0a chan puts\fR to.
7b50: 70 6c 61 74 66 6f 72 6d 2d 73 70 65 63 69 66 69 platform-specifi
7b60: 63 20 65 6e 64 2d 6f 66 2d 6c 69 6e 65 20 73 65 c end-of-line se
7b70: 71 75 65 6e 63 65 73 20 61 63 63 6f 72 64 69 6e quences accordin
7b80: 67 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 g to the current
7b90: 6c 79 0a 63 6f 6e 66 69 67 75 72 65 64 20 76 61 ly.configured va
7ba0: 6c 75 65 20 6f 66 20 74 68 65 20 5c 66 42 5c 2d lue of the \fB\-
7bb0: 74 72 61 6e 73 6c 61 74 69 6f 6e 5c 66 52 20 6f translation\fR o
7bc0: 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 63 68 ption for the ch
7bd0: 61 6e 6e 65 6c 0a 28 66 6f 72 20 65 78 61 6d 70 annel.(for examp
7be0: 6c 65 2c 20 6f 6e 20 50 43 73 20 6e 65 77 6c 69 le, on PCs newli
7bf0: 6e 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 nes are normally
7c00: 20 72 65 70 6c 61 63 65 64 20 77 69 74 68 0a 63 replaced with.c
7c10: 61 72 72 69 61 67 65 2d 72 65 74 75 72 6e 2d 6c arriage-return-l
7c20: 69 6e 65 66 65 65 64 20 73 65 71 75 65 6e 63 65 inefeed sequence
7c30: 73 3b 20 73 65 65 20 5c 66 42 63 68 61 6e 20 63 s; see \fBchan c
7c40: 6f 6e 66 69 67 75 72 65 5c 66 52 20 61 62 6f 76 onfigure\fR abov
7c50: 65 20 66 6f 72 0a 64 65 74 61 69 6c 73 29 2e 0a e for.details)..
7c60: 2e 50 50 0a 54 63 6c 20 62 75 66 66 65 72 73 20 .PP.Tcl buffers
7c70: 6f 75 74 70 75 74 20 69 6e 74 65 72 6e 61 6c 6c output internall
7c80: 79 2c 20 73 6f 20 63 68 61 72 61 63 74 65 72 73 y, so characters
7c90: 20 77 72 69 74 74 65 6e 20 77 69 74 68 20 5c 66 written with \f
7ca0: 42 63 68 61 6e 0a 70 75 74 73 5c 66 52 20 6d 61 Bchan.puts\fR ma
7cb0: 79 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6d 6d y not appear imm
7cc0: 65 64 69 61 74 65 6c 79 20 6f 6e 20 74 68 65 20 ediately on the
7cd0: 6f 75 74 70 75 74 20 66 69 6c 65 20 6f 72 20 64 output file or d
7ce0: 65 76 69 63 65 3b 20 54 63 6c 0a 77 69 6c 6c 20 evice; Tcl.will
7cf0: 6e 6f 72 6d 61 6c 6c 79 20 64 65 6c 61 79 20 6f normally delay o
7d00: 75 74 70 75 74 20 75 6e 74 69 6c 20 74 68 65 20 utput until the
7d10: 62 75 66 66 65 72 20 69 73 20 66 75 6c 6c 20 6f buffer is full o
7d20: 72 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 69 73 r the channel is
7d30: 0a 63 6c 6f 73 65 64 2e 20 20 59 6f 75 20 63 61 .closed. You ca
7d40: 6e 20 66 6f 72 63 65 20 6f 75 74 70 75 74 20 74 n force output t
7d50: 6f 20 61 70 70 65 61 72 20 69 6d 6d 65 64 69 61 o appear immedia
7d60: 74 65 6c 79 20 77 69 74 68 20 74 68 65 20 5c 66 tely with the \f
7d70: 42 63 68 61 6e 0a 66 6c 75 73 68 5c 66 52 20 63 Bchan.flush\fR c
7d80: 6f 6d 6d 61 6e 64 2e 0a 2e 50 50 0a 57 68 65 6e ommand...PP.When
7d90: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
7da0: 65 72 20 66 69 6c 6c 73 20 75 70 2c 20 74 68 65 er fills up, the
7db0: 20 5c 66 42 63 68 61 6e 20 70 75 74 73 5c 66 52 \fBchan puts\fR
7dc0: 20 63 6f 6d 6d 61 6e 64 20 77 69 6c 6c 0a 6e 6f command will.no
7dd0: 72 6d 61 6c 6c 79 20 62 6c 6f 63 6b 20 75 6e 74 rmally block unt
7de0: 69 6c 20 61 6c 6c 20 74 68 65 20 62 75 66 66 65 il all the buffe
7df0: 72 65 64 20 64 61 74 61 20 68 61 73 20 62 65 65 red data has bee
7e00: 6e 20 61 63 63 65 70 74 65 64 20 66 6f 72 0a 6f n accepted for.o
7e10: 75 74 70 75 74 20 62 79 20 74 68 65 20 6f 70 65 utput by the ope
7e20: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
7e30: 49 66 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 If \fIchannel\fR
7e40: 20 69 73 20 69 6e 20 6e 6f 6e 2d 62 6c 6f 63 6b is in non-block
7e50: 69 6e 67 0a 6d 6f 64 65 20 74 68 65 6e 20 74 68 ing.mode then th
7e60: 65 20 5c 66 42 63 68 61 6e 20 70 75 74 73 5c 66 e \fBchan puts\f
7e70: 52 20 63 6f 6d 6d 61 6e 64 20 77 69 6c 6c 20 6e R command will n
7e80: 6f 74 20 62 6c 6f 63 6b 20 65 76 65 6e 20 69 66 ot block even if
7e90: 20 74 68 65 0a 6f 70 65 72 61 74 69 6e 67 20 73 the.operating s
7ea0: 79 73 74 65 6d 20 63 61 6e 6e 6f 74 20 61 63 63 ystem cannot acc
7eb0: 65 70 74 20 74 68 65 20 64 61 74 61 2e 20 20 49 ept the data. I
7ec0: 6e 73 74 65 61 64 2c 20 54 63 6c 20 63 6f 6e 74 nstead, Tcl cont
7ed0: 69 6e 75 65 73 20 74 6f 0a 62 75 66 66 65 72 20 inues to.buffer
7ee0: 74 68 65 20 64 61 74 61 20 61 6e 64 20 77 72 69 the data and wri
7ef0: 74 65 73 20 69 74 20 69 6e 20 74 68 65 20 62 61 tes it in the ba
7f00: 63 6b 67 72 6f 75 6e 64 20 61 73 20 66 61 73 74 ckground as fast
7f10: 20 61 73 20 74 68 65 0a 75 6e 64 65 72 6c 79 69 as the.underlyi
7f20: 6e 67 20 66 69 6c 65 20 6f 72 20 64 65 76 69 63 ng file or devic
7f30: 65 20 63 61 6e 20 61 63 63 65 70 74 20 69 74 2e e can accept it.
7f40: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
7f50: 6e 20 6d 75 73 74 20 75 73 65 20 74 68 65 0a 54 n must use the.T
7f60: 63 6c 20 65 76 65 6e 74 20 6c 6f 6f 70 20 66 6f cl event loop fo
7f70: 72 20 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 20 6f r non-blocking o
7f80: 75 74 70 75 74 20 74 6f 20 77 6f 72 6b 3b 20 6f utput to work; o
7f90: 74 68 65 72 77 69 73 65 20 54 63 6c 20 6e 65 76 therwise Tcl nev
7fa0: 65 72 0a 66 69 6e 64 73 20 6f 75 74 20 74 68 61 er.finds out tha
7fb0: 74 20 74 68 65 20 66 69 6c 65 20 6f 72 20 64 65 t the file or de
7fc0: 76 69 63 65 20 69 73 20 72 65 61 64 79 20 66 6f vice is ready fo
7fd0: 72 20 6d 6f 72 65 20 6f 75 74 70 75 74 20 64 61 r more output da
7fe0: 74 61 2e 20 20 49 74 0a 69 73 20 70 6f 73 73 69 ta. It.is possi
7ff0: 62 6c 65 20 66 6f 72 20 61 6e 20 61 72 62 69 74 ble for an arbit
8000: 72 61 72 69 6c 79 20 6c 61 72 67 65 20 61 6d 6f rarily large amo
8010: 75 6e 74 20 6f 66 20 64 61 74 61 20 74 6f 20 62 unt of data to b
8020: 65 20 62 75 66 66 65 72 65 64 20 66 6f 72 0a 61 e buffered for.a
8030: 20 63 68 61 6e 6e 65 6c 20 69 6e 20 6e 6f 6e 2d channel in non-
8040: 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 2c 20 77 blocking mode, w
8050: 68 69 63 68 20 63 6f 75 6c 64 20 63 6f 6e 73 75 hich could consu
8060: 6d 65 20 61 20 6c 61 72 67 65 20 61 6d 6f 75 6e me a large amoun
8070: 74 20 6f 66 0a 6d 65 6d 6f 72 79 2e 20 20 54 6f t of.memory. To
8080: 20 61 76 6f 69 64 20 77 61 73 74 69 6e 67 20 6d avoid wasting m
8090: 65 6d 6f 72 79 2c 20 6e 6f 6e 2d 62 6c 6f 63 6b emory, non-block
80a0: 69 6e 67 20 49 2f 4f 20 73 68 6f 75 6c 64 20 6e ing I/O should n
80b0: 6f 72 6d 61 6c 6c 79 20 62 65 0a 75 73 65 64 20 ormally be.used
80c0: 69 6e 20 61 6e 20 65 76 65 6e 74 2d 64 72 69 76 in an event-driv
80d0: 65 6e 20 66 61 73 68 69 6f 6e 20 77 69 74 68 20 en fashion with
80e0: 74 68 65 20 5c 66 42 63 68 61 6e 20 65 76 65 6e the \fBchan even
80f0: 74 5c 66 52 20 63 6f 6d 6d 61 6e 64 0a 28 64 6f t\fR command.(do
8100: 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 5c 66 42 63 not invoke \fBc
8110: 68 61 6e 20 70 75 74 73 5c 66 52 20 75 6e 6c 65 han puts\fR unle
8120: 73 73 20 79 6f 75 20 68 61 76 65 20 72 65 63 65 ss you have rece
8130: 6e 74 6c 79 20 62 65 65 6e 20 6e 6f 74 69 66 69 ntly been notifi
8140: 65 64 0a 76 69 61 20 61 20 66 69 6c 65 20 65 76 ed.via a file ev
8150: 65 6e 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ent that the cha
8160: 6e 6e 65 6c 20 69 73 20 72 65 61 64 79 20 66 6f nnel is ready fo
8170: 72 20 6d 6f 72 65 20 6f 75 74 70 75 74 20 64 61 r more output da
8180: 74 61 29 2e 0a 2e 50 50 0a 54 68 65 20 63 6f 6d ta)...PP.The com
8190: 6d 61 6e 64 20 77 69 6c 6c 20 72 61 69 73 65 20 mand will raise
81a0: 61 6e 20 65 72 72 6f 72 20 65 78 63 65 70 74 69 an error excepti
81b0: 6f 6e 20 77 69 74 68 20 50 4f 53 49 58 20 65 72 on with POSIX er
81c0: 72 6f 72 20 63 6f 64 65 20 5c 66 42 45 49 4c 53 ror code \fBEILS
81d0: 45 51 5c 66 52 20 69 66 0a 74 68 65 20 65 6e 63 EQ\fR if.the enc
81e0: 6f 64 69 6e 67 20 70 72 6f 66 69 6c 65 20 5c 66 oding profile \f
81f0: 42 73 74 72 69 63 74 5c 66 52 20 69 73 20 69 6e Bstrict\fR is in
8200: 20 65 66 66 65 63 74 20 66 6f 72 20 74 68 65 20 effect for the
8210: 63 68 61 6e 6e 65 6c 20 61 6e 64 20 74 68 65 20 channel and the
8220: 6f 75 74 70 75 74 0a 64 61 74 61 20 63 61 6e 6e output.data cann
8230: 6f 74 20 62 65 20 65 6e 63 6f 64 65 64 20 69 6e ot be encoded in
8240: 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 63 6f the encoding co
8250: 6e 66 69 67 75 72 65 64 20 66 6f 72 20 74 68 65 nfigured for the
8260: 20 63 68 61 6e 6e 65 6c 2e 20 44 61 74 61 0a 6d channel. Data.m
8270: 61 79 20 62 65 20 70 61 72 74 69 61 6c 6c 79 20 ay be partially
8280: 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20 63 written to the c
8290: 68 61 6e 6e 65 6c 20 69 6e 20 74 68 69 73 20 63 hannel in this c
82a0: 61 73 65 2e 0a 2e 52 45 0a 2e 5c 22 20 4d 45 54 ase...RE..\" MET
82b0: 48 4f 44 3a 20 72 65 61 64 0a 2e 54 50 0a 5c 66 HOD: read..TP.\f
82c0: 42 63 68 61 6e 20 72 65 61 64 20 5c 66 49 63 68 Bchan read \fIch
82d0: 61 6e 6e 65 6c 5c 66 52 20 3f 5c 66 49 6e 75 6d annel\fR ?\fInum
82e0: 43 68 61 72 73 5c 66 52 3f 0a 2e 54 50 0a 5c 66 Chars\fR?..TP.\f
82f0: 42 63 68 61 6e 20 72 65 61 64 20 5c 66 52 3f 5c Bchan read \fR?\
8300: 66 42 5c 2d 6e 6f 6e 65 77 6c 69 6e 65 5c 66 52 fB\-nonewline\fR
8310: 3f 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 52 0a ? \fIchannel\fR.
8320: 2e 0a 49 6e 20 74 68 65 20 66 69 72 73 74 20 66 ..In the first f
8330: 6f 72 6d 2c 20 74 68 65 20 72 65 73 75 6c 74 20 orm, the result
8340: 77 69 6c 6c 20 62 65 20 74 68 65 20 6e 65 78 74 will be the next
8350: 20 5c 66 49 6e 75 6d 43 68 61 72 73 5c 66 52 0a \fInumChars\fR.
8360: 63 68 61 72 61 63 74 65 72 73 20 72 65 61 64 20 characters read
8370: 66 72 6f 6d 20 74 68 65 20 63 68 61 6e 6e 65 6c from the channel
8380: 20 6e 61 6d 65 64 20 5c 66 49 63 68 61 6e 6e 65 named \fIchanne
8390: 6c 5c 66 52 3b 20 69 66 0a 5c 66 49 6e 75 6d 43 l\fR; if.\fInumC
83a0: 68 61 72 73 5c 66 52 20 69 73 20 6f 6d 69 74 74 hars\fR is omitt
83b0: 65 64 2c 20 61 6c 6c 20 63 68 61 72 61 63 74 65 ed, all characte
83c0: 72 73 20 75 70 20 74 6f 20 74 68 65 20 70 6f 69 rs up to the poi
83d0: 6e 74 20 77 68 65 6e 20 74 68 65 0a 63 68 61 6e nt when the.chan
83e0: 6e 65 6c 20 77 6f 75 6c 64 20 73 69 67 6e 61 6c nel would signal
83f0: 20 61 20 66 61 69 6c 75 72 65 20 28 77 68 65 74 a failure (whet
8400: 68 65 72 20 61 6e 20 65 6e 64 2d 6f 66 2d 66 69 her an end-of-fi
8410: 6c 65 2c 20 62 6c 6f 63 6b 65 64 20 6f 72 0a 6f le, blocked or.o
8420: 74 68 65 72 20 65 72 72 6f 72 20 63 6f 6e 64 69 ther error condi
8430: 74 69 6f 6e 29 20 61 72 65 20 72 65 61 64 2e 20 tion) are read.
8440: 49 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 66 6f In the second fo
8450: 72 6d 20 28 69 2e 65 2e 20 77 68 65 6e 0a 5c 66 rm (i.e. when.\f
8460: 49 6e 75 6d 43 68 61 72 73 5c 66 52 20 68 61 73 InumChars\fR has
8470: 20 62 65 65 6e 20 6f 6d 69 74 74 65 64 29 20 74 been omitted) t
8480: 68 65 20 66 6c 61 67 20 5c 66 42 5c 2d 6e 6f 6e he flag \fB\-non
8490: 65 77 6c 69 6e 65 5c 66 52 20 6d 61 79 20 62 65 ewline\fR may be
84a0: 0a 67 69 76 65 6e 20 74 6f 20 69 6e 64 69 63 61 .given to indica
84b0: 74 65 20 74 68 61 74 20 61 6e 79 20 74 72 61 69 te that any trai
84c0: 6c 69 6e 67 20 6e 65 77 6c 69 6e 65 20 69 6e 20 ling newline in
84d0: 74 68 65 20 73 74 72 69 6e 67 20 74 68 61 74 20 the string that
84e0: 68 61 73 0a 62 65 65 6e 20 72 65 61 64 20 73 68 has.been read sh
84f0: 6f 75 6c 64 20 62 65 20 74 72 69 6d 6d 65 64 2e ould be trimmed.
8500: 0a 2e 52 53 0a 2e 50 50 0a 49 66 20 5c 66 49 63 ..RS..PP.If \fIc
8510: 68 61 6e 6e 65 6c 5c 66 52 20 69 73 20 69 6e 20 hannel\fR is in
8520: 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 non-blocking mod
8530: 65 2c 20 5c 66 42 63 68 61 6e 20 72 65 61 64 5c e, \fBchan read\
8540: 66 52 20 6d 61 79 20 6e 6f 74 0a 72 65 61 64 20 fR may not.read
8550: 61 73 20 6d 61 6e 79 20 63 68 61 72 61 63 74 65 as many characte
8560: 72 73 20 61 73 20 72 65 71 75 65 73 74 65 64 3a rs as requested:
8570: 20 6f 6e 63 65 20 61 6c 6c 20 61 76 61 69 6c 61 once all availa
8580: 62 6c 65 20 69 6e 70 75 74 20 68 61 73 0a 62 65 ble input has.be
8590: 65 6e 20 72 65 61 64 2c 20 74 68 65 20 63 6f 6d en read, the com
85a0: 6d 61 6e 64 20 77 69 6c 6c 20 72 65 74 75 72 6e mand will return
85b0: 20 74 68 65 20 64 61 74 61 20 74 68 61 74 20 69 the data that i
85c0: 73 20 61 76 61 69 6c 61 62 6c 65 20 72 61 74 68 s available rath
85d0: 65 72 0a 74 68 61 6e 20 62 6c 6f 63 6b 69 6e 67 er.than blocking
85e0: 20 66 6f 72 20 6d 6f 72 65 20 69 6e 70 75 74 2e for more input.
85f0: 20 20 49 66 20 74 68 65 20 63 68 61 6e 6e 65 6c If the channel
8600: 20 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 74 is configured t
8610: 6f 20 75 73 65 20 61 0a 6d 75 6c 74 69 2d 62 79 o use a.multi-by
8620: 74 65 20 65 6e 63 6f 64 69 6e 67 2c 20 74 68 65 te encoding, the
8630: 6e 20 74 68 65 72 65 20 6d 61 79 20 61 63 74 75 n there may actu
8640: 61 6c 6c 79 20 62 65 20 73 6f 6d 65 20 62 79 74 ally be some byt
8650: 65 73 20 72 65 6d 61 69 6e 69 6e 67 0a 69 6e 20 es remaining.in
8660: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 the internal buf
8670: 66 65 72 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 fers that do not
8680: 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 form a complete
8690: 20 63 68 61 72 61 63 74 65 72 2e 20 20 54 68 65 character. The
86a0: 73 65 0a 62 79 74 65 73 20 77 69 6c 6c 20 6e 6f se.bytes will no
86b0: 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 75 6e t be returned un
86c0: 74 69 6c 20 61 20 63 6f 6d 70 6c 65 74 65 20 63 til a complete c
86d0: 68 61 72 61 63 74 65 72 20 69 73 20 61 76 61 69 haracter is avai
86e0: 6c 61 62 6c 65 20 6f 72 0a 65 6e 64 2d 6f 66 2d lable or.end-of-
86f0: 66 69 6c 65 20 69 73 20 72 65 61 63 68 65 64 2e file is reached.
8700: 20 20 54 68 65 20 5c 66 42 5c 2d 6e 6f 6e 65 77 The \fB\-nonew
8710: 6c 69 6e 65 5c 66 52 20 73 77 69 74 63 68 20 69 line\fR switch i
8720: 73 20 69 67 6e 6f 72 65 64 20 69 66 0a 74 68 65 s ignored if.the
8730: 20 63 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e 73 command returns
8740: 20 62 65 66 6f 72 65 20 72 65 61 63 68 69 6e 67 before reaching
8750: 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
8760: 66 69 6c 65 2e 0a 2e 50 50 0a 5c 66 42 43 68 61 file...PP.\fBCha
8770: 6e 20 72 65 61 64 5c 66 52 20 74 72 61 6e 73 6c n read\fR transl
8780: 61 74 65 73 20 65 6e 64 2d 6f 66 2d 6c 69 6e 65 ates end-of-line
8790: 20 73 65 71 75 65 6e 63 65 73 20 69 6e 20 74 68 sequences in th
87a0: 65 20 69 6e 70 75 74 20 69 6e 74 6f 0a 6e 65 77 e input into.new
87b0: 6c 69 6e 65 20 63 68 61 72 61 63 74 65 72 73 20 line characters
87c0: 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
87d0: 20 5c 66 42 5c 2d 74 72 61 6e 73 6c 61 74 69 6f \fB\-translatio
87e0: 6e 5c 66 52 20 6f 70 74 69 6f 6e 20 66 6f 72 20 n\fR option for
87f0: 74 68 65 0a 63 68 61 6e 6e 65 6c 20 28 73 65 65 the.channel (see
8800: 20 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 75 \fBchan configu
8810: 72 65 5c 66 52 20 61 62 6f 76 65 20 66 6f 72 20 re\fR above for
8820: 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 6e 20 a discussion on
8830: 74 68 65 20 77 61 79 73 0a 69 6e 20 77 68 69 63 the ways.in whic
8840: 68 20 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 h \fBchan config
8850: 75 72 65 5c 66 52 20 77 69 6c 6c 20 61 6c 74 65 ure\fR will alte
8860: 72 20 69 6e 70 75 74 29 2e 0a 2e 50 50 0a 57 68 r input)...PP.Wh
8870: 65 6e 20 72 65 61 64 69 6e 67 20 66 72 6f 6d 20 en reading from
8880: 61 20 73 65 72 69 61 6c 20 70 6f 72 74 2c 20 6d a serial port, m
8890: 6f 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ost applications
88a0: 20 73 68 6f 75 6c 64 20 63 6f 6e 66 69 67 75 72 should configur
88b0: 65 0a 74 68 65 20 73 65 72 69 61 6c 20 70 6f 72 e.the serial por
88c0: 74 20 63 68 61 6e 6e 65 6c 20 74 6f 20 62 65 20 t channel to be
88d0: 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 2c 20 6c 69 non-blocking, li
88e0: 6b 65 20 74 68 69 73 3a 0a 2e 50 50 0a 2e 43 53 ke this:..PP..CS
88f0: 0a 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 75 .\fBchan configu
8900: 72 65 20 5c 66 49 63 68 61 6e 6e 65 6c 20 5c 66 re \fIchannel \f
8910: 42 5c 2d 62 6c 6f 63 6b 69 6e 67 20 5c 66 49 30 B\-blocking \fI0
8920: 5c 66 52 2e 0a 2e 43 45 0a 2e 50 50 0a 54 68 65 \fR...CE..PP.The
8930: 6e 20 5c 66 42 63 68 61 6e 20 72 65 61 64 5c 66 n \fBchan read\f
8940: 52 20 62 65 68 61 76 65 73 20 6d 75 63 68 20 6c R behaves much l
8950: 69 6b 65 20 64 65 73 63 72 69 62 65 64 20 61 62 ike described ab
8960: 6f 76 65 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a ove. Note that.
8970: 6d 6f 73 74 20 73 65 72 69 61 6c 20 70 6f 72 74 most serial port
8980: 73 20 61 72 65 20 63 6f 6d 70 61 72 61 74 69 76 s are comparativ
8990: 65 6c 79 20 73 6c 6f 77 3b 20 69 74 20 69 73 20 ely slow; it is
89a0: 65 6e 74 69 72 65 6c 79 20 70 6f 73 73 69 62 6c entirely possibl
89b0: 65 20 74 6f 0a 67 65 74 20 61 20 5c 66 42 72 65 e to.get a \fBre
89c0: 61 64 61 62 6c 65 5c 66 52 20 65 76 65 6e 74 20 adable\fR event
89d0: 66 6f 72 20 65 61 63 68 20 63 68 61 72 61 63 74 for each charact
89e0: 65 72 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65 er read from the
89f0: 6d 2e 20 43 61 72 65 0a 6d 75 73 74 20 62 65 20 m. Care.must be
8a00: 74 61 6b 65 6e 20 77 68 65 6e 20 75 73 69 6e 67 taken when using
8a10: 20 5c 66 42 63 68 61 6e 20 72 65 61 64 5c 66 52 \fBchan read\fR
8a20: 20 6f 6e 20 62 6c 6f 63 6b 69 6e 67 20 73 65 72 on blocking ser
8a30: 69 61 6c 20 70 6f 72 74 73 3a 0a 2e 54 50 0a 5c ial ports:..TP.\
8a40: 66 42 63 68 61 6e 20 72 65 61 64 20 5c 66 49 63 fBchan read \fIc
8a50: 68 61 6e 6e 65 6c 20 6e 75 6d 43 68 61 72 73 5c hannel numChars\
8a60: 66 52 0a 2e 0a 49 6e 20 74 68 69 73 20 66 6f 72 fR...In this for
8a70: 6d 20 5c 66 42 63 68 61 6e 20 72 65 61 64 5c 66 m \fBchan read\f
8a80: 52 20 62 6c 6f 63 6b 73 20 75 6e 74 69 6c 20 5c R blocks until \
8a90: 66 49 6e 75 6d 43 68 61 72 73 5c 66 52 20 68 61 fInumChars\fR ha
8aa0: 76 65 20 62 65 65 6e 0a 72 65 63 65 69 76 65 64 ve been.received
8ab0: 20 66 72 6f 6d 20 74 68 65 20 73 65 72 69 61 6c from the serial
8ac0: 20 70 6f 72 74 2e 0a 2e 54 50 0a 5c 66 42 63 68 port...TP.\fBch
8ad0: 61 6e 20 72 65 61 64 20 5c 66 49 63 68 61 6e 6e an read \fIchann
8ae0: 65 6c 5c 66 52 0a 2e 0a 49 6e 20 74 68 69 73 20 el\fR...In this
8af0: 66 6f 72 6d 20 5c 66 42 63 68 61 6e 20 72 65 61 form \fBchan rea
8b00: 64 5c 66 52 20 62 6c 6f 63 6b 73 20 75 6e 74 69 d\fR blocks unti
8b10: 6c 20 74 68 65 20 72 65 63 65 70 74 69 6f 6e 20 l the reception
8b20: 6f 66 20 74 68 65 0a 65 6e 64 2d 6f 66 2d 66 69 of the.end-of-fi
8b30: 6c 65 20 63 68 61 72 61 63 74 65 72 2c 20 73 65 le character, se
8b40: 65 20 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 e \fBchan config
8b50: 75 72 65 20 2d 65 6f 66 63 68 61 72 5c 66 52 2e ure -eofchar\fR.
8b60: 20 49 66 20 74 68 65 72 65 20 6e 6f 0a 65 6e 64 If there no.end
8b70: 2d 6f 66 2d 66 69 6c 65 20 63 68 61 72 61 63 74 -of-file charact
8b80: 65 72 20 68 61 73 20 62 65 65 6e 20 63 6f 6e 66 er has been conf
8b90: 69 67 75 72 65 64 20 66 6f 72 20 74 68 65 20 63 igured for the c
8ba0: 68 61 6e 6e 65 6c 2c 20 74 68 65 6e 0a 5c 66 42 hannel, then.\fB
8bb0: 63 68 61 6e 20 72 65 61 64 5c 66 52 20 77 69 6c chan read\fR wil
8bc0: 6c 20 62 6c 6f 63 6b 20 66 6f 72 65 76 65 72 2e l block forever.
8bd0: 0a 2e 50 50 0a 49 66 20 74 68 65 20 65 6e 63 6f ..PP.If the enco
8be0: 64 69 6e 67 20 70 72 6f 66 69 6c 65 20 5c 66 42 ding profile \fB
8bf0: 73 74 72 69 63 74 5c 66 52 20 69 73 20 69 6e 20 strict\fR is in
8c00: 65 66 66 65 63 74 20 66 6f 72 20 74 68 65 20 63 effect for the c
8c10: 68 61 6e 6e 65 6c 2c 20 74 68 65 20 63 6f 6d 6d hannel, the comm
8c20: 61 6e 64 0a 77 69 6c 6c 20 72 61 69 73 65 20 61 and.will raise a
8c30: 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 n exception with
8c40: 20 74 68 65 20 50 4f 53 49 58 20 65 72 72 6f 72 the POSIX error
8c50: 20 63 6f 64 65 20 5c 66 42 45 49 4c 53 45 51 5c code \fBEILSEQ\
8c60: 66 52 20 69 66 20 61 6e 79 20 65 6e 63 6f 64 69 fR if any encodi
8c70: 6e 67 0a 65 72 72 6f 72 73 20 61 72 65 20 65 6e ng.errors are en
8c80: 63 6f 75 6e 74 65 72 65 64 20 69 6e 20 74 68 65 countered in the
8c90: 20 63 68 61 6e 6e 65 6c 20 69 6e 70 75 74 20 64 channel input d
8ca0: 61 74 61 2e 20 49 66 20 74 68 65 20 63 68 61 6e ata. If the chan
8cb0: 6e 65 6c 20 69 73 20 69 6e 20 62 6c 6f 63 6b 69 nel is in blocki
8cc0: 6e 67 0a 6d 6f 64 65 2c 20 74 68 65 20 65 72 72 ng.mode, the err
8cd0: 6f 72 20 69 73 20 74 68 72 6f 77 6e 20 61 66 74 or is thrown aft
8ce0: 65 72 20 61 64 76 61 6e 63 69 6e 67 20 74 68 65 er advancing the
8cf0: 20 66 69 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f file pointer to
8d00: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
8d10: 66 0a 74 68 65 20 69 6e 76 61 6c 69 64 20 64 61 f.the invalid da
8d20: 74 61 2e 20 54 68 65 20 73 75 63 63 65 73 73 66 ta. The successf
8d30: 75 6c 6c 79 20 64 65 63 6f 64 65 64 20 6c 65 61 ully decoded lea
8d40: 64 69 6e 67 20 70 6f 72 74 69 6f 6e 20 6f 66 20 ding portion of
8d50: 74 68 65 20 64 61 74 61 20 70 72 69 6f 72 20 74 the data prior t
8d60: 6f 0a 74 68 65 20 65 72 72 6f 72 20 6c 6f 63 61 o.the error loca
8d70: 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 tion is returned
8d80: 20 61 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 as the value of
8d90: 20 74 68 65 20 5c 66 42 5c 2d 64 61 74 61 5c 66 the \fB\-data\f
8da0: 52 20 6b 65 79 20 6f 66 20 74 68 65 20 65 72 72 R key of the err
8db0: 6f 72 0a 6f 70 74 69 6f 6e 20 64 69 63 74 69 6f or.option dictio
8dc0: 6e 61 72 79 2e 20 49 66 20 74 68 65 20 63 68 61 nary. If the cha
8dd0: 6e 6e 65 6c 20 69 73 20 69 6e 20 6e 6f 6e 2d 62 nnel is in non-b
8de0: 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 2c 20 74 68 locking mode, th
8df0: 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 0a 64 e successfully.d
8e00: 65 63 6f 64 65 64 20 70 6f 72 74 69 6f 6e 20 6f ecoded portion o
8e10: 66 20 64 61 74 61 20 69 73 20 72 65 74 75 72 6e f data is return
8e20: 65 64 20 62 79 20 74 68 65 20 63 6f 6d 6d 61 6e ed by the comman
8e30: 64 20 77 69 74 68 6f 75 74 20 61 6e 20 65 72 72 d without an err
8e40: 6f 72 0a 65 78 63 65 70 74 69 6f 6e 20 62 65 69 or.exception bei
8e50: 6e 67 20 72 61 69 73 65 64 2e 20 41 20 73 75 62 ng raised. A sub
8e60: 73 65 71 75 65 6e 74 20 72 65 61 64 20 77 69 6c sequent read wil
8e70: 6c 20 73 74 61 72 74 20 61 74 20 74 68 65 20 69 l start at the i
8e80: 6e 76 61 6c 69 64 20 64 61 74 61 0a 61 6e 64 20 nvalid data.and
8e90: 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 61 69 73 immediately rais
8ea0: 65 20 61 20 5c 66 42 45 49 4c 53 45 51 5c 66 52 e a \fBEILSEQ\fR
8eb0: 20 50 4f 53 49 58 20 65 72 72 6f 72 20 65 78 63 POSIX error exc
8ec0: 65 70 74 69 6f 6e 2e 20 55 6e 6c 69 6b 65 20 74 eption. Unlike t
8ed0: 68 65 0a 62 6c 6f 63 6b 69 6e 67 20 63 68 61 6e he.blocking chan
8ee0: 6e 65 6c 20 63 61 73 65 2c 20 74 68 65 20 5c 66 nel case, the \f
8ef0: 42 5c 2d 64 61 74 61 5c 66 52 20 6b 65 79 20 69 B\-data\fR key i
8f00: 73 20 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 6e s not present in
8f10: 20 74 68 65 0a 65 72 72 6f 72 20 6f 70 74 69 6f the.error optio
8f20: 6e 20 64 69 63 74 69 6f 6e 61 72 79 2e 20 49 6e n dictionary. In
8f30: 20 74 68 65 20 63 61 73 65 20 6f 66 20 65 78 63 the case of exc
8f40: 65 70 74 69 6f 6e 20 74 68 72 6f 77 6e 20 64 75 eption thrown du
8f50: 65 20 74 6f 20 65 6e 63 6f 64 69 6e 67 0a 65 72 e to encoding.er
8f60: 72 6f 72 73 2c 20 69 74 20 69 73 20 70 6f 73 73 rors, it is poss
8f70: 69 62 6c 65 20 74 6f 20 69 6e 74 72 6f 73 70 65 ible to introspe
8f80: 63 74 2c 20 61 6e 64 20 69 6e 20 73 6f 6d 65 20 ct, and in some
8f90: 63 61 73 65 73 20 72 65 63 6f 76 65 72 2c 20 62 cases recover, b
8fa0: 79 0a 63 68 61 6e 67 69 6e 67 20 74 68 65 20 65 y.changing the e
8fb0: 6e 63 6f 64 69 6e 67 20 69 6e 20 75 73 65 2e 20 ncoding in use.
8fc0: 53 65 65 20 5c 66 42 45 4e 43 4f 44 49 4e 47 20 See \fBENCODING
8fd0: 45 52 52 4f 52 20 45 58 41 4d 50 4c 45 53 5c 66 ERROR EXAMPLES\f
8fe0: 52 20 6c 61 74 65 72 2e 0a 2e 52 45 0a 2e 5c 22 R later...RE..\"
8ff0: 20 4d 45 54 48 4f 44 3a 20 73 65 65 6b 0a 2e 54 METHOD: seek..T
9000: 50 0a 5c 66 42 63 68 61 6e 20 73 65 65 6b 20 5c P.\fBchan seek \
9010: 66 49 63 68 61 6e 6e 65 6c 20 6f 66 66 73 65 74 fIchannel offset
9020: 5c 66 52 20 3f 5c 66 49 6f 72 69 67 69 6e 5c 66 \fR ?\fIorigin\f
9030: 52 3f 0a 2e 0a 53 65 74 73 20 74 68 65 20 63 75 R?...Sets the cu
9040: 72 72 65 6e 74 20 61 63 63 65 73 73 20 70 6f 73 rrent access pos
9050: 69 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 ition within the
9060: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 61 74 61 underlying data
9070: 20 73 74 72 65 61 6d 20 66 6f 72 0a 74 68 65 20 stream for.the
9080: 63 68 61 6e 6e 65 6c 20 6e 61 6d 65 64 20 5c 66 channel named \f
9090: 49 63 68 61 6e 6e 65 6c 5c 66 52 20 74 6f 20 62 Ichannel\fR to b
90a0: 65 20 5c 66 49 6f 66 66 73 65 74 5c 66 52 20 62 e \fIoffset\fR b
90b0: 79 74 65 73 20 72 65 6c 61 74 69 76 65 20 74 6f ytes relative to
90c0: 0a 5c 66 49 6f 72 69 67 69 6e 5c 66 52 2e 20 5c .\fIorigin\fR. \
90d0: 66 49 4f 66 66 73 65 74 5c 66 52 20 6d 75 73 74 fIOffset\fR must
90e0: 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 20 28 be an integer (
90f0: 77 68 69 63 68 20 6d 61 79 20 62 65 20 6e 65 67 which may be neg
9100: 61 74 69 76 65 29 0a 61 6e 64 20 5c 66 49 6f 72 ative).and \fIor
9110: 69 67 69 6e 5c 66 52 20 6d 75 73 74 20 62 65 20 igin\fR must be
9120: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
9130: 77 69 6e 67 3a 0a 2e 52 53 0a 2e 49 50 20 5c 66 wing:..RS..IP \f
9140: 42 73 74 61 72 74 5c 66 52 0a 54 68 65 20 6e 65 Bstart\fR.The ne
9150: 77 20 61 63 63 65 73 73 20 70 6f 73 69 74 69 6f w access positio
9160: 6e 20 77 69 6c 6c 20 62 65 20 5c 66 49 6f 66 66 n will be \fIoff
9170: 73 65 74 5c 66 52 20 62 79 74 65 73 20 66 72 6f set\fR bytes fro
9180: 6d 20 74 68 65 20 73 74 61 72 74 0a 6f 66 20 74 m the start.of t
9190: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 66 69 he underlying fi
91a0: 6c 65 20 6f 72 20 64 65 76 69 63 65 2e 0a 2e 49 le or device...I
91b0: 50 20 5c 66 42 63 75 72 72 65 6e 74 5c 66 52 0a P \fBcurrent\fR.
91c0: 54 68 65 20 6e 65 77 20 61 63 63 65 73 73 20 70 The new access p
91d0: 6f 73 69 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 osition will be
91e0: 5c 66 49 6f 66 66 73 65 74 5c 66 52 20 62 79 74 \fIoffset\fR byt
91f0: 65 73 20 66 72 6f 6d 20 74 68 65 20 63 75 72 72 es from the curr
9200: 65 6e 74 0a 61 63 63 65 73 73 20 70 6f 73 69 74 ent.access posit
9210: 69 6f 6e 3b 20 61 20 6e 65 67 61 74 69 76 65 20 ion; a negative
9220: 5c 66 49 6f 66 66 73 65 74 5c 66 52 20 6d 6f 76 \fIoffset\fR mov
9230: 65 73 20 74 68 65 20 61 63 63 65 73 73 20 70 6f es the access po
9240: 73 69 74 69 6f 6e 0a 62 61 63 6b 77 61 72 64 73 sition.backwards
9250: 20 69 6e 20 74 68 65 20 75 6e 64 65 72 6c 79 69 in the underlyi
9260: 6e 67 20 66 69 6c 65 20 6f 72 20 64 65 76 69 63 ng file or devic
9270: 65 2e 0a 2e 49 50 20 5c 66 42 65 6e 64 5c 66 52 e...IP \fBend\fR
9280: 0a 54 68 65 20 6e 65 77 20 61 63 63 65 73 73 20 .The new access
9290: 70 6f 73 69 74 69 6f 6e 20 77 69 6c 6c 20 62 65 position will be
92a0: 20 5c 66 49 6f 66 66 73 65 74 5c 66 52 20 62 79 \fIoffset\fR by
92b0: 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 tes from the end
92c0: 20 6f 66 20 74 68 65 0a 66 69 6c 65 20 6f 72 20 of the.file or
92d0: 64 65 76 69 63 65 2e 20 20 41 20 6e 65 67 61 74 device. A negat
92e0: 69 76 65 20 5c 66 49 6f 66 66 73 65 74 5c 66 52 ive \fIoffset\fR
92f0: 20 70 6c 61 63 65 73 20 74 68 65 20 61 63 63 65 places the acce
9300: 73 73 20 70 6f 73 69 74 69 6f 6e 0a 62 65 66 6f ss position.befo
9310: 72 65 20 74 68 65 20 65 6e 64 20 6f 66 20 66 69 re the end of fi
9320: 6c 65 2c 20 61 6e 64 20 61 20 70 6f 73 69 74 69 le, and a positi
9330: 76 65 20 5c 66 49 6f 66 66 73 65 74 5c 66 52 20 ve \fIoffset\fR
9340: 70 6c 61 63 65 73 20 74 68 65 20 61 63 63 65 73 places the acces
9350: 73 0a 70 6f 73 69 74 69 6f 6e 20 61 66 74 65 72 s.position after
9360: 20 74 68 65 20 65 6e 64 20 6f 66 20 66 69 6c 65 the end of file
9370: 2e 0a 2e 50 50 0a 54 68 65 20 5c 66 49 6f 72 69 ...PP.The \fIori
9380: 67 69 6e 5c 66 52 20 61 72 67 75 6d 65 6e 74 20 gin\fR argument
9390: 64 65 66 61 75 6c 74 73 20 74 6f 20 5c 66 42 73 defaults to \fBs
93a0: 74 61 72 74 5c 66 52 2e 0a 2e 50 50 0a 5c 66 42 tart\fR...PP.\fB
93b0: 43 68 61 6e 20 73 65 65 6b 5c 66 52 20 66 6c 75 Chan seek\fR flu
93c0: 73 68 65 73 20 61 6c 6c 20 62 75 66 66 65 72 65 shes all buffere
93d0: 64 20 6f 75 74 70 75 74 20 66 6f 72 20 74 68 65 d output for the
93e0: 20 63 68 61 6e 6e 65 6c 20 62 65 66 6f 72 65 20 channel before
93f0: 74 68 65 0a 63 6f 6d 6d 61 6e 64 20 72 65 74 75 the.command retu
9400: 72 6e 73 2c 20 65 76 65 6e 20 69 66 20 74 68 65 rns, even if the
9410: 20 63 68 61 6e 6e 65 6c 20 69 73 20 69 6e 20 6e channel is in n
9420: 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 on-blocking mode
9430: 2e 20 20 49 74 20 61 6c 73 6f 0a 64 69 73 63 61 . It also.disca
9440: 72 64 73 20 61 6e 79 20 62 75 66 66 65 72 65 64 rds any buffered
9450: 20 61 6e 64 20 75 6e 72 65 61 64 20 69 6e 70 75 and unread inpu
9460: 74 2e 20 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 t. This command
9470: 20 72 65 74 75 72 6e 73 20 61 6e 20 65 6d 70 74 returns an empt
9480: 79 0a 73 74 72 69 6e 67 2e 20 20 41 6e 20 65 72 y.string. An er
9490: 72 6f 72 20 6f 63 63 75 72 73 20 69 66 20 74 68 ror occurs if th
94a0: 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 61 70 is command is ap
94b0: 70 6c 69 65 64 20 74 6f 20 63 68 61 6e 6e 65 6c plied to channel
94c0: 73 20 77 68 6f 73 65 0a 75 6e 64 65 72 6c 79 69 s whose.underlyi
94d0: 6e 67 20 66 69 6c 65 20 6f 72 20 64 65 76 69 63 ng file or devic
94e0: 65 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f e does not suppo
94f0: 72 74 20 73 65 65 6b 69 6e 67 2e 0a 2e 50 50 0a rt seeking...PP.
9500: 4e 6f 74 65 20 74 68 61 74 20 5c 66 49 6f 66 66 Note that \fIoff
9510: 73 65 74 5c 66 52 20 76 61 6c 75 65 73 20 61 72 set\fR values ar
9520: 65 20 62 79 74 65 20 6f 66 66 73 65 74 73 2c 20 e byte offsets,
9530: 6e 6f 74 20 63 68 61 72 61 63 74 65 72 20 6f 66 not character of
9540: 66 73 65 74 73 2e 0a 42 6f 74 68 20 5c 66 42 63 fsets..Both \fBc
9550: 68 61 6e 20 73 65 65 6b 5c 66 52 20 61 6e 64 20 han seek\fR and
9560: 5c 66 42 63 68 61 6e 20 74 65 6c 6c 5c 66 52 20 \fBchan tell\fR
9570: 6f 70 65 72 61 74 65 20 69 6e 20 74 65 72 6d 73 operate in terms
9580: 20 6f 66 20 62 79 74 65 73 2c 0a 6e 6f 74 20 63 of bytes,.not c
9590: 68 61 72 61 63 74 65 72 73 2c 20 75 6e 6c 69 6b haracters, unlik
95a0: 65 20 5c 66 42 63 68 61 6e 20 72 65 61 64 5c 66 e \fBchan read\f
95b0: 52 2e 0a 2e 52 45 0a 2e 5c 22 20 4d 45 54 48 4f R...RE..\" METHO
95c0: 44 3a 20 74 65 6c 6c 0a 2e 54 50 0a 5c 66 42 63 D: tell..TP.\fBc
95d0: 68 61 6e 20 74 65 6c 6c 20 5c 66 49 63 68 61 6e han tell \fIchan
95e0: 6e 65 6c 5c 66 52 0a 2e 0a 52 65 74 75 72 6e 73 nel\fR...Returns
95f0: 20 61 20 6e 75 6d 62 65 72 20 67 69 76 69 6e 67 a number giving
9600: 20 74 68 65 20 63 75 72 72 65 6e 74 20 61 63 63 the current acc
9610: 65 73 73 20 70 6f 73 69 74 69 6f 6e 20 77 69 74 ess position wit
9620: 68 69 6e 20 74 68 65 0a 75 6e 64 65 72 6c 79 69 hin the.underlyi
9630: 6e 67 20 64 61 74 61 20 73 74 72 65 61 6d 20 66 ng data stream f
9640: 6f 72 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 6e or the channel n
9650: 61 6d 65 64 20 5c 66 49 63 68 61 6e 6e 65 6c 5c amed \fIchannel\
9660: 66 52 2e 20 54 68 69 73 0a 76 61 6c 75 65 20 72 fR. This.value r
9670: 65 74 75 72 6e 65 64 20 69 73 20 61 20 62 79 74 eturned is a byt
9680: 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 63 61 e offset that ca
9690: 6e 20 62 65 20 70 61 73 73 65 64 20 74 6f 20 5c n be passed to \
96a0: 66 42 63 68 61 6e 20 73 65 65 6b 5c 66 52 0a 69 fBchan seek\fR.i
96b0: 6e 20 6f 72 64 65 72 20 74 6f 20 73 65 74 20 74 n order to set t
96c0: 68 65 20 63 68 61 6e 6e 65 6c 20 74 6f 20 61 20 he channel to a
96d0: 70 61 72 74 69 63 75 6c 61 72 20 70 6f 73 69 74 particular posit
96e0: 69 6f 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 ion. Note that
96f0: 74 68 69 73 0a 76 61 6c 75 65 20 69 73 20 69 6e this.value is in
9700: 20 74 65 72 6d 73 20 6f 66 20 62 79 74 65 73 2c terms of bytes,
9710: 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 not characters
9720: 6c 69 6b 65 20 5c 66 42 63 68 61 6e 20 72 65 61 like \fBchan rea
9730: 64 5c 66 52 2e 20 20 54 68 65 0a 76 61 6c 75 65 d\fR. The.value
9740: 20 72 65 74 75 72 6e 65 64 20 69 73 20 2d 31 20 returned is -1
9750: 66 6f 72 20 63 68 61 6e 6e 65 6c 73 20 74 68 61 for channels tha
9760: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 t do not support
9770: 20 73 65 65 6b 69 6e 67 2e 0a 2e 5c 22 20 4d 45 seeking...\" ME
9780: 54 48 4f 44 3a 20 74 72 75 6e 63 61 74 65 0a 2e THOD: truncate..
9790: 54 50 0a 5c 66 42 63 68 61 6e 20 74 72 75 6e 63 TP.\fBchan trunc
97a0: 61 74 65 20 5c 66 49 63 68 61 6e 6e 65 6c 5c 66 ate \fIchannel\f
97b0: 52 20 3f 5c 66 49 6c 65 6e 67 74 68 5c 66 52 3f R ?\fIlength\fR?
97c0: 0a 2e 0a 53 65 74 73 20 74 68 65 20 62 79 74 65 ...Sets the byte
97d0: 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 75 length of the u
97e0: 6e 64 65 72 6c 79 69 6e 67 20 64 61 74 61 20 73 nderlying data s
97f0: 74 72 65 61 6d 20 66 6f 72 20 74 68 65 20 63 68 tream for the ch
9800: 61 6e 6e 65 6c 0a 6e 61 6d 65 64 20 5c 66 49 63 annel.named \fIc
9810: 68 61 6e 6e 65 6c 5c 66 52 20 74 6f 20 62 65 20 hannel\fR to be
9820: 5c 66 49 6c 65 6e 67 74 68 5c 66 52 20 28 6f 72 \fIlength\fR (or
9830: 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
9840: 62 79 74 65 0a 6f 66 66 73 65 74 20 77 69 74 68 byte.offset with
9850: 69 6e 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e in the underlyin
9860: 67 20 64 61 74 61 20 73 74 72 65 61 6d 20 69 66 g data stream if
9870: 20 5c 66 49 6c 65 6e 67 74 68 5c 66 52 20 69 73 \fIlength\fR is
9880: 0a 6f 6d 69 74 74 65 64 29 2e 20 54 68 65 20 63 .omitted). The c
9890: 68 61 6e 6e 65 6c 20 69 73 20 66 6c 75 73 68 65 hannel is flushe
98a0: 64 20 62 65 66 6f 72 65 20 74 72 75 6e 63 61 74 d before truncat
98b0: 69 6f 6e 2e 0a 2e 0a 2e 53 48 20 45 58 41 4d 50 ion.....SH EXAMP
98c0: 4c 45 53 0a 2e 53 53 20 22 53 49 4d 50 4c 45 20 LES..SS "SIMPLE
98d0: 43 48 41 4e 4e 45 4c 20 4f 50 45 52 41 54 49 4f CHANNEL OPERATIO
98e0: 4e 20 45 58 41 4d 50 4c 45 53 22 0a 2e 50 50 0a N EXAMPLES"..PP.
98f0: 49 6e 73 74 72 75 63 74 20 54 63 6c 20 74 6f 20 Instruct Tcl to
9900: 61 6c 77 61 79 73 20 73 65 6e 64 20 6f 75 74 70 always send outp
9910: 75 74 20 74 6f 20 5c 66 42 73 74 64 6f 75 74 5c ut to \fBstdout\
9920: 66 52 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 0a fR immediately,.
9930: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
9940: 74 20 69 73 20 74 6f 20 61 20 74 65 72 6d 69 6e t is to a termin
9950: 61 6c 3a 0a 2e 50 50 0a 2e 43 53 0a 5c 66 42 66 al:..PP..CS.\fBf
9960: 63 6f 6e 66 69 67 75 72 65 5c 66 52 20 73 74 64 configure\fR std
9970: 6f 75 74 20 2d 62 75 66 66 65 72 69 6e 67 20 6e out -buffering n
9980: 6f 6e 65 0a 2e 43 45 0a 2e 50 50 0a 49 6e 20 74 one..CE..PP.In t
9990: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 he following exa
99a0: 6d 70 6c 65 20 61 20 66 69 6c 65 20 69 73 20 6f mple a file is o
99b0: 70 65 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 pened using the
99c0: 65 6e 63 6f 64 69 6e 67 20 43 50 31 32 35 32 2c encoding CP1252,
99d0: 20 77 68 69 63 68 20 69 73 0a 63 6f 6d 6d 6f 6e which is.common
99e0: 20 6f 6e 20 57 69 6e 64 6f 77 73 2c 20 73 65 61 on Windows, sea
99f0: 72 63 68 65 73 20 66 6f 72 20 61 20 73 74 72 69 rches for a stri
9a00: 6e 67 2c 20 72 65 77 72 69 74 65 73 20 74 68 61 ng, rewrites tha
9a10: 74 20 70 61 72 74 2c 20 61 6e 64 20 74 72 75 6e t part, and trun
9a20: 63 61 74 65 73 20 74 68 65 0a 66 69 6c 65 20 74 cates the.file t
9a30: 77 6f 20 6c 69 6e 65 73 20 6c 61 74 65 72 2e 0a wo lines later..
9a40: 2e 50 50 0a 2e 43 53 0a 73 65 74 20 66 20 5b 6f .PP..CS.set f [o
9a50: 70 65 6e 20 73 6f 6d 65 66 69 6c 65 2e 74 78 74 pen somefile.txt
9a60: 20 72 2b 5d 0a 5c 66 42 63 68 61 6e 20 63 6f 6e r+].\fBchan con
9a70: 66 69 67 75 72 65 5c 66 52 20 24 66 20 2d 65 6e figure\fR $f -en
9a80: 63 6f 64 69 6e 67 20 63 70 31 32 35 32 0a 73 65 coding cp1252.se
9a90: 74 20 6f 66 66 73 65 74 20 30 0a 0a 5c 66 49 23 t offset 0..\fI#
9aa0: 20 53 65 61 72 63 68 20 66 6f 72 20 73 74 72 69 Search for stri
9ab0: 6e 67 20 22 46 4f 4f 42 41 52 22 20 69 6e 20 74 ng "FOOBAR" in t
9ac0: 68 65 20 66 69 6c 65 5c 66 52 0a 77 68 69 6c 65 he file\fR.while
9ad0: 20 7b 5b 5c 66 42 63 68 61 6e 20 67 65 74 73 5c {[\fBchan gets\
9ae0: 66 52 20 24 66 20 6c 69 6e 65 5d 20 3e 3d 20 30 fR $f line] >= 0
9af0: 7d 20 7b 0a 20 20 20 20 73 65 74 20 69 64 78 20 } {. set idx
9b00: 5b 73 74 72 69 6e 67 20 66 69 72 73 74 20 46 4f [string first FO
9b10: 4f 42 41 52 20 24 6c 69 6e 65 5d 0a 20 20 20 20 OBAR $line].
9b20: 69 66 20 7b 24 69 64 78 20 3e 3d 20 30 7d 20 7b if {$idx >= 0} {
9b30: 0a 20 20 20 20 20 20 20 20 5c 66 49 23 20 46 6f . \fI# Fo
9b40: 75 6e 64 20 69 74 3b 20 72 65 77 72 69 74 65 20 und it; rewrite
9b50: 6c 69 6e 65 5c 66 52 0a 0a 20 20 20 20 20 20 20 line\fR..
9b60: 20 5c 66 42 63 68 61 6e 20 73 65 65 6b 5c 66 52 \fBchan seek\fR
9b70: 20 24 66 20 5b 65 78 70 72 20 7b 24 6f 66 66 73 $f [expr {$offs
9b80: 65 74 20 2b 20 24 69 64 78 7d 5d 0a 20 20 20 20 et + $idx}].
9b90: 20 20 20 20 5c 66 42 63 68 61 6e 20 70 75 74 73 \fBchan puts
9ba0: 5c 66 52 20 2d 6e 6f 6e 65 77 6c 69 6e 65 20 24 \fR -nonewline $
9bb0: 66 20 42 41 52 46 4f 4f 0a 0a 20 20 20 20 20 20 f BARFOO..
9bc0: 20 20 5c 66 49 23 20 53 6b 69 70 20 74 6f 20 65 \fI# Skip to e
9bd0: 6e 64 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 nd of following
9be0: 6c 69 6e 65 2c 20 61 6e 64 20 74 72 75 6e 63 61 line, and trunca
9bf0: 74 65 5c 66 52 0a 20 20 20 20 20 20 20 20 5c 66 te\fR. \f
9c00: 42 63 68 61 6e 20 67 65 74 73 5c 66 52 20 24 66 Bchan gets\fR $f
9c10: 0a 20 20 20 20 20 20 20 20 5c 66 42 63 68 61 6e . \fBchan
9c20: 20 67 65 74 73 5c 66 52 20 24 66 0a 20 20 20 20 gets\fR $f.
9c30: 20 20 20 20 5c 66 42 63 68 61 6e 20 74 72 75 6e \fBchan trun
9c40: 63 61 74 65 5c 66 52 20 24 66 0a 0a 20 20 20 20 cate\fR $f..
9c50: 20 20 20 20 5c 66 49 23 20 53 74 6f 70 20 73 65 \fI# Stop se
9c60: 61 72 63 68 69 6e 67 20 74 68 65 20 66 69 6c 65 arching the file
9c70: 20 6e 6f 77 5c 66 52 0a 20 20 20 20 20 20 20 20 now\fR.
9c80: 62 72 65 61 6b 0a 20 20 20 20 7d 0a 0a 20 20 20 break. }..
9c90: 20 5c 66 49 23 20 53 61 76 65 20 6f 66 66 73 65 \fI# Save offse
9ca0: 74 20 6f 66 20 73 74 61 72 74 20 6f 66 20 6e 65 t of start of ne
9cb0: 78 74 20 6c 69 6e 65 20 66 6f 72 20 6c 61 74 65 xt line for late
9cc0: 72 5c 66 52 0a 20 20 20 20 73 65 74 20 6f 66 66 r\fR. set off
9cd0: 73 65 74 20 5b 5c 66 42 63 68 61 6e 20 74 65 6c set [\fBchan tel
9ce0: 6c 5c 66 52 20 24 66 5d 0a 7d 0a 5c 66 42 63 68 l\fR $f].}.\fBch
9cf0: 61 6e 20 63 6c 6f 73 65 5c 66 52 20 24 66 0a 2e an close\fR $f..
9d00: 43 45 0a 2e 50 50 0a 54 68 69 73 20 65 78 61 6d CE..PP.This exam
9d10: 70 6c 65 20 69 6c 6c 75 73 74 72 61 74 65 73 20 ple illustrates
9d20: 66 6c 75 73 68 69 6e 67 20 6f 66 20 61 20 63 68 flushing of a ch
9d30: 61 6e 6e 65 6c 2e 20 54 68 65 20 75 73 65 72 20 annel. The user
9d40: 69 73 0a 70 72 6f 6d 70 74 65 64 20 66 6f 72 20 is.prompted for
9d50: 73 6f 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e some information
9d60: 2e 20 42 65 63 61 75 73 65 20 74 68 65 20 73 74 . Because the st
9d70: 61 6e 64 61 72 64 20 69 6e 70 75 74 20 63 68 61 andard input cha
9d80: 6e 6e 65 6c 0a 69 73 20 6c 69 6e 65 20 62 75 66 nnel.is line buf
9d90: 66 65 72 65 64 2c 20 69 74 20 6d 75 73 74 20 62 fered, it must b
9da0: 65 20 66 6c 75 73 68 65 64 20 66 6f 72 20 74 68 e flushed for th
9db0: 65 20 75 73 65 72 20 74 6f 20 73 65 65 20 74 68 e user to see th
9dc0: 65 20 70 72 6f 6d 70 74 2e 0a 2e 50 50 0a 2e 43 e prompt...PP..C
9dd0: 53 0a 63 68 61 6e 20 70 75 74 73 20 2d 6e 6f 6e S.chan puts -non
9de0: 65 77 6c 69 6e 65 20 22 50 6c 65 61 73 65 20 74 ewline "Please t
9df0: 79 70 65 20 79 6f 75 72 20 6e 61 6d 65 3a 20 22 ype your name: "
9e00: 0a 5c 66 42 63 68 61 6e 20 66 6c 75 73 68 5c 66 .\fBchan flush\f
9e10: 52 20 73 74 64 6f 75 74 0a 63 68 61 6e 20 67 65 R stdout.chan ge
9e20: 74 73 20 73 74 64 69 6e 20 6e 61 6d 65 0a 63 68 ts stdin name.ch
9e30: 61 6e 20 70 75 74 73 20 22 48 65 6c 6c 6f 20 74 an puts "Hello t
9e40: 68 65 72 65 2c 20 24 6e 61 6d 65 21 22 0a 2e 43 here, $name!"..C
9e50: 45 0a 2e 50 50 0a 54 68 69 73 20 65 78 61 6d 70 E..PP.This examp
9e60: 6c 65 20 72 65 61 64 73 20 61 20 66 69 6c 65 20 le reads a file
9e70: 6f 6e 65 20 6c 69 6e 65 20 61 74 20 61 20 74 69 one line at a ti
9e80: 6d 65 20 61 6e 64 20 70 72 69 6e 74 73 20 69 74 me and prints it
9e90: 20 6f 75 74 20 77 69 74 68 0a 74 68 65 20 63 75 out with.the cu
9ea0: 72 72 65 6e 74 20 6c 69 6e 65 20 6e 75 6d 62 65 rrent line numbe
9eb0: 72 20 61 74 74 61 63 68 65 64 20 74 6f 20 74 68 r attached to th
9ec0: 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 20 e start of each
9ed0: 6c 69 6e 65 2e 0a 2e 50 50 0a 2e 43 53 0a 73 65 line...PP..CS.se
9ee0: 74 20 63 68 61 6e 20 5b 6f 70 65 6e 20 22 73 6f t chan [open "so
9ef0: 6d 65 2e 66 69 6c 65 2e 74 78 74 22 5d 0a 73 65 me.file.txt"].se
9f00: 74 20 6c 69 6e 65 4e 75 6d 62 65 72 20 30 0a 77 t lineNumber 0.w
9f10: 68 69 6c 65 20 7b 5b 5c 66 42 63 68 61 6e 20 67 hile {[\fBchan g
9f20: 65 74 73 5c 66 52 20 24 63 68 61 6e 20 6c 69 6e ets\fR $chan lin
9f30: 65 5d 20 3e 3d 20 30 7d 20 7b 0a 20 20 20 20 63 e] >= 0} {. c
9f40: 68 61 6e 20 70 75 74 73 20 22 5b 69 6e 63 72 20 han puts "[incr
9f50: 6c 69 6e 65 4e 75 6d 62 65 72 5d 3a 20 24 6c 69 lineNumber]: $li
9f60: 6e 65 22 0a 7d 0a 63 68 61 6e 20 63 6c 6f 73 65 ne".}.chan close
9f70: 20 24 63 68 61 6e 0a 2e 43 45 0a 2e 50 50 0a 49 $chan..CE..PP.I
9f80: 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 n this example i
9f90: 6c 6c 75 73 74 72 61 74 69 6e 67 20 65 76 65 6e llustrating even
9fa0: 74 20 64 72 69 76 65 6e 20 72 65 61 64 73 2c 0a t driven reads,.
9fb0: 5c 66 42 47 65 74 44 61 74 61 5c 66 52 20 77 69 \fBGetData\fR wi
9fc0: 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 77 69 74 ll be called wit
9fd0: 68 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 61 73 h the channel as
9fe0: 20 61 6e 0a 61 72 67 75 6d 65 6e 74 20 77 68 65 an.argument whe
9ff0: 6e 65 76 65 72 20 24 63 68 61 6e 20 62 65 63 6f never $chan beco
a000: 6d 65 73 20 72 65 61 64 61 62 6c 65 2e 20 54 68 mes readable. Th
a010: 65 20 5c 66 42 72 65 61 64 5c 66 52 20 63 61 6c e \fBread\fR cal
a020: 6c 20 77 69 6c 6c 0a 72 65 61 64 20 77 68 61 74 l will.read what
a030: 65 76 65 72 20 62 69 6e 61 72 79 20 64 61 74 61 ever binary data
a040: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 61 76 is currently av
a050: 61 69 6c 61 62 6c 65 20 77 69 74 68 6f 75 74 20 ailable without
a060: 62 6c 6f 63 6b 69 6e 67 2e 0a 48 65 72 65 20 74 blocking..Here t
a070: 68 65 20 63 68 61 6e 6e 65 6c 20 68 61 73 20 74 he channel has t
a080: 68 65 20 66 69 6c 65 65 76 65 6e 74 20 72 65 6d he fileevent rem
a090: 6f 76 65 64 20 77 68 65 6e 20 61 6e 20 65 6e 64 oved when an end
a0a0: 20 6f 66 20 66 69 6c 65 0a 6f 63 63 75 72 73 20 of file.occurs
a0b0: 74 6f 20 61 76 6f 69 64 20 62 65 69 6e 67 20 63 to avoid being c
a0c0: 6f 6e 74 69 6e 75 61 6c 6c 79 20 63 61 6c 6c 65 ontinually calle
a0d0: 64 20 28 73 65 65 20 61 62 6f 76 65 29 2e 20 41 d (see above). A
a0e0: 6c 74 65 72 6e 61 74 69 76 65 6c 79 0a 74 68 65 lternatively.the
a0f0: 20 63 68 61 6e 6e 65 6c 20 6d 61 79 20 62 65 20 channel may be
a100: 63 6c 6f 73 65 64 20 6f 6e 20 74 68 69 73 20 63 closed on this c
a110: 6f 6e 64 69 74 69 6f 6e 2e 0a 2e 50 50 0a 2e 43 ondition...PP..C
a120: 53 0a 70 72 6f 63 20 47 65 74 44 61 74 61 20 7b S.proc GetData {
a130: 63 68 61 6e 7d 20 7b 0a 20 20 20 20 73 65 74 20 chan} {. set
a140: 64 61 74 61 20 5b 63 68 61 6e 20 72 65 61 64 20 data [chan read
a150: 24 63 68 61 6e 5d 0a 20 20 20 20 63 68 61 6e 20 $chan]. chan
a160: 70 75 74 73 20 22 5b 73 74 72 69 6e 67 20 6c 65 puts "[string le
a170: 6e 67 74 68 20 24 64 61 74 61 5d 20 24 64 61 74 ngth $data] $dat
a180: 61 22 0a 20 20 20 20 69 66 20 7b 5b 63 68 61 6e a". if {[chan
a190: 20 65 6f 66 20 24 63 68 61 6e 5d 7d 20 7b 0a 20 eof $chan]} {.
a1a0: 20 20 20 20 20 20 20 63 68 61 6e 20 65 76 65 6e chan even
a1b0: 74 20 24 63 68 61 6e 20 72 65 61 64 61 62 6c 65 t $chan readable
a1c0: 20 7b 7d 0a 20 20 20 20 7d 0a 7d 0a 0a 63 68 61 {}. }.}..cha
a1d0: 6e 20 63 6f 6e 66 69 67 75 72 65 20 24 63 68 61 n configure $cha
a1e0: 6e 20 2d 62 6c 6f 63 6b 69 6e 67 20 30 20 2d 65 n -blocking 0 -e
a1f0: 6e 63 6f 64 69 6e 67 20 62 69 6e 61 72 79 0a 5c ncoding binary.\
a200: 66 42 63 68 61 6e 20 65 76 65 6e 74 5c 66 52 20 fBchan event\fR
a210: 24 63 68 61 6e 20 72 65 61 64 61 62 6c 65 20 5b $chan readable [
a220: 6c 69 73 74 20 47 65 74 44 61 74 61 20 24 63 68 list GetData $ch
a230: 61 6e 5d 0a 2e 43 45 0a 2e 50 50 0a 54 68 65 20 an]..CE..PP.The
a240: 6e 65 78 74 20 65 78 61 6d 70 6c 65 20 69 73 20 next example is
a250: 73 69 6d 69 6c 61 72 20 62 75 74 20 75 73 65 73 similar but uses
a260: 20 5c 66 42 63 68 61 6e 20 67 65 74 73 5c 66 52 \fBchan gets\fR
a270: 20 74 6f 20 72 65 61 64 0a 6c 69 6e 65 2d 6f 72 to read.line-or
a280: 69 65 6e 74 65 64 20 64 61 74 61 2e 0a 2e 50 50 iented data...PP
a290: 0a 2e 43 53 0a 70 72 6f 63 20 47 65 74 44 61 74 ..CS.proc GetDat
a2a0: 61 20 7b 63 68 61 6e 7d 20 7b 0a 20 20 20 20 69 a {chan} {. i
a2b0: 66 20 7b 5b 63 68 61 6e 20 67 65 74 73 20 24 63 f {[chan gets $c
a2c0: 68 61 6e 20 6c 69 6e 65 5d 20 3e 3d 20 30 7d 20 han line] >= 0}
a2d0: 7b 0a 20 20 20 20 20 20 20 20 63 68 61 6e 20 70 {. chan p
a2e0: 75 74 73 20 24 6c 69 6e 65 0a 20 20 20 20 7d 0a uts $line. }.
a2f0: 20 20 20 20 69 66 20 7b 5b 63 68 61 6e 20 65 6f if {[chan eo
a300: 66 20 24 63 68 61 6e 5d 7d 20 7b 0a 20 20 20 20 f $chan]} {.
a310: 20 20 20 20 63 68 61 6e 20 63 6c 6f 73 65 20 24 chan close $
a320: 63 68 61 6e 0a 20 20 20 20 7d 0a 7d 0a 0a 63 68 chan. }.}..ch
a330: 61 6e 20 63 6f 6e 66 69 67 75 72 65 20 24 63 68 an configure $ch
a340: 61 6e 20 2d 62 6c 6f 63 6b 69 6e 67 20 30 20 2d an -blocking 0 -
a350: 62 75 66 66 65 72 69 6e 67 20 6c 69 6e 65 20 2d buffering line -
a360: 74 72 61 6e 73 6c 61 74 69 6f 6e 20 63 72 6c 66 translation crlf
a370: 0a 5c 66 42 63 68 61 6e 20 65 76 65 6e 74 5c 66 .\fBchan event\f
a380: 52 20 24 63 68 61 6e 20 72 65 61 64 61 62 6c 65 R $chan readable
a390: 20 5b 6c 69 73 74 20 47 65 74 44 61 74 61 20 24 [list GetData $
a3a0: 63 68 61 6e 5d 0a 2e 43 45 0a 2e 50 50 0a 41 20 chan]..CE..PP.A
a3b0: 6e 65 74 77 6f 72 6b 20 73 65 72 76 65 72 20 74 network server t
a3c0: 68 61 74 20 65 63 68 6f 65 73 20 69 74 73 20 69 hat echoes its i
a3d0: 6e 70 75 74 20 6c 69 6e 65 2d 62 79 2d 6c 69 6e nput line-by-lin
a3e0: 65 20 77 69 74 68 6f 75 74 0a 70 72 65 76 65 6e e without.preven
a3f0: 74 69 6e 67 20 73 65 72 76 69 63 69 6e 67 20 6f ting servicing o
a400: 66 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 f other connecti
a410: 6f 6e 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ons at the same
a420: 74 69 6d 65 3a 0a 2e 50 50 0a 2e 43 53 0a 23 20 time:..PP..CS.#
a430: 54 68 69 73 20 69 73 20 61 20 76 65 72 79 20 73 This is a very s
a440: 69 6d 70 6c 65 20 6c 6f 67 67 65 72 2e 2e 2e 0a imple logger....
a450: 70 72 6f 63 20 6c 6f 67 20 7b 6d 65 73 73 61 67 proc log {messag
a460: 65 7d 20 7b 0a 20 20 20 20 5c 66 42 63 68 61 6e e} {. \fBchan
a470: 20 70 75 74 73 5c 66 52 20 73 74 64 6f 75 74 20 puts\fR stdout
a480: 24 6d 65 73 73 61 67 65 0a 7d 0a 0a 23 20 54 68 $message.}..# Th
a490: 69 73 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 is is called whe
a4a0: 6e 65 76 65 72 20 61 20 6e 65 77 20 63 6c 69 65 never a new clie
a4b0: 6e 74 20 63 6f 6e 6e 65 63 74 73 20 74 6f 20 74 nt connects to t
a4c0: 68 65 20 73 65 72 76 65 72 0a 70 72 6f 63 20 63 he server.proc c
a4d0: 6f 6e 6e 65 63 74 20 7b 63 68 61 6e 20 68 6f 73 onnect {chan hos
a4e0: 74 20 70 6f 72 74 7d 20 7b 0a 20 20 20 20 73 65 t port} {. se
a4f0: 74 20 63 6c 69 65 6e 74 4e 61 6d 65 20 5b 66 6f t clientName [fo
a500: 72 6d 61 74 20 3c 25 73 3a 25 64 3e 20 24 68 6f rmat <%s:%d> $ho
a510: 73 74 20 24 70 6f 72 74 5d 0a 20 20 20 20 6c 6f st $port]. lo
a520: 67 20 22 63 6f 6e 6e 65 63 74 69 6f 6e 20 66 72 g "connection fr
a530: 6f 6d 20 24 63 6c 69 65 6e 74 4e 61 6d 65 22 0a om $clientName".
a540: 20 20 20 20 5c 66 42 63 68 61 6e 20 63 6f 6e 66 \fBchan conf
a550: 69 67 75 72 65 5c 66 52 20 24 63 68 61 6e 20 2d igure\fR $chan -
a560: 62 6c 6f 63 6b 69 6e 67 20 30 20 2d 62 75 66 66 blocking 0 -buff
a570: 65 72 69 6e 67 20 6c 69 6e 65 0a 20 20 20 20 5c ering line. \
a580: 66 42 63 68 61 6e 20 65 76 65 6e 74 5c 66 52 20 fBchan event\fR
a590: 24 63 68 61 6e 20 72 65 61 64 61 62 6c 65 20 5b $chan readable [
a5a0: 6c 69 73 74 20 65 63 68 6f 4c 69 6e 65 20 24 63 list echoLine $c
a5b0: 68 61 6e 20 24 63 6c 69 65 6e 74 4e 61 6d 65 5d han $clientName]
a5c0: 0a 7d 0a 0a 23 20 54 68 69 73 20 69 73 20 63 61 .}..# This is ca
a5d0: 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 65 69 lled whenever ei
a5e0: 74 68 65 72 20 61 74 20 6c 65 61 73 74 20 6f 6e ther at least on
a5f0: 65 20 62 79 74 65 20 6f 66 20 69 6e 70 75 74 0a e byte of input.
a600: 23 20 64 61 74 61 20 69 73 20 61 76 61 69 6c 61 # data is availa
a610: 62 6c 65 2c 20 6f 72 20 74 68 65 20 63 68 61 6e ble, or the chan
a620: 6e 65 6c 20 77 61 73 20 63 6c 6f 73 65 64 20 62 nel was closed b
a630: 79 20 74 68 65 20 63 6c 69 65 6e 74 2e 0a 70 72 y the client..pr
a640: 6f 63 20 65 63 68 6f 4c 69 6e 65 20 7b 63 68 61 oc echoLine {cha
a650: 6e 20 63 6c 69 65 6e 74 4e 61 6d 65 7d 20 7b 0a n clientName} {.
a660: 20 20 20 20 5c 66 42 63 68 61 6e 20 67 65 74 73 \fBchan gets
a670: 5c 66 52 20 24 63 68 61 6e 20 6c 69 6e 65 0a 20 \fR $chan line.
a680: 20 20 20 69 66 20 7b 5b 5c 66 42 63 68 61 6e 20 if {[\fBchan
a690: 65 6f 66 5c 66 52 20 24 63 68 61 6e 5d 7d 20 7b eof\fR $chan]} {
a6a0: 0a 20 20 20 20 20 20 20 20 6c 6f 67 20 22 66 69 . log "fi
a6b0: 6e 69 73 68 69 6e 67 20 63 6f 6e 6e 65 63 74 69 nishing connecti
a6c0: 6f 6e 20 66 72 6f 6d 20 24 63 6c 69 65 6e 74 4e on from $clientN
a6d0: 61 6d 65 22 0a 20 20 20 20 20 20 20 20 5c 66 42 ame". \fB
a6e0: 63 68 61 6e 20 63 6c 6f 73 65 5c 66 52 20 24 63 chan close\fR $c
a6f0: 68 61 6e 0a 20 20 20 20 7d 20 65 6c 73 65 69 66 han. } elseif
a700: 20 7b 21 5b 5c 66 42 63 68 61 6e 20 62 6c 6f 63 {![\fBchan bloc
a710: 6b 65 64 5c 66 52 20 24 63 68 61 6e 5d 7d 20 7b ked\fR $chan]} {
a720: 0a 20 20 20 20 20 20 20 20 23 20 44 69 64 6e 27 . # Didn'
a730: 74 20 62 6c 6f 63 6b 20 77 61 69 74 69 6e 67 20 t block waiting
a740: 66 6f 72 20 65 6e 64 2d 6f 66 2d 6c 69 6e 65 0a for end-of-line.
a750: 20 20 20 20 20 20 20 20 6c 6f 67 20 22 24 63 6c log "$cl
a760: 69 65 6e 74 4e 61 6d 65 20 2d 20 24 6c 69 6e 65 ientName - $line
a770: 22 0a 20 20 20 20 20 20 20 20 5c 66 42 63 68 61 ". \fBcha
a780: 6e 20 70 75 74 73 5c 66 52 20 24 63 68 61 6e 20 n puts\fR $chan
a790: 24 6c 69 6e 65 0a 20 20 20 20 7d 0a 7d 0a 0a 23 $line. }.}..#
a7a0: 20 43 72 65 61 74 65 20 74 68 65 20 73 65 72 76 Create the serv
a7b0: 65 72 20 73 6f 63 6b 65 74 20 61 6e 64 20 65 6e er socket and en
a7c0: 74 65 72 20 74 68 65 20 65 76 65 6e 74 2d 6c 6f ter the event-lo
a7d0: 6f 70 20 74 6f 20 77 61 69 74 0a 23 20 66 6f 72 op to wait.# for
a7e0: 20 69 6e 63 6f 6d 69 6e 67 20 63 6f 6e 6e 65 63 incoming connec
a7f0: 74 69 6f 6e 73 2e 2e 2e 0a 73 6f 63 6b 65 74 20 tions....socket
a800: 2d 73 65 72 76 65 72 20 63 6f 6e 6e 65 63 74 20 -server connect
a810: 31 32 33 34 35 0a 76 77 61 69 74 20 66 6f 72 65 12345.vwait fore
a820: 76 65 72 0a 2e 43 45 0a 2e 50 50 0a 54 68 65 20 ver..CE..PP.The
a830: 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c following exampl
a840: 65 20 72 65 61 64 73 20 61 20 50 50 4d 2d 66 6f e reads a PPM-fo
a850: 72 6d 61 74 20 69 6d 61 67 65 20 66 72 6f 6d 20 rmat image from
a860: 61 20 66 69 6c 65 0a 63 6f 6d 62 69 6e 69 6e 67 a file.combining
a870: 20 41 53 43 49 49 20 61 6e 64 20 62 69 6e 61 72 ASCII and binar
a880: 79 20 63 6f 6e 74 65 6e 74 2e 0a 2e 50 50 0a 2e y content...PP..
a890: 43 53 0a 23 20 4f 70 65 6e 20 74 68 65 20 66 69 CS.# Open the fi
a8a0: 6c 65 20 61 6e 64 20 70 75 74 20 69 74 20 69 6e le and put it in
a8b0: 74 6f 20 55 6e 69 78 20 41 53 43 49 49 20 6d 6f to Unix ASCII mo
a8c0: 64 65 0a 73 65 74 20 66 20 5b 6f 70 65 6e 20 74 de.set f [open t
a8d0: 65 61 70 6f 74 2e 70 70 6d 5d 0a 5c 66 42 63 68 eapot.ppm].\fBch
a8e0: 61 6e 20 63 6f 6e 66 69 67 75 72 65 5c 66 52 20 an configure\fR
a8f0: 24 66 20 2d 65 6e 63 6f 64 69 6e 67 20 61 73 63 $f -encoding asc
a900: 69 69 20 2d 74 72 61 6e 73 6c 61 74 69 6f 6e 20 ii -translation
a910: 6c 66 0a 0a 23 20 47 65 74 20 74 68 65 20 68 65 lf..# Get the he
a920: 61 64 65 72 0a 69 66 20 7b 5b 63 68 61 6e 20 67 ader.if {[chan g
a930: 65 74 73 20 24 66 5d 20 6e 65 20 22 50 36 22 7d ets $f] ne "P6"}
a940: 20 7b 0a 20 20 20 20 65 72 72 6f 72 20 22 6e 6f {. error "no
a950: 74 20 61 20 72 61 77 5c 2d 62 69 74 73 20 50 50 t a raw\-bits PP
a960: 4d 22 0a 7d 0a 0a 23 20 52 65 61 64 20 6c 69 6e M".}..# Read lin
a970: 65 73 20 75 6e 74 69 6c 20 77 65 20 68 61 76 65 es until we have
a980: 20 67 6f 74 20 6e 6f 6e 2d 63 6f 6d 6d 65 6e 74 got non-comment
a990: 20 6c 69 6e 65 73 0a 23 20 74 68 61 74 20 73 75 lines.# that su
a9a0: 70 70 6c 79 20 75 73 20 77 69 74 68 20 74 68 72 pply us with thr
a9b0: 65 65 20 64 65 63 69 6d 61 6c 20 76 61 6c 75 65 ee decimal value
a9c0: 73 2e 0a 73 65 74 20 77 6f 72 64 73 20 7b 7d 0a s..set words {}.
a9d0: 77 68 69 6c 65 20 7b 5b 6c 6c 65 6e 67 74 68 20 while {[llength
a9e0: 24 77 6f 72 64 73 5d 20 3c 20 33 7d 20 7b 0a 20 $words] < 3} {.
a9f0: 20 20 20 63 68 61 6e 20 67 65 74 73 20 24 66 20 chan gets $f
aa00: 6c 69 6e 65 0a 20 20 20 20 69 66 20 7b 5b 73 74 line. if {[st
aa10: 72 69 6e 67 20 6d 61 74 63 68 20 22 23 2a 22 20 ring match "#*"
aa20: 24 6c 69 6e 65 5d 7d 20 63 6f 6e 74 69 6e 75 65 $line]} continue
aa30: 0a 20 20 20 20 6c 61 70 70 65 6e 64 20 77 6f 72 . lappend wor
aa40: 64 73 20 7b 2a 7d 5b 6a 6f 69 6e 20 5b 73 63 61 ds {*}[join [sca
aa50: 6e 20 24 6c 69 6e 65 20 25 64 25 64 25 64 5d 5d n $line %d%d%d]]
aa60: 0a 7d 0a 0a 23 20 54 68 6f 73 65 20 77 6f 72 64 .}..# Those word
aa70: 73 20 73 75 70 70 6c 79 20 74 68 65 20 73 69 7a s supply the siz
aa80: 65 20 6f 66 20 74 68 65 20 69 6d 61 67 65 20 61 e of the image a
aa90: 6e 64 20 69 74 73 0a 23 20 6f 76 65 72 61 6c 6c nd its.# overall
aaa0: 20 64 65 70 74 68 20 70 65 72 20 63 68 61 6e 6e depth per chann
aab0: 65 6c 2e 20 41 73 73 69 67 6e 20 74 6f 20 76 61 el. Assign to va
aac0: 72 69 61 62 6c 65 73 2e 0a 6c 61 73 73 69 67 6e riables..lassign
aad0: 20 24 77 6f 72 64 73 20 78 53 69 7a 65 20 79 53 $words xSize yS
aae0: 69 7a 65 20 64 65 70 74 68 0a 0a 23 20 4e 6f 77 ize depth..# Now
aaf0: 20 73 77 69 74 63 68 20 74 6f 20 62 69 6e 61 72 switch to binar
ab00: 79 20 6d 6f 64 65 20 74 6f 20 70 75 6c 6c 20 69 y mode to pull i
ab10: 6e 20 74 68 65 20 64 61 74 61 2c 0a 23 20 6f 6e n the data,.# on
ab20: 65 20 62 79 74 65 20 70 65 72 20 63 68 61 6e 6e e byte per chann
ab30: 65 6c 20 28 72 65 64 2c 67 72 65 65 6e 2c 62 6c el (red,green,bl
ab40: 75 65 29 20 70 65 72 20 70 69 78 65 6c 2e 0a 5c ue) per pixel..\
ab50: 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 75 72 65 fBchan configure
ab60: 5c 66 52 20 24 66 20 2d 74 72 61 6e 73 6c 61 74 \fR $f -translat
ab70: 69 6f 6e 20 62 69 6e 61 72 79 0a 73 65 74 20 6e ion binary.set n
ab80: 75 6d 44 61 74 61 42 79 74 65 73 20 5b 65 78 70 umDataBytes [exp
ab90: 72 20 7b 33 20 2a 20 24 78 53 69 7a 65 20 2a 20 r {3 * $xSize *
aba0: 24 79 53 69 7a 65 7d 5d 0a 73 65 74 20 64 61 74 $ySize}].set dat
abb0: 61 20 5b 63 68 61 6e 20 72 65 61 64 20 24 66 20 a [chan read $f
abc0: 24 6e 75 6d 44 61 74 61 42 79 74 65 73 5d 0a 0a $numDataBytes]..
abd0: 63 6c 6f 73 65 20 24 66 0a 2e 43 45 0a 2e 53 53 close $f..CE..SS
abe0: 20 22 46 49 4c 45 20 53 45 45 4b 20 45 58 41 4d "FILE SEEK EXAM
abf0: 50 4c 45 53 22 0a 2e 50 50 0a 52 65 61 64 20 61 PLES"..PP.Read a
ac00: 20 66 69 6c 65 20 74 77 69 63 65 3a 0a 2e 50 50 file twice:..PP
ac10: 0a 2e 43 53 0a 73 65 74 20 66 20 5b 6f 70 65 6e ..CS.set f [open
ac20: 20 66 69 6c 65 2e 74 78 74 5d 0a 73 65 74 20 64 file.txt].set d
ac30: 61 74 61 31 20 5b 63 68 61 6e 20 72 65 61 64 20 ata1 [chan read
ac40: 24 66 5d 0a 5c 66 42 63 68 61 6e 20 73 65 65 6b $f].\fBchan seek
ac50: 5c 66 52 20 24 66 20 30 0a 73 65 74 20 64 61 74 \fR $f 0.set dat
ac60: 61 32 20 5b 63 68 61 6e 20 72 65 61 64 20 24 66 a2 [chan read $f
ac70: 5d 0a 63 68 61 6e 20 63 6c 6f 73 65 20 24 66 0a ].chan close $f.
ac80: 23 20 24 64 61 74 61 31 20 65 71 20 24 64 61 74 # $data1 eq $dat
ac90: 61 32 20 69 66 20 74 68 65 20 66 69 6c 65 20 77 a2 if the file w
aca0: 61 73 6e 27 74 20 75 70 64 61 74 65 64 0a 2e 43 asn't updated..C
acb0: 45 0a 2e 50 50 0a 52 65 61 64 20 74 68 65 20 6c E..PP.Read the l
acc0: 61 73 74 20 31 30 20 62 79 74 65 73 20 66 72 6f ast 10 bytes fro
acd0: 6d 20 61 20 66 69 6c 65 3a 0a 2e 50 50 0a 2e 43 m a file:..PP..C
ace0: 53 0a 73 65 74 20 66 20 5b 6f 70 65 6e 20 66 69 S.set f [open fi
acf0: 6c 65 2e 64 61 74 61 5d 0a 23 20 54 68 69 73 20 le.data].# This
ad00: 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f is guaranteed to
ad10: 20 77 6f 72 6b 20 77 69 74 68 20 62 69 6e 61 72 work with binar
ad20: 79 20 64 61 74 61 20 62 75 74 0a 23 20 6d 61 79 y data but.# may
ad30: 20 66 61 69 6c 20 77 69 74 68 20 6f 74 68 65 72 fail with other
ad40: 20 65 6e 63 6f 64 69 6e 67 73 2e 2e 2e 0a 63 68 encodings....ch
ad50: 61 6e 20 63 6f 6e 66 69 67 75 72 65 20 24 66 20 an configure $f
ad60: 2d 74 72 61 6e 73 6c 61 74 69 6f 6e 20 62 69 6e -translation bin
ad70: 61 72 79 0a 5c 66 42 63 68 61 6e 20 73 65 65 6b ary.\fBchan seek
ad80: 5c 66 52 20 24 66 20 2d 31 30 20 65 6e 64 0a 73 \fR $f -10 end.s
ad90: 65 74 20 64 61 74 61 20 5b 63 68 61 6e 20 72 65 et data [chan re
ada0: 61 64 20 24 66 20 31 30 5d 0a 63 68 61 6e 20 63 ad $f 10].chan c
adb0: 6c 6f 73 65 20 24 66 0a 2e 43 45 0a 2e 50 50 0a lose $f..CE..PP.
adc0: 52 65 61 64 20 61 20 6c 69 6e 65 20 66 72 6f 6d Read a line from
add0: 20 61 20 66 69 6c 65 20 63 68 61 6e 6e 65 6c 20 a file channel
ade0: 6f 6e 6c 79 20 69 66 20 69 74 20 73 74 61 72 74 only if it start
adf0: 73 20 77 69 74 68 20 5c 66 42 66 6f 6f 62 61 72 s with \fBfoobar
ae00: 5c 66 52 3a 0a 2e 50 50 0a 2e 43 53 0a 23 20 53 \fR:..PP..CS.# S
ae10: 61 76 65 20 74 68 65 20 6f 66 66 73 65 74 20 69 ave the offset i
ae20: 6e 20 63 61 73 65 20 77 65 20 6e 65 65 64 20 74 n case we need t
ae30: 6f 20 75 6e 64 6f 20 74 68 65 20 72 65 61 64 2e o undo the read.
ae40: 2e 2e 0a 73 65 74 20 6f 66 66 73 65 74 20 5b 5c ...set offset [\
ae50: 66 42 74 65 6c 6c 5c 66 52 20 24 63 68 61 6e 5d fBtell\fR $chan]
ae60: 0a 69 66 20 7b 5b 72 65 61 64 20 24 63 68 61 6e .if {[read $chan
ae70: 20 36 5d 20 65 71 20 22 66 6f 6f 62 61 72 22 7d 6] eq "foobar"}
ae80: 20 7b 0a 20 20 20 20 67 65 74 73 20 24 63 68 61 {. gets $cha
ae90: 6e 20 6c 69 6e 65 0a 7d 20 65 6c 73 65 20 7b 0a n line.} else {.
aea0: 20 20 20 20 73 65 74 20 6c 69 6e 65 20 7b 7d 0a set line {}.
aeb0: 20 20 20 20 23 20 55 6e 64 6f 20 74 68 65 20 72 # Undo the r
aec0: 65 61 64 2e 2e 2e 0a 20 20 20 20 73 65 65 6b 20 ead.... seek
aed0: 24 63 68 61 6e 20 24 6f 66 66 73 65 74 0a 7d 0a $chan $offset.}.
aee0: 2e 43 45 0a 2e 53 53 20 22 45 4e 43 4f 44 49 4e .CE..SS "ENCODIN
aef0: 47 20 45 52 52 4f 52 20 45 58 41 4d 50 4c 45 53 G ERROR EXAMPLES
af00: 22 0a 2e 50 50 0a 54 68 65 20 65 78 61 6d 70 6c "..PP.The exampl
af10: 65 20 62 65 6c 6f 77 20 69 6c 6c 75 73 74 72 61 e below illustra
af20: 74 65 73 20 68 61 6e 64 6c 69 6e 67 20 6f 66 20 tes handling of
af30: 61 6e 20 65 6e 63 6f 64 69 6e 67 20 65 72 72 6f an encoding erro
af40: 72 20 65 6e 63 6f 75 6e 74 65 72 65 64 0a 64 75 r encountered.du
af50: 72 69 6e 67 20 63 68 61 6e 6e 65 6c 20 69 6e 70 ring channel inp
af60: 75 74 2e 20 46 69 72 73 74 2c 20 63 72 65 61 74 ut. First, creat
af70: 69 6f 6e 20 6f 66 20 61 20 74 65 73 74 20 66 69 ion of a test fi
af80: 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 74 68 le containing.th
af90: 65 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 e invalid UTF-8
afa0: 73 65 71 75 65 6e 63 65 20 28 5c 66 42 41 20 5c sequence (\fBA \
afb0: 5c 78 43 33 20 42 5c 66 52 29 3a 0a 2e 50 50 0a \xC3 B\fR):..PP.
afc0: 2e 43 53 0a 25 20 73 65 74 20 66 20 5b 6f 70 65 .CS.% set f [ope
afd0: 6e 20 74 65 73 74 5f 41 5f 31 39 35 5f 42 2e 74 n test_A_195_B.t
afe0: 78 74 20 77 62 5d 3b 20 63 68 61 6e 20 70 75 74 xt wb]; chan put
aff0: 73 20 2d 6e 6f 6e 65 77 6c 69 6e 65 20 24 66 20 s -nonewline $f
b000: 41 5c 5c 78 43 33 42 3b 20 63 68 61 6e 20 63 6c A\\xC3B; chan cl
b010: 6f 73 65 20 24 66 0a 2e 43 45 0a 2e 50 50 0a 41 ose $f..CE..PP.A
b020: 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 n attempt to rea
b030: 64 20 74 68 65 20 66 69 6c 65 20 77 69 6c 6c 20 d the file will
b040: 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 65 6e 63 result in an enc
b050: 6f 64 69 6e 67 20 65 72 72 6f 72 20 77 68 69 63 oding error whic
b060: 68 20 69 73 0a 74 68 65 6e 20 69 6e 74 72 6f 73 h is.then intros
b070: 70 65 63 74 65 64 20 62 79 20 73 77 69 74 63 68 pected by switch
b080: 69 6e 67 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 ing the channel
b090: 74 6f 20 62 69 6e 61 72 79 20 6d 6f 64 65 2e 20 to binary mode.
b0a0: 4e 6f 74 65 20 69 6e 20 74 68 65 0a 65 78 61 6d Note in the.exam
b0b0: 70 6c 65 20 74 68 61 74 20 77 68 65 6e 20 74 68 ple that when th
b0c0: 65 20 65 72 72 6f 72 20 69 73 20 72 65 70 6f 72 e error is repor
b0d0: 74 65 64 20 74 68 65 20 66 69 6c 65 20 70 6f 73 ted the file pos
b0e0: 69 74 69 6f 6e 20 72 65 6d 61 69 6e 73 0a 75 6e ition remains.un
b0f0: 63 68 61 6e 67 65 64 20 73 6f 20 74 68 61 74 20 changed so that
b100: 74 68 65 20 5c 66 42 63 68 61 6e 20 67 65 74 73 the \fBchan gets
b110: 5c 66 52 20 64 75 72 69 6e 67 20 72 65 63 6f 76 \fR during recov
b120: 65 72 79 20 72 65 74 75 72 6e 73 20 74 68 65 0a ery returns the.
b130: 66 75 6c 6c 20 6c 69 6e 65 2e 0a 2e 50 50 0a 2e full line...PP..
b140: 43 53 0a 25 20 73 65 74 20 66 20 5b 6f 70 65 6e CS.% set f [open
b150: 20 74 65 73 74 5f 41 5f 31 39 35 5f 42 2e 74 78 test_A_195_B.tx
b160: 74 20 72 5d 0a 66 69 6c 65 33 38 34 62 36 61 38 t r].file384b6a8
b170: 0a 25 20 63 68 61 6e 20 63 6f 6e 66 69 67 75 72 .% chan configur
b180: 65 20 24 66 20 2d 65 6e 63 6f 64 69 6e 67 20 75 e $f -encoding u
b190: 74 66 2d 38 0a 25 20 63 61 74 63 68 20 7b 63 68 tf-8.% catch {ch
b1a0: 61 6e 20 67 65 74 73 20 24 66 7d 20 65 20 64 0a an gets $f} e d.
b1b0: 31 0a 25 20 73 65 74 20 64 0a 2d 63 6f 64 65 20 1.% set d.-code
b1c0: 31 20 2d 6c 65 76 65 6c 20 30 0a 2d 65 72 72 6f 1 -level 0.-erro
b1d0: 72 73 74 61 63 6b 20 7b 49 4e 4e 45 52 20 7b 69 rstack {INNER {i
b1e0: 6e 76 6f 6b 65 53 74 6b 31 20 67 65 74 73 20 66 nvokeStk1 gets f
b1f0: 69 6c 65 33 38 34 62 36 61 38 7d 7d 0a 2d 65 72 ile384b6a8}}.-er
b200: 72 6f 72 63 6f 64 65 20 7b 50 4f 53 49 58 20 45 rorcode {POSIX E
b210: 49 4c 53 45 51 20 7b 69 6e 76 61 6c 69 64 20 6f ILSEQ {invalid o
b220: 72 20 69 6e 63 6f 6d 70 6c 65 74 65 20 6d 75 6c r incomplete mul
b230: 74 69 62 79 74 65 20 6f 72 20 77 69 64 65 20 63 tibyte or wide c
b240: 68 61 72 61 63 74 65 72 7d 7d 0a 2d 65 72 72 6f haracter}}.-erro
b250: 72 69 6e 66 6f 20 7b 2e 2e 2e 7d 20 2d 65 72 72 rinfo {...} -err
b260: 6f 72 6c 69 6e 65 20 31 0a 25 20 63 68 61 6e 20 orline 1.% chan
b270: 74 65 6c 6c 20 24 66 0a 30 0a 25 20 63 68 61 6e tell $f.0.% chan
b280: 20 63 6f 6e 66 69 67 75 72 65 20 24 66 20 2d 65 configure $f -e
b290: 6e 63 6f 64 69 6e 67 20 62 69 6e 61 72 79 0a 25 ncoding binary.%
b2a0: 20 63 68 61 6e 20 67 65 74 73 20 24 66 0a 41 c3 chan gets $f.A�
b2b0: 83 42 0a 2e 43 45 0a 2e 50 50 0a 54 68 65 20 66 �B..CE..PP.The f
b2c0: 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65 ollowing example
b2d0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 is similar to t
b2e0: 68 65 20 61 62 6f 76 65 20 62 75 74 20 64 65 6d he above but dem
b2f0: 6f 6e 73 74 72 61 74 65 73 20 72 65 63 6f 76 65 onstrates recove
b300: 72 79 20 61 66 74 65 72 20 61 0a 62 6c 6f 63 6b ry after a.block
b310: 69 6e 67 20 72 65 61 64 2e 20 54 68 65 20 73 75 ing read. The su
b320: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 63 6f 64 ccessfully decod
b330: 65 64 20 64 61 74 61 20 22 41 22 20 69 73 20 72 ed data "A" is r
b340: 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 20 65 eturned in the e
b350: 72 72 6f 72 20 6f 70 74 69 6f 6e 73 0a 64 69 63 rror options.dic
b360: 74 69 6f 6e 61 72 79 20 6b 65 79 20 5c 66 42 5c tionary key \fB\
b370: 2d 64 61 74 61 5c 66 52 2e 20 54 68 65 20 66 69 -data\fR. The fi
b380: 6c 65 20 70 6f 73 69 74 69 6f 6e 20 69 73 20 61 le position is a
b390: 64 76 61 6e 63 65 64 20 6f 6e 20 74 68 65 20 65 dvanced on the e
b3a0: 6e 63 6f 64 69 6e 67 20 65 72 72 6f 72 0a 70 6f ncoding error.po
b3b0: 73 69 74 69 6f 6e 20 31 2e 20 54 68 65 20 64 61 sition 1. The da
b3c0: 74 61 20 61 74 20 74 68 65 20 65 72 72 6f 72 20 ta at the error
b3d0: 70 6f 73 69 74 69 6f 6e 20 69 73 20 74 68 75 73 position is thus
b3e0: 20 72 65 63 6f 76 65 72 65 64 20 62 79 20 74 68 recovered by th
b3f0: 65 20 6e 65 78 74 0a 5c 66 42 63 68 61 6e 20 72 e next.\fBchan r
b400: 65 61 64 5c 66 52 20 63 6f 6d 6d 61 6e 64 2e 0a ead\fR command..
b410: 2e 50 50 0a 2e 43 53 0a 25 20 73 65 74 20 66 20 .PP..CS.% set f
b420: 5b 6f 70 65 6e 20 74 65 73 74 5f 41 5f 31 39 35 [open test_A_195
b430: 5f 42 2e 74 78 74 20 72 5d 0a 66 69 6c 65 33 35 _B.txt r].file35
b440: 61 36 35 61 30 0a 25 20 63 68 61 6e 20 63 6f 6e a65a0.% chan con
b450: 66 69 67 75 72 65 20 24 66 20 2d 65 6e 63 6f 64 figure $f -encod
b460: 69 6e 67 20 75 74 66 2d 38 20 2d 62 6c 6f 63 6b ing utf-8 -block
b470: 69 6e 67 20 31 0a 25 20 63 61 74 63 68 20 7b 63 ing 1.% catch {c
b480: 68 61 6e 20 72 65 61 64 20 24 66 7d 20 65 20 64 han read $f} e d
b490: 0a 31 0a 25 20 73 65 74 20 64 0a 2d 64 61 74 61 .1.% set d.-data
b4a0: 20 41 20 2d 63 6f 64 65 20 31 20 2d 6c 65 76 65 A -code 1 -leve
b4b0: 6c 20 30 0a 2d 65 72 72 6f 72 73 74 61 63 6b 20 l 0.-errorstack
b4c0: 7b 49 4e 4e 45 52 20 7b 69 6e 76 6f 6b 65 53 74 {INNER {invokeSt
b4d0: 6b 31 20 72 65 61 64 20 66 69 6c 65 33 35 61 36 k1 read file35a6
b4e0: 35 61 30 7d 7d 0a 2d 65 72 72 6f 72 63 6f 64 65 5a0}}.-errorcode
b4f0: 20 7b 50 4f 53 49 58 20 45 49 4c 53 45 51 20 7b {POSIX EILSEQ {
b500: 69 6e 76 61 6c 69 64 20 6f 72 20 69 6e 63 6f 6d invalid or incom
b510: 70 6c 65 74 65 20 6d 75 6c 74 69 62 79 74 65 20 plete multibyte
b520: 6f 72 20 77 69 64 65 20 63 68 61 72 61 63 74 65 or wide characte
b530: 72 7d 7d 0a 2d 65 72 72 6f 72 69 6e 66 6f 20 7b r}}.-errorinfo {
b540: 2e 2e 2e 7d 20 2d 65 72 72 6f 72 6c 69 6e 65 20 ...} -errorline
b550: 31 0a 25 20 63 68 61 6e 20 74 65 6c 6c 20 24 66 1.% chan tell $f
b560: 0a 31 0a 25 20 63 68 61 6e 20 63 6f 6e 66 69 67 .1.% chan config
b570: 75 72 65 20 24 66 20 2d 65 6e 63 6f 64 69 6e 67 ure $f -encoding
b580: 20 62 69 6e 61 72 79 0a 25 20 63 68 61 6e 20 72 binary.% chan r
b590: 65 61 64 20 24 66 0a c3 83 42 0a 25 20 63 68 61 ead $f.ÃB.% cha
b5a0: 6e 20 63 6c 6f 73 65 20 24 66 0a 2e 43 45 0a 2e n close $f..CE..
b5b0: 50 50 0a 46 69 6e 61 6c 6c 79 20 74 68 65 20 73 PP.Finally the s
b5c0: 61 6d 65 20 65 78 61 6d 70 6c 65 2c 20 62 75 74 ame example, but
b5d0: 20 74 68 69 73 20 74 69 6d 65 20 77 69 74 68 20 this time with
b5e0: 61 20 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 20 63 a non-blocking c
b5f0: 68 61 6e 6e 65 6c 2e 0a 2e 50 50 0a 2e 43 53 0a hannel...PP..CS.
b600: 25 20 73 65 74 20 66 20 5b 6f 70 65 6e 20 74 65 % set f [open te
b610: 73 74 5f 41 5f 31 39 35 5f 42 2e 74 78 74 20 72 st_A_195_B.txt r
b620: 5d 0a 66 69 6c 65 33 35 61 36 35 61 30 0a 25 20 ].file35a65a0.%
b630: 63 68 61 6e 20 63 6f 6e 66 69 67 75 72 65 20 24 chan configure $
b640: 66 20 2d 65 6e 63 6f 64 69 6e 67 20 75 74 66 2d f -encoding utf-
b650: 38 20 2d 62 6c 6f 63 6b 69 6e 67 20 30 0a 25 20 8 -blocking 0.%
b660: 63 68 61 6e 20 72 65 61 64 20 24 66 0a 41 0a 25 chan read $f.A.%
b670: 20 63 68 61 6e 20 74 65 6c 6c 20 24 66 0a 31 0a chan tell $f.1.
b680: 25 20 63 61 74 63 68 20 7b 63 68 61 6e 20 72 65 % catch {chan re
b690: 61 64 20 24 66 7d 20 65 20 64 0a 31 0a 25 20 73 ad $f} e d.1.% s
b6a0: 65 74 20 64 0a 2d 63 6f 64 65 20 31 20 2d 6c 65 et d.-code 1 -le
b6b0: 76 65 6c 20 30 0a 2d 65 72 72 6f 72 73 74 61 63 vel 0.-errorstac
b6c0: 6b 20 7b 49 4e 4e 45 52 20 7b 69 6e 76 6f 6b 65 k {INNER {invoke
b6d0: 53 74 6b 31 20 72 65 61 64 20 66 69 6c 65 33 38 Stk1 read file38
b6e0: 34 62 32 32 38 7d 7d 0a 2d 65 72 72 6f 72 63 6f 4b228}}.-errorco
b6f0: 64 65 20 7b 50 4f 53 49 58 20 45 49 4c 53 45 51 de {POSIX EILSEQ
b700: 20 7b 69 6e 76 61 6c 69 64 20 6f 72 20 69 6e 63 {invalid or inc
b710: 6f 6d 70 6c 65 74 65 20 6d 75 6c 74 69 62 79 74 omplete multibyt
b720: 65 20 6f 72 20 77 69 64 65 20 63 68 61 72 61 63 e or wide charac
b730: 74 65 72 7d 7d 0a 2d 65 72 72 6f 72 69 6e 66 6f ter}}.-errorinfo
b740: 20 7b 2e 2e 2e 7d 20 2d 65 72 72 6f 72 6c 69 6e {...} -errorlin
b750: 65 20 31 0a 2e 43 45 0a 0a 2e 53 53 20 22 43 48 e 1..CE...SS "CH
b760: 41 4e 4e 45 4c 20 43 4f 50 59 20 45 58 41 4d 50 ANNEL COPY EXAMP
b770: 4c 45 53 22 0a 2e 50 50 0a 54 68 65 20 66 69 72 LES"..PP.The fir
b780: 73 74 20 65 78 61 6d 70 6c 65 20 74 72 61 6e 73 st example trans
b790: 66 65 72 73 20 74 68 65 20 63 6f 6e 74 65 6e 74 fers the content
b7a0: 73 20 6f 66 20 6f 6e 65 20 63 68 61 6e 6e 65 6c s of one channel
b7b0: 20 65 78 61 63 74 6c 79 20 74 6f 0a 61 6e 6f 74 exactly to.anot
b7c0: 68 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 77 her. Note that w
b7d0: 68 65 6e 20 63 6f 70 79 69 6e 67 20 6f 6e 65 20 hen copying one
b7e0: 66 69 6c 65 20 74 6f 20 61 6e 6f 74 68 65 72 2c file to another,
b7f0: 20 69 74 20 69 73 20 62 65 74 74 65 72 20 74 6f it is better to
b800: 0a 75 73 65 20 5c 66 42 66 69 6c 65 20 63 6f 70 .use \fBfile cop
b810: 79 5c 66 52 20 77 68 69 63 68 20 61 6c 73 6f 20 y\fR which also
b820: 63 6f 70 69 65 73 20 66 69 6c 65 20 6d 65 74 61 copies file meta
b830: 64 61 74 61 20 28 65 2e 67 2e 20 74 68 65 20 66 data (e.g. the f
b840: 69 6c 65 0a 61 63 63 65 73 73 20 70 65 72 6d 69 ile.access permi
b850: 73 73 69 6f 6e 73 29 20 77 68 65 72 65 20 70 6f ssions) where po
b860: 73 73 69 62 6c 65 2e 0a 2e 50 50 0a 2e 43 53 0a ssible...PP..CS.
b870: 5c 66 42 63 68 61 6e 20 63 6f 6e 66 69 67 75 72 \fBchan configur
b880: 65 5c 66 52 20 24 69 6e 20 2d 74 72 61 6e 73 6c e\fR $in -transl
b890: 61 74 69 6f 6e 20 62 69 6e 61 72 79 0a 5c 66 42 ation binary.\fB
b8a0: 63 68 61 6e 20 63 6f 6e 66 69 67 75 72 65 5c 66 chan configure\f
b8b0: 52 20 24 6f 75 74 20 2d 74 72 61 6e 73 6c 61 74 R $out -translat
b8c0: 69 6f 6e 20 62 69 6e 61 72 79 0a 5c 66 42 63 68 ion binary.\fBch
b8d0: 61 6e 20 63 6f 70 79 5c 66 52 20 24 69 6e 20 24 an copy\fR $in $
b8e0: 6f 75 74 0a 2e 43 45 0a 2e 50 50 0a 54 68 69 73 out..CE..PP.This
b8f0: 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
b900: 73 68 6f 77 73 20 68 6f 77 20 74 68 65 20 63 61 shows how the ca
b910: 6c 6c 62 61 63 6b 20 67 65 74 73 0a 70 61 73 73 llback gets.pass
b920: 65 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ed the number of
b930: 20 62 79 74 65 73 20 74 72 61 6e 73 66 65 72 72 bytes transferr
b940: 65 64 2e 0a 49 74 20 61 6c 73 6f 20 75 73 65 73 ed..It also uses
b950: 20 76 77 61 69 74 20 74 6f 20 70 75 74 20 74 68 vwait to put th
b960: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e e application in
b970: 74 6f 20 74 68 65 20 65 76 65 6e 74 20 6c 6f 6f to the event loo
b980: 70 2e 0a 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 p..Of course, th
b990: 69 73 20 73 69 6d 70 6c 69 66 69 65 64 20 65 78 is simplified ex
b9a0: 61 6d 70 6c 65 20 63 6f 75 6c 64 20 62 65 20 64 ample could be d
b9b0: 6f 6e 65 20 77 69 74 68 6f 75 74 20 74 68 65 20 one without the
b9c0: 63 6f 6d 6d 61 6e 64 0a 63 61 6c 6c 62 61 63 6b command.callback
b9d0: 2e 0a 2e 50 50 0a 2e 43 53 0a 70 72 6f 63 20 43 ...PP..CS.proc C
b9e0: 6c 65 61 6e 75 70 20 7b 69 6e 20 6f 75 74 20 62 leanup {in out b
b9f0: 79 74 65 73 20 7b 65 72 72 6f 72 20 7b 7d 7d 7d ytes {error {}}}
ba00: 20 7b 0a 20 20 20 20 67 6c 6f 62 61 6c 20 74 6f {. global to
ba10: 74 61 6c 0a 20 20 20 20 73 65 74 20 74 6f 74 61 tal. set tota
ba20: 6c 20 24 62 79 74 65 73 0a 20 20 20 20 5c 66 42 l $bytes. \fB
ba30: 63 68 61 6e 20 63 6c 6f 73 65 5c 66 52 20 24 69 chan close\fR $i
ba40: 6e 0a 20 20 20 20 5c 66 42 63 68 61 6e 20 63 6c n. \fBchan cl
ba50: 6f 73 65 5c 66 52 20 24 6f 75 74 0a 20 20 20 20 ose\fR $out.
ba60: 69 66 20 7b 24 65 72 72 6f 72 20 6e 65 20 22 22 if {$error ne ""
ba70: 7d 20 7b 0a 20 20 20 20 20 20 20 20 23 20 65 72 } {. # er
ba80: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 64 75 72 ror occurred dur
ba90: 69 6e 67 20 74 68 65 20 63 6f 70 79 0a 20 20 20 ing the copy.
baa0: 20 7d 0a 7d 0a 0a 73 65 74 20 69 6e 20 5b 6f 70 }.}..set in [op
bab0: 65 6e 20 24 66 69 6c 65 31 5d 0a 73 65 74 20 6f en $file1].set o
bac0: 75 74 20 5b 73 6f 63 6b 65 74 20 24 73 65 72 76 ut [socket $serv
bad0: 65 72 20 24 70 6f 72 74 5d 0a 5c 66 42 63 68 61 er $port].\fBcha
bae0: 6e 20 63 6f 70 79 5c 66 52 20 24 69 6e 20 24 6f n copy\fR $in $o
baf0: 75 74 20 2d 63 6f 6d 6d 61 6e 64 20 5b 6c 69 73 ut -command [lis
bb00: 74 20 43 6c 65 61 6e 75 70 20 24 69 6e 20 24 6f t Cleanup $in $o
bb10: 75 74 5d 0a 76 77 61 69 74 20 74 6f 74 61 6c 0a ut].vwait total.
bb20: 2e 43 45 0a 2e 50 50 0a 54 68 65 20 74 68 69 72 .CE..PP.The thir
bb30: 64 20 65 78 61 6d 70 6c 65 20 63 6f 70 69 65 73 d example copies
bb40: 20 69 6e 20 63 68 75 6e 6b 73 20 61 6e 64 20 74 in chunks and t
bb50: 65 73 74 73 20 66 6f 72 20 65 6e 64 20 6f 66 20 ests for end of
bb60: 66 69 6c 65 0a 69 6e 20 74 68 65 20 63 6f 6d 6d file.in the comm
bb70: 61 6e 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2e 50 and callback...P
bb80: 50 0a 2e 43 53 0a 70 72 6f 63 20 43 6f 70 79 4d P..CS.proc CopyM
bb90: 6f 72 65 20 7b 69 6e 20 6f 75 74 20 63 68 75 6e ore {in out chun
bba0: 6b 20 62 79 74 65 73 20 7b 65 72 72 6f 72 20 7b k bytes {error {
bbb0: 7d 7d 7d 20 7b 0a 20 20 20 20 67 6c 6f 62 61 6c }}} {. global
bbc0: 20 74 6f 74 61 6c 20 64 6f 6e 65 0a 20 20 20 20 total done.
bbd0: 69 6e 63 72 20 74 6f 74 61 6c 20 24 62 79 74 65 incr total $byte
bbe0: 73 0a 20 20 20 20 69 66 20 7b 28 24 65 72 72 6f s. if {($erro
bbf0: 72 20 6e 65 20 22 22 29 20 7c 7c 20 5b 5c 66 42 r ne "") || [\fB
bc00: 63 68 61 6e 20 65 6f 66 5c 66 52 20 24 69 6e 5d chan eof\fR $in]
bc10: 7d 20 7b 0a 20 20 20 20 20 20 20 20 73 65 74 20 } {. set
bc20: 64 6f 6e 65 20 24 74 6f 74 61 6c 0a 20 20 20 20 done $total.
bc30: 20 20 20 20 5c 66 42 63 68 61 6e 20 63 6c 6f 73 \fBchan clos
bc40: 65 5c 66 52 20 24 69 6e 0a 20 20 20 20 20 20 20 e\fR $in.
bc50: 20 5c 66 42 63 68 61 6e 20 63 6c 6f 73 65 5c 66 \fBchan close\f
bc60: 52 20 24 6f 75 74 0a 20 20 20 20 7d 20 65 6c 73 R $out. } els
bc70: 65 20 7b 0a 20 20 20 20 20 20 20 20 5c 66 42 63 e {. \fBc
bc80: 68 61 6e 20 63 6f 70 79 5c 66 52 20 24 69 6e 20 han copy\fR $in
bc90: 24 6f 75 74 20 2d 73 69 7a 65 20 24 63 68 75 6e $out -size $chun
bca0: 6b 20 5c 65 0a 20 20 20 20 20 20 20 20 20 20 20 k \e.
bcb0: 20 2d 63 6f 6d 6d 61 6e 64 20 5b 6c 69 73 74 20 -command [list
bcc0: 43 6f 70 79 4d 6f 72 65 20 24 69 6e 20 24 6f 75 CopyMore $in $ou
bcd0: 74 20 24 63 68 75 6e 6b 5d 0a 20 20 20 20 7d 0a t $chunk]. }.
bce0: 7d 0a 0a 73 65 74 20 69 6e 20 5b 6f 70 65 6e 20 }..set in [open
bcf0: 24 66 69 6c 65 31 5d 0a 73 65 74 20 6f 75 74 20 $file1].set out
bd00: 5b 73 6f 63 6b 65 74 20 24 73 65 72 76 65 72 20 [socket $server
bd10: 24 70 6f 72 74 5d 0a 73 65 74 20 63 68 75 6e 6b $port].set chunk
bd20: 20 31 30 32 34 0a 73 65 74 20 74 6f 74 61 6c 20 1024.set total
bd30: 30 0a 5c 66 42 63 68 61 6e 20 63 6f 70 79 5c 66 0.\fBchan copy\f
bd40: 52 20 24 69 6e 20 24 6f 75 74 20 2d 73 69 7a 65 R $in $out -size
bd50: 20 24 63 68 75 6e 6b 20 5c 65 0a 20 20 20 20 2d $chunk \e. -
bd60: 63 6f 6d 6d 61 6e 64 20 5b 6c 69 73 74 20 43 6f command [list Co
bd70: 70 79 4d 6f 72 65 20 24 69 6e 20 24 6f 75 74 20 pyMore $in $out
bd80: 24 63 68 75 6e 6b 5d 0a 76 77 61 69 74 20 64 6f $chunk].vwait do
bd90: 6e 65 0a 2e 43 45 0a 2e 50 50 0a 54 68 65 20 66 ne..CE..PP.The f
bda0: 6f 75 72 74 68 20 65 78 61 6d 70 6c 65 20 73 74 ourth example st
bdb0: 61 72 74 73 20 61 6e 20 61 73 79 6e 63 68 72 6f arts an asynchro
bdc0: 6e 6f 75 73 2c 20 62 69 64 69 72 65 63 74 69 6f nous, bidirectio
bdd0: 6e 61 6c 20 63 6f 70 79 20 62 65 74 77 65 65 6e nal copy between
bde0: 0a 74 77 6f 20 73 6f 63 6b 65 74 73 2e 20 54 68 .two sockets. Th
bdf0: 6f 73 65 20 63 6f 75 6c 64 20 61 6c 73 6f 20 62 ose could also b
be00: 65 20 70 69 70 65 73 20 66 72 6f 6d 20 74 77 6f e pipes from two
be10: 20 62 69 64 69 72 65 63 74 69 6f 6e 61 6c 20 70 bidirectional p
be20: 69 70 65 6c 69 6e 65 73 0a 28 65 2e 67 2e 2c 20 ipelines.(e.g.,
be30: 5c 66 49 5b 6f 70 65 6e 20 22 7c 68 61 6c 20 39 \fI[open "|hal 9
be40: 30 30 30 22 20 72 2b 5d 5c 66 52 29 3b 20 74 68 000" r+]\fR); th
be50: 65 20 63 6f 6e 76 65 72 73 61 74 69 6f 6e 20 77 e conversation w
be60: 69 6c 6c 20 72 65 6d 61 69 6e 0a 65 73 73 65 6e ill remain.essen
be70: 74 69 61 6c 6c 79 20 73 65 63 72 65 74 20 74 6f tially secret to
be80: 20 74 68 65 20 73 63 72 69 70 74 2c 20 73 69 6e the script, sin
be90: 63 65 20 61 6c 6c 20 66 6f 75 72 20 5c 66 42 63 ce all four \fBc
bea0: 68 61 6e 20 65 76 65 6e 74 5c 66 52 20 73 6c 6f han event\fR slo
beb0: 74 73 0a 61 72 65 20 62 75 73 79 2c 20 74 68 6f ts.are busy, tho
bec0: 75 67 68 20 61 6e 79 20 74 72 61 6e 73 66 6f 72 ugh any transfor
bed0: 6d 73 20 74 68 61 74 20 61 72 65 20 5c 66 42 63 ms that are \fBc
bee0: 68 61 6e 20 70 75 73 68 5c 66 52 65 64 20 6f 6e han push\fRed on
bef0: 20 74 68 65 0a 63 68 61 6e 6e 65 6c 73 20 77 69 the.channels wi
bf00: 6c 6c 20 62 65 20 61 62 6c 65 20 74 6f 20 6f 62 ll be able to ob
bf10: 73 65 72 76 65 20 74 68 65 20 70 61 73 73 69 6e serve the passin
bf20: 67 20 74 72 61 66 66 69 63 2e 0a 2e 50 50 0a 2e g traffic...PP..
bf30: 43 53 0a 70 72 6f 63 20 44 6f 6e 65 20 7b 64 69 CS.proc Done {di
bf40: 72 20 61 72 67 73 7d 20 7b 0a 20 20 20 20 67 6c r args} {. gl
bf50: 6f 62 61 6c 20 66 6c 6f 77 73 20 64 6f 6e 65 0a obal flows done.
bf60: 20 20 20 20 5c 66 42 63 68 61 6e 20 70 75 74 73 \fBchan puts
bf70: 5c 66 52 20 22 24 64 69 72 20 69 73 20 6f 76 65 \fR "$dir is ove
bf80: 72 2e 22 0a 20 20 20 20 69 6e 63 72 20 66 6c 6f r.". incr flo
bf90: 77 73 20 2d 31 0a 20 20 20 20 69 66 20 7b 24 66 ws -1. if {$f
bfa0: 6c 6f 77 73 20 3c 3d 20 30 7d 20 7b 0a 20 20 20 lows <= 0} {.
bfb0: 20 20 20 20 20 73 65 74 20 64 6f 6e 65 20 31 0a set done 1.
bfc0: 20 20 20 20 7d 0a 7d 0a 0a 73 65 74 20 66 6c 6f }.}..set flo
bfd0: 77 73 20 32 0a 5c 66 42 63 68 61 6e 20 63 6f 70 ws 2.\fBchan cop
bfe0: 79 5c 66 52 20 24 73 6f 6b 31 20 24 73 6f 6b 32 y\fR $sok1 $sok2
bff0: 20 2d 63 6f 6d 6d 61 6e 64 20 5b 6c 69 73 74 20 -command [list
c000: 44 6f 6e 65 20 55 50 5d 0a 5c 66 42 63 68 61 6e Done UP].\fBchan
c010: 20 63 6f 70 79 5c 66 52 20 24 73 6f 6b 32 20 24 copy\fR $sok2 $
c020: 73 6f 6b 31 20 2d 63 6f 6d 6d 61 6e 64 20 5b 6c sok1 -command [l
c030: 69 73 74 20 44 6f 6e 65 20 44 4f 57 4e 5d 0a 76 ist Done DOWN].v
c040: 77 61 69 74 20 64 6f 6e 65 0a 2e 43 45 0a 2e 53 wait done..CE..S
c050: 48 20 22 53 45 45 20 41 4c 53 4f 22 0a 63 6c 6f H "SEE ALSO".clo
c060: 73 65 28 6e 29 2c 20 65 6f 66 28 6e 29 2c 20 66 se(n), eof(n), f
c070: 62 6c 6f 63 6b 65 64 28 6e 29 2c 20 66 63 6f 6e blocked(n), fcon
c080: 66 69 67 75 72 65 28 6e 29 2c 20 66 63 6f 70 79 figure(n), fcopy
c090: 28 6e 29 2c 20 66 69 6c 65 28 6e 29 2c 0a 66 69 (n), file(n),.fi
c0a0: 6c 65 65 76 65 6e 74 28 6e 29 2c 20 66 6c 75 73 leevent(n), flus
c0b0: 68 28 6e 29 2c 20 67 65 74 73 28 6e 29 2c 20 6f h(n), gets(n), o
c0c0: 70 65 6e 28 6e 29 2c 20 70 75 74 73 28 6e 29 2c pen(n), puts(n),
c0d0: 20 72 65 61 64 28 6e 29 2c 20 73 65 65 6b 28 6e read(n), seek(n
c0e0: 29 2c 0a 73 6f 63 6b 65 74 28 6e 29 2c 20 74 65 ),.socket(n), te
c0f0: 6c 6c 28 6e 29 2c 20 72 65 66 63 68 61 6e 28 6e ll(n), refchan(n
c100: 29 2c 20 74 72 61 6e 73 63 68 61 6e 28 6e 29 2c ), transchan(n),
c110: 0a 54 63 6c 5f 53 74 61 6e 64 61 72 64 43 68 61 .Tcl_StandardCha
c120: 6e 6e 65 6c 73 28 33 29 0a 2e 53 48 20 4b 45 59 nnels(3)..SH KEY
c130: 57 4f 52 44 53 0a 62 6c 6f 63 6b 69 6e 67 2c 20 WORDS.blocking,
c140: 63 68 61 6e 6e 65 6c 2c 20 65 6e 64 20 6f 66 20 channel, end of
c150: 66 69 6c 65 2c 20 65 76 65 6e 74 73 2c 20 69 6e file, events, in
c160: 70 75 74 2c 20 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e put, non-blockin
c170: 67 2c 0a 6f 66 66 73 65 74 2c 20 6f 75 74 70 75 g,.offset, outpu
c180: 74 2c 20 72 65 61 64 61 62 6c 65 2c 20 73 65 65 t, readable, see
c190: 6b 2c 20 73 74 64 69 6f 2c 20 74 65 6c 6c 2c 20 k, stdio, tell,
c1a0: 77 72 69 74 61 62 6c 65 0a 27 5c 22 20 4c 6f 63 writable.'\" Loc
c1b0: 61 6c 20 56 61 72 69 61 62 6c 65 73 3a 0a 27 5c al Variables:.'\
c1c0: 22 20 6d 6f 64 65 3a 20 6e 72 6f 66 66 0a 27 5c " mode: nroff.'\
c1d0: 22 20 45 6e 64 3a 0a " End:.
