Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Consolidate channel documentation. close, puts etc. manpages now just reference chan |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | descendants | both | trunk | main |
Files: | files | file ages | folders |
SHA3-256: |
e56d76c76121b3fc741da94f4d374d53 |
User & Date: | apnadkarni 2024-04-22 12:55:32 |
Context
2024-04-22
| ||
16:28 | Fix [6eb8d79cb8]: segfault in obj-34.1 check-in: 59010ad4e6 user: jan.nijtmans tags: trunk, main | |
12:55 | Consolidate channel documentation. close, puts etc. manpages now just reference chan check-in: e56d76c761 user: apnadkarni tags: trunk, main | |
07:01 | Merge 8.7 check-in: 4dbeabc65c user: oehhar tags: trunk, main | |
2024-04-11
| ||
02:27 | Done with consolidating chan related docs except chan copy Closed-Leaf check-in: 6fea3e0740 user: apnadkarni tags: apn-chan-docs | |
Changes
Changes to doc/chan.n.
︙ | ︙ | |||
29 30 31 32 33 34 35 | on the channel failed because it would have otherwise caused the process to block, and 0 otherwise. Each Tcl channel is in blocking mode unless configured otherwise. .\" METHOD: close .TP \fBchan close \fIchannelName\fR ?\fIdirection\fR? . | | | | < < < | | | | | | 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | on the channel failed because it would have otherwise caused the process to block, and 0 otherwise. Each Tcl channel is in blocking mode unless configured otherwise. .\" METHOD: close .TP \fBchan close \fIchannelName\fR ?\fIdirection\fR? . Closes and destroys the named channel deleting any existing event handlers established for the channel. The command returns the empty string. If \fIdirection\fR is given, it is \fBread\fR, or \fBwrite\fR, or any unique abbreviation of those words, and only that side of the channel is closed. I.e. a read-write channel may become read-only or write-only. Closing a read-only channel for reading, or closing a write-only channel for writing is the same as simply closing the channel. It is an error to close a read-only channel for writing or to close a write-only channel for reading. .RS .PP When a channel is closed for writing, any buffered output on the channel is flushed. When a channel is closed for reading, any buffered input is discarded. When a channel is destroyed the underlying resource is closed and the channel is thereafter unavailable. .PP |
︙ | ︙ | |||
86 87 88 89 90 91 92 | .QW \fB0\fR restores the previous behavior. .RE .\" METHOD: configure .TP \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . | | | | | | 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | .QW \fB0\fR restores the previous behavior. .RE .\" METHOD: configure .TP \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . Configures or retrieves the configuration of the channel \fIchannelName\fR. .RS .PP If no \fIoptionName\fR or \fIvalue\fR arguments are given, \fBchan configure\fR returns a dictionary of option names and values for the channel. If \fIoptionName\fR is supplied without a \fIvalue\fR, \fBchan configure\fR returns the current value of the named option. If one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, \fBchan configure\fR sets each of the named options to the corresponding \fIvalue\fR and returns the empty string. .PP The options described below are supported for all channels. Each type of channel may provide additional options. Those options are described in the relevant documentation. For example, additional options are documented for \fBsocket\fR, and also for serial devices at \fBopen\fR. .\" OPTION: -blocking .TP \fB\-blocking\fI boolean\fR . If \fB\-blocking\fR is set to \fBtrue\fR (default), reading the channel or writing to it may cause the process to block indefinitely. Otherwise, operations such as \fBchan gets\fR, \fBchan read\fR, \fBchan puts\fR, \fBchan flush\fR, and \fBchan close\fR take care not to block. Non-blocking mode in general requires that the event loop is entered, e.g. by calling \fBTcl_DoOneEvent\fR or \fBvwait\fR or by using Tk, to give Tcl a chance to process events on the channel. .\" OPTION: -buffering .TP \fB\-buffering\fI newValue\fR . If \fInewValue\fR is \fBfull\fR, which is the default, output is buffered |
︙ | ︙ | |||
131 132 133 134 135 136 137 | .TP \fB\-buffersize\fI newSize\fR . \fInewSize\fR, an integer no greater than one million, is the size in bytes of any input or output buffers subsequently allocated for this channel. .\" OPTION: -encoding .TP | | | | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | .TP \fB\-buffersize\fI newSize\fR . \fInewSize\fR, an integer no greater than one million, is the size in bytes of any input or output buffers subsequently allocated for this channel. .\" OPTION: -encoding .TP \fB\-encoding\fR \fIname\fR . Sets the encoding of the channel to \fIname\fR which should be one of the names returned by \fBencoding names\fR, or .QW \fBbinary\fR \&. Input is converted from the encoding into Unicode, and output is converted from Unicode to the encoding. .RS .PP \fBbinary\fR is an alias for \fBiso8859-1\fR. This alone is not sufficient for |
︙ | ︙ | |||
190 191 192 193 194 195 196 | output, e.g. with \fBchan puts\fR, each line feed is translated to the external end-of-line character. The default translation, \fBauto\fR, handles all the common cases, and \fB\-translation\fR provides explicit control over the end-of-line character. .RS .PP Returns the input translation for a read-only channel, the output translation | | | 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 | output, e.g. with \fBchan puts\fR, each line feed is translated to the external end-of-line character. The default translation, \fBauto\fR, handles all the common cases, and \fB\-translation\fR provides explicit control over the end-of-line character. .RS .PP Returns the input translation for a read-only channel, the output translation for a write-only channel, and both the input translation and the output translation for a read-write channel. When two translations are given, they are the input and output translation, respectively. When only one translation is given for a read-write channel, it is the translation for both input and output. The following values are currently supported: .IP \fBauto\fR The default. For input each occurrence of a line feed (\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a line feed (\fBcrlf\fR) is |
︙ | ︙ | |||
339 340 341 342 343 344 345 | \fIscript\fR is evaluated at the global level in the interpreter it was established in. Any resulting error is handled in the background, i.e. via \fBinterp bgerror\fR. In order to prevent an endless loop due to a buggy handler, the handler is deleted if \fIscript\fR returns an error so that it is not evaluated again. .PP Without an event handler, \fBchan gets\fR or \fBchan read\fR on a channel in | | | > | | > > > | > | < < > > > < | | | | | < | | < | | | > > | | > > > | > > > > > > > > > | < > | > > > | > > > > > > > > > | 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 | \fIscript\fR is evaluated at the global level in the interpreter it was established in. Any resulting error is handled in the background, i.e. via \fBinterp bgerror\fR. In order to prevent an endless loop due to a buggy handler, the handler is deleted if \fIscript\fR returns an error so that it is not evaluated again. .PP Without an event handler, \fBchan gets\fR or \fBchan read\fR on a channel in blocking mode may block until data becomes available, during which the thread is unable to perform other work or respond to events on other channels. This could cause the application to appear to .QW "freeze up" \&. Channel event handlers allow events on the channel to direct channel handling so that the reader or writer can continue to perform other processing while waiting for a channel to become available and then handle channel operations when the channel is ready for the operation. .PP A channel is considered to be readable if there is unread data available on the underlying device. A channel is also considered to be readable if there is unread data in an input buffer, except in the special case where the most recent attempt to read from the channel was a \fBchan gets\fR call that could not find a complete line in the input buffer. This feature allows a file to be read a line at a time in non-blocking mode using events. A channel is also considered to be readable if an end of file or error condition is present on the underlying file or device. It is important for \fIscript\fR to check for these conditions and handle them appropriately; for example, if there is no special check for end of file, an infinite loop may occur where \fIscript\fR reads no data, returns, and is immediately invoked again. .PP A channel is considered to be writable if at least one byte of data can be written to the underlying file or device without blocking, or if an error condition is present. Note that client sockets opened in asynchronous mode become writable when they become connected or if the connection fails. .PP Event-driven channel handling works best for channels in non-blocking mode. A channel in blocking mode blocks when \fBchan puts\fR writes more data than the channel can accept at the moment, and when \fBchan gets\fR or \fBchan read\fR requests more data than is currently available. When a channel blocks, the thread can not do any other processing or service any other events. A channel in non-blocking mode allows a thread to carry on with other work and get back to the channel at the right time. .RE .\" METHOD: flush .TP \fBchan flush \fIchannelName\fR . For a channel in blocking mode, flushes all buffered output to the destination, and then returns. For a channel in non-blocking mode, returns immediately while all buffered output is flushed in the background as soon as possible. .\" METHOD: gets .TP \fBchan gets \fIchannelName\fR ?\fIvarName\fR? . Reads a line from the channel consisting of all characters up to the next end-of-line sequence or until end of file is seen. The line feed character corresponding to end-of-line sequence is not included as part of the line. If the \fIvarName\fR argument is specified, the line is stored in the variable of that name and the command returns the length of the line. If \fIvarName\fR is not specified, the command returns the line itself as the result of the command. .RS .PP If a complete line is not available and the channel is not at EOF, the command will block in the case of a blocking channel. For non-blocking channels, the command will return the empty string as the result in the case of \fIvarName\fR not specified and -1 if it is. .RE .RS .PP If a blocking channel is already at EOF, the command returns an empty string if \fIvarName\fR is not specified. Note an empty string result can also be returned when a blank line (no characters before the next end of line sequence). The two cases can be distinguished by calling the \fBchan eof\fR command to check for end of file. If \fIvarName\fR is specified, the command returns -1 on end of file. There is no ambiguity in this case because blank lines result in 0 being returned. .RE .RS .PP If a non-blocking channel is already at EOF, the command returns an empty line if \fIvarName\fR is not specified. This can be distinguished from an empty line being returned by either a blank line being read or a full line not being available through the use of the \fBchan eof\fR and \fBchan blocked\fR commands. If \fBchan eof\fR returns true, the channel is at EOF. If \fBchan blocked\fR returns true, a full line was not available. If both commands return false, an empty line was read. If \fIvarName\fR was specified for a non-bocking channel at EOF, the command returns -1. This can be distinguished from full line not being available either by \fBchan eof\fR or \fBchan blocked\fR as above. Note that when \fIvarName\fR is specified, there is no need to distinguish between eof and blank lines as the latter will result in the command returning 0. .PP If the encoding profile \fBstrict\fR is in effect for the channel, the command will raise an exception with the POSIX error code \fBEILSEQ\fR if any encoding errors are encountered in the channel input data. The file pointer remains unchanged and it is possible to introspect, and in some cases recover, by changing the encoding in use. See \fBENCODING ERROR EXAMPLES\fR later. .RE .\" METHOD: names .TP \fBchan names\fR ?\fIpattern\fR? . Returns a list of all channel names, or if \fIpattern\fR is given, only those names that match according to the rules of \fBstring match\fR. |
︙ | ︙ | |||
505 506 507 508 509 510 511 | \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelName\fR? \fIstring\fR . Writes \fIstring\fR and a line feed to the channel. If \fB\-nonewline\fR is given, the trailing line feed is not written. The default channel is \fBstdout\fR. .RS .PP | | | | | | | | < | | | | | > > > > > | > > > > > > > > > > > > > > > | 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 | \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelName\fR? \fIstring\fR . Writes \fIstring\fR and a line feed to the channel. If \fB\-nonewline\fR is given, the trailing line feed is not written. The default channel is \fBstdout\fR. .RS .PP Each line feed in the output is translated to the appropriate end of line sequence as per the \fB\-translation\fR configuration setting of the channel. .PP Because Tcl internally buffers output, characters written to a channel may not immediately be available at the destination. Tcl normally delays output until the buffer is full or the channel is closed. \fBchan flush\fR forces output in the direction of the destination. .PP When the output for a channel in blocking mode fills up, \fBchan puts\fR blocks until space in the buffer is available again. On the other hand for a channel in non-blocking mode, it returns immediately and the data is written in the background as fast possible, constrained by the speed at which as the destination accepts it. Output to a channel in non-blocking mode only works properly when the application enters the event loop. When a channel is in non-blocking mode, Tcl's internal buffers can hold an arbitrary amount of data, possibly consuming a large amount of memory. To avoid wasting memory, channels in non-blocking mode should normally be handled using \fBchan event\fR, where the application only invokes \fBchan puts\fR after being notified through a file event handler that the channel is ready for more output data. .PP The command will raise an error exception with POSIX error code \fBEILSEQ\fR if the encoding profile \fBstrict\fR is in effect for the channel and the output data cannot be encoded in the encoding configured for the channel. Data may be partially written to the channel in this case. .RE .\" METHOD: read .TP \fBchan read \fIchannelName\fR ?\fInumChars\fR? .TP \fBchan read \fR?\fB\-nonewline\fR? \fIchannelName\fR . Reads and returns the next \fInumChars\fR characters from the channel. If \fInumChars\fR is omitted, all available characters up to the end of the file are read, or if the channel is in non-blocking mode, all currently-available characters are read. If there is an error on the channel, reading ceases and an error is returned. If \fInumChars\fR is not given, \fB\-nonewline\fR may be given, causing any trailing line feed to be trimmed. .RS .PP If the channel is in non-blocking mode, fewer characters than requested may be returned. If the channel is configured to use a multi-byte encoding, bytes that do not form a complete character are retained in the buffers until enough bytes to complete the character accumulate, or the end of the data is reached. \fB\-nonewline\fR is ignored if characters are returned before reaching the end of the file. .PP Each end-of-line sequence according to the value of \fB\-translation\fR is translated into a line feed. .PP When reading from a serial port, most applications should configure the serial port channel to be in non-blocking mode, but not necessarily use an event handler since most serial ports are comparatively slow. It is entirely possible to get a \fBreadable\fR event for each individual character. In blocking mode, \fBchan read\fR blocks forever when reading to the end of the data if there is no \fBchan configure -eofchar\fR configured for the channel. .PP If the encoding profile \fBstrict\fR is in effect for the channel, the command will raise an exception with the POSIX error code \fBEILSEQ\fR if any encoding errors are encountered in the channel input data. If the channel is in blocking mode, the error is thrown after advancing the file pointer to the beginning of the invalid data. The successfully decoded leading portion of the data prior to the error location is returned as the value of the \fB\-data\fR key of the error option dictionary. If the channel is in non-blocking mode, the successfully decoded portion of data is returned by the command without an error exception being raised. A subsequent read will start at the invalid data and immediately raise a \fBEILSEQ\fR POSIX error exception. Unlike the blocking channel case, the \fB\-data\fR key is not present in the error option dictionary. In the case of exception thrown due to encoding errors, it is possible to introspect, and in some cases recover, by changing the encoding in use. See \fBENCODING ERROR EXAMPLES\fR later. .RE .\" METHOD: seek .TP \fBchan seek \fIchannelName offset\fR ?\fIorigin\fR? . Sets the current position for the data in the channel to integer \fIoffset\fR bytes relative to \fIorigin\fR. A negative offset moves the current position |
︙ | ︙ | |||
597 598 599 600 601 602 603 604 605 606 607 608 609 610 | \fBchan truncate \fIchannelName\fR ?\fIlength\fR? . Flushes the channel and truncates the data in the channel to \fIlength\fR bytes, or to the current position in bytes if \fIlength\fR is omitted. . .SH EXAMPLES .SS "SIMPLE CHANNEL OPERATION EXAMPLES" .PP In the following example a file is opened using the encoding CP1252, which is common on Windows, searches for a string, rewrites that part, and truncates the file two lines later. .PP .CS set f [open somefile.txt r+] | > > > > > > > | 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 | \fBchan truncate \fIchannelName\fR ?\fIlength\fR? . Flushes the channel and truncates the data in the channel to \fIlength\fR bytes, or to the current position in bytes if \fIlength\fR is omitted. . .SH EXAMPLES .SS "SIMPLE CHANNEL OPERATION EXAMPLES" .PP Instruct Tcl to always send output to \fBstdout\fR immediately, whether or not it is to a terminal: .PP .CS \fBfconfigure\fR stdout -buffering none .CE .PP In the following example a file is opened using the encoding CP1252, which is common on Windows, searches for a string, rewrites that part, and truncates the file two lines later. .PP .CS set f [open somefile.txt r+] |
︙ | ︙ | |||
630 631 632 633 634 635 636 637 638 639 640 641 642 643 | } \fI# Save offset of start of next line for later\fR set offset [\fBchan tell\fR $f] } \fBchan close\fR $f .CE .PP A network server that echoes its input line-by-line without preventing servicing of other connections at the same time: .PP .CS # This is a very simple logger... proc log message { | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 | } \fI# Save offset of start of next line for later\fR set offset [\fBchan tell\fR $f] } \fBchan close\fR $f .CE .PP This example illustrates flushing of a channel. The user is prompted for some information. Because the standard input channel is line buffered, it must be flushed for the user to see the prompt. .PP .CS chan puts -nonewline "Please type your name: " \fBchan flush\fR stdout chan gets stdin name chan puts "Hello there, $name!" .CE .PP This example reads a file one line at a time and prints it out with the current line number attached to the start of each line. .PP .CS set chan [open "some.file.txt"] set lineNumber 0 while {[\fBchan gets\fR $chan line] >= 0} { chan puts "[incr lineNumber]: $line" } chan close $chan .CE .PP In this example illustrating event driven reads, \fBGetData\fR will be called with the channel as an argument whenever $chan becomes readable. The \fBread\fR call will read whatever binary data is currently available without blocking. Here the channel has the fileevent removed when an end of file occurs to avoid being continually called (see above). Alternatively the channel may be closed on this condition. .PP .CS proc GetData {chan} { set data [chan read $chan] chan puts "[string length $data] $data" if {[chan eof $chan]} { chan event $chan readable {} } } chan configure $chan -blocking 0 -encoding binary \fBchan event\fR $chan readable [list GetData $chan] .CE .PP The next example is similar but uses \fBchan gets\fR to read line-oriented data. .PP .CS proc GetData {chan} { if {[chan gets $chan line] >= 0} { chan puts $line } if {[chan eof $chan]} { chan close $chan } } chan configure $chan -blocking 0 -buffering line -translation crlf \fBchan event\fR $chan readable [list GetData $chan] .CE .PP A network server that echoes its input line-by-line without preventing servicing of other connections at the same time: .PP .CS # This is a very simple logger... proc log message { |
︙ | ︙ | |||
667 668 669 670 671 672 673 674 675 676 677 678 679 680 | } # Create the server socket and enter the event-loop to wait # for incoming connections... socket -server connect 12345 vwait forever .CE .SS "CHANNEL COPY EXAMPLES" .PP The first example transfers the contents of one channel exactly to another. Note that when copying one file to another, it is better to use \fBfile copy\fR which also copies file metadata (e.g. the file access permissions) where possible. .PP | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 | } # Create the server socket and enter the event-loop to wait # for incoming connections... socket -server connect 12345 vwait forever .CE .PP The following example reads a PPM-format image from a file combining ASCII and binary content. .PP .CS # Open the file and put it into Unix ASCII mode set f [open teapot.ppm] \fBchan configure\fR $f -encoding ascii -translation lf # Get the header if {[chan gets $f] ne "P6"} { error "not a raw\-bits PPM" } # Read lines until we have got non-comment lines # that supply us with three decimal values. set words {} while {[llength $words] < 3} { chan gets $f line if {[string match "#*" $line]} continue lappend words {*}[join [scan $line %d%d%d]] } # Those words supply the size of the image and its # overall depth per channel. Assign to variables. lassign $words xSize ySize depth # Now switch to binary mode to pull in the data, # one byte per channel (red,green,blue) per pixel. \fBchan configure\fR $f -translation binary set numDataBytes [expr {3 * $xSize * $ySize}] set data [chan read $f $numDataBytes] close $f .CE .SS "FILE SEEK EXAMPLES" .PP Read a file twice: .PP .CS set f [open file.txt] set data1 [chan read $f] \fBchan seek\fR $f 0 set data2 [chan read $f] chan close $f # $data1 eq $data2 if the file wasn't updated .CE .PP Read the last 10 bytes from a file: .PP .CS set f [open file.data] # This is guaranteed to work with binary data but # may fail with other encodings... chan configure $f -translation binary \fBchan seek\fR $f -10 end set data [chan read $f 10] chan close $f .CE .PP Read a line from a file channel only if it starts with \fBfoobar\fR: .PP .CS # Save the offset in case we need to undo the read... set offset [\fBtell\fR $chan] if {[read $chan 6] eq "foobar"} { gets $chan line } else { set line {} # Undo the read... seek $chan $offset } .CE .SS "ENCODING ERROR EXAMPLES" .PP The example below illustrates handling of an encoding error encountered during channel input. First, creation of a test file containing the invalid UTF-8 sequence (\fBA \\xC3 B\fR): .PP .CS % set f [open test_A_195_B.txt wb]; chan puts -nonewline $f A\\xC3B; chan close $f .CE .PP An attempt to read the file will result in an encoding error which is then introspected by switching the channel to binary mode. Note in the example that when the error is reported the file position remains unchanged so that the \fBchan gets\fR during recovery returns the full line. .PP .CS % set f [open test_A_195_B.txt r] file384b6a8 % chan configure $f -encoding utf-8 -profile strict % catch {chan gets $f} e d 1 % set d -code 1 -level 0 -errorstack {INNER {invokeStk1 gets file384b6a8}} -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} -errorinfo {...} -errorline 1 % chan tell $f 0 % chan configure $f -encoding binary -profile strict % chan gets $f AÃB .CE .PP The following example is similar to the above but demonstrates recovery after a blocking read. The successfully decoded data "A" is returned in the error options dictionary key \fB\-data\fR. The file position is advanced on the encoding error position 1. The data at the error position is thus recovered by the next \fBchan read\fR command. .PP .CS % set f [open test_A_195_B.txt r] file35a65a0 % chan configure $f -encoding utf-8 -profile strict -blocking 1 % catch {chan read $f} e d 1 % set d -data A -code 1 -level 0 -errorstack {INNER {invokeStk1 read file35a65a0}} -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} -errorinfo {...} -errorline 1 % chan tell $f 1 % chan configure $f -encoding binary -profile strict % chan read $f ÃB % chan close $f .CE .PP Finally the same example, but this time with a non-blocking channel. .PP .CS % set f [open test_A_195_B.txt r] file35a65a0 % chan configure $f -encoding utf-8 -profile strict -blocking 0 % chan read $f A % chan tell $f 1 % catch {chan read $f} e d 1 % set d -code 1 -level 0 -errorstack {INNER {invokeStk1 read file384b228}} -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} -errorinfo {...} -errorline 1 .CE .SS "CHANNEL COPY EXAMPLES" .PP The first example transfers the contents of one channel exactly to another. Note that when copying one file to another, it is better to use \fBfile copy\fR which also copies file metadata (e.g. the file access permissions) where possible. .PP |
︙ | ︙ | |||
754 755 756 757 758 759 760 | \fBchan copy\fR $sok1 $sok2 -command [list Done UP] \fBchan copy\fR $sok2 $sok1 -command [list Done DOWN] vwait done .CE .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), | | > > | | 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 | \fBchan copy\fR $sok1 $sok2 -command [list Done UP] \fBchan copy\fR $sok2 $sok1 -command [list Done DOWN] vwait done .CE .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), socket(n), tell(n), refchan(n), transchan(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, end of file, events, input, non-blocking, offset, output, readable, seek, stdio, tell, writable '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/close.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME close \- Close an open channel .SH SYNOPSIS \fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | | < < | < < | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME close \- Close an open channel .SH SYNOPSIS \fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP The \fBclose\fR command has been superceded by the \fBchan close\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/eof.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME eof \- Check for end of file condition on channel .SH SYNOPSIS \fBeof \fIchannelId\fR .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < | < < < < < < < < < < | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME eof \- Check for end of file condition on channel .SH SYNOPSIS \fBeof \fIchannelId\fR .BE .SH DESCRIPTION .PP The \fBeof\fR command has been superceded by the \fBchan eof\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/fblocked.n.
︙ | ︙ | |||
10 11 12 13 14 15 16 | .SH NAME fblocked \- Test whether the last input operation exhausted all available input .SH SYNOPSIS \fBfblocked \fIchannelId\fR .BE .SH DESCRIPTION .PP | | < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | .SH NAME fblocked \- Test whether the last input operation exhausted all available input .SH SYNOPSIS \fBfblocked \fIchannelId\fR .BE .SH DESCRIPTION .PP The \fBfblocked\fR command has been superceded by the \fBchan blocked\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/fconfigure.n.
︙ | ︙ | |||
15 16 17 18 19 20 21 | \fBfconfigure \fIchannelId\fR \fBfconfigure \fIchannelId name\fR \fBfconfigure \fIchannelId name value \fR?\fIname value ...\fR? .fi .BE .SH DESCRIPTION .PP | | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < | 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | \fBfconfigure \fIchannelId\fR \fBfconfigure \fIchannelId name\fR \fBfconfigure \fIchannelId name value \fR?\fIname value ...\fR? .fi .BE .SH DESCRIPTION .PP The \fBfconfigure\fR command has been superceded by the \fBchan configure\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" End: |
Changes to doc/fileevent.n.
︙ | ︙ | |||
15 16 17 18 19 20 21 | .SH SYNOPSIS \fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR? .sp \fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR? .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < | < | 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | .SH SYNOPSIS \fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR? .sp \fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR? .BE .SH DESCRIPTION .PP The \fBfileevent\fR command has been superceded by the \fBchan event\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/flush.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME flush \- Flush buffered output for a channel .SH SYNOPSIS \fBflush \fIchannelId\fR .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < < < < < < | < < < > < < | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME flush \- Flush buffered output for a channel .SH SYNOPSIS \fBflush \fIchannelId\fR .BE .SH DESCRIPTION .PP The \fBflush\fR command has been superceded by the \fBchan flush\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/gets.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME gets \- Read a line from a channel .SH SYNOPSIS \fBgets \fIchannelId\fR ?\fIvarName\fR? .BE .SH DESCRIPTION .PP | | < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME gets \- Read a line from a channel .SH SYNOPSIS \fBgets \fIchannelId\fR ?\fIvarName\fR? .BE .SH DESCRIPTION .PP The \fBgets\fR command has been superceded by the \fBchan gets\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/puts.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME puts \- Write to a channel .SH SYNOPSIS \fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < | < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME puts \- Write to a channel .SH SYNOPSIS \fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR .BE .SH DESCRIPTION .PP The \fBputs\fR command has been superceded by the \fBchan puts\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/read.n.
︙ | ︙ | |||
14 15 16 17 18 19 20 | .SH SYNOPSIS \fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR .sp \fBread \fIchannelId numChars\fR .BE .SH DESCRIPTION .PP | | < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | .SH SYNOPSIS \fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR .sp \fBread \fIchannelId numChars\fR .BE .SH DESCRIPTION .PP The \fBread\fR command has been superceded by the \fBchan read\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\"Local Variables: '\"mode: nroff '\"End: |
Changes to doc/seek.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME seek \- Change the access position for an open channel .SH SYNOPSIS \fBseek \fIchannelId offset \fR?\fIorigin\fR? .BE .SH DESCRIPTION .PP | < < < < < | < < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < > | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME seek \- Change the access position for an open channel .SH SYNOPSIS \fBseek \fIchannelId offset \fR?\fIorigin\fR? .BE .SH DESCRIPTION .PP The \fBseek\fR command has been superceded by the \fBchan seek\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |
Changes to doc/tell.n.
︙ | ︙ | |||
12 13 14 15 16 17 18 | .SH NAME tell \- Return current access position for an open channel .SH SYNOPSIS \fBtell \fIchannelId\fR .BE .SH DESCRIPTION .PP | < < < < < < < < < < < < < < < < < | < < < < < < < < > < < | | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | .SH NAME tell \- Return current access position for an open channel .SH SYNOPSIS \fBtell \fIchannelId\fR .BE .SH DESCRIPTION .PP The \fBtell\fR command has been superceded by the \fBchan tell\fR command which supports the same syntax and options. .SH "SEE ALSO" chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: |