diff options
Diffstat (limited to 'doc/chan.n')
| -rw-r--r-- | doc/chan.n | 736 |
1 files changed, 736 insertions, 0 deletions
diff --git a/doc/chan.n b/doc/chan.n new file mode 100644 index 0000000..f5d3d54 --- /dev/null +++ b/doc/chan.n @@ -0,0 +1,736 @@ +'\" +'\" Copyright (c) 2005-2006 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +.so man.macros +.TH chan n 8.5 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +chan \- Read, write and manipulate channels +.SH SYNOPSIS +\fBchan \fIoption\fR ?\fIarg arg ...\fR? +.BE +.SH DESCRIPTION +.PP +This command provides several operations for reading from, writing to +and otherwise manipulating open channels (such as have been created +with the \fBopen\fR and \fBsocket\fR commands, or the default named +channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to +the process's standard input, output and error streams respectively). +\fIOption\fR indicates what to do with the channel; any unique +abbreviation for \fIoption\fR is acceptable. Valid options are: +.TP +\fBchan blocked \fIchannelId\fR +. +This tests whether the last input operation on the channel called +\fIchannelId\fR failed because it would have otherwise caused the +process to block, and returns 1 if that was the case. It returns 0 +otherwise. Note that this only ever returns 1 when the channel has +been configured to be non-blocking; all Tcl channels have blocking +turned on by default. +.TP +\fBchan close \fIchannelId\fR +. +Close and destroy the channel called \fIchannelId\fR. Note that this +deletes all existing file-events registered on the channel. +.RS +.PP +As part of closing the channel, all buffered output is flushed to the +channel's output device, any buffered input is discarded, the +underlying operating system resource is closed and \fIchannelId\fR +becomes unavailable for future use. +.PP +If the channel is blocking, the command does not return until all +output is flushed. If the channel is nonblocking and there is +unflushed output, the channel remains open and the command returns +immediately; output will be flushed in the background and the channel +will be closed when all the flushing is complete. +.PP +If \fIchannelId\fR is a blocking channel for a command pipeline then +\fBchan close\fR waits for the child processes to complete. +.PP +If the channel is shared between interpreters, then \fBchan close\fR +makes \fIchannelId\fR unavailable in the invoking interpreter but has +no other effect until all of the sharing interpreters have closed the +channel. When the last interpreter in which the channel is registered +invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions +described above occur. See the \fBinterp\fR command for a description +of channel sharing. +.PP +Channels are automatically closed when an interpreter is destroyed and +when the process exits. Channels are switched to blocking mode, to +ensure that all output is correctly flushed before the process exits. +.PP +The command returns an empty string, and may generate an error if +an error occurs while flushing output. If a command in a command +pipeline created with \fBopen\fR returns an error, \fBchan close\fR +generates an error (similar to the \fBexec\fR command.) +.RE +.TP +\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... +. +Query or set the configuration options of the channel named +\fIchannelId\fR. +.RS +.PP +If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the +command returns a list containing alternating option names and values +for the channel. If \fIoptionName\fR is supplied but no \fIvalue\fR +then the command returns the current value of the given option. If +one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, +the command sets each of the named options to the corresponding +\fIvalue\fR; in this case the return value is an empty string. +.PP +The options described below are supported for all channels. In +addition, each channel type may add options that only it supports. See +the manual entry for the command that creates each type of channels +for the options that that specific type of channel supports. For +example, see the manual entry for the \fBsocket\fR command for its +additional options. +.TP +\fB\-blocking\fR \fIboolean\fR +. +The \fB\-blocking\fR option determines whether I/O operations on the +channel can cause the process to block indefinitely. The value of the +option must be a proper boolean value. Channels are normally in +blocking mode; if a channel is placed into nonblocking mode it will +affect the operation of the \fBchan gets\fR, \fBchan read\fR, \fBchan +puts\fR, \fBchan flush\fR, and \fBchan close\fR commands; see the +documentation for those commands for details. For nonblocking mode to +work correctly, the application must be using the Tcl event loop +(e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR +command). +.TP +\fB\-buffering\fR \fInewValue\fR +. +If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output +until its internal buffer is full or until the \fBchan flush\fR +command is invoked. If \fInewValue\fR is \fBline\fR, then the I/O +system will automatically flush output for the channel whenever a +newline character is output. If \fInewValue\fR is \fBnone\fR, the I/O +system will flush automatically after every output operation. The +default is for \fB\-buffering\fR to be set to \fBfull\fR except for +channels that connect to terminal-like devices; for these channels the +initial setting is \fBline\fR. Additionally, \fBstdin\fR and +\fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set +to \fBnone\fR. +.TP +\fB\-buffersize\fR \fInewSize\fR +. +\fINewvalue\fR must be an integer; its value is used to set the size +of buffers, in bytes, subsequently allocated for this channel to store +input or output. \fINewvalue\fR must be a number of no more than one +million, allowing buffers of up to one million bytes in size. +.TP +\fB\-encoding\fR \fIname\fR +. +This option is used to specify the encoding of the channel as one of +the named encodings returned by \fBencoding names\fR or the special +value \fBbinary\fR, so that the data can be converted to and from +Unicode for use in Tcl. For instance, in order for Tcl to read +characters from a Japanese file in \fBshiftjis\fR and properly process +and display the contents, the encoding would be set to \fBshiftjis\fR. +Thereafter, when reading from the channel, the bytes in the Japanese +file would be converted to Unicode as they are read. Writing is also +supported \- as Tcl strings are written to the channel they will +automatically be converted to the specified encoding on output. +.RS +.PP +If a file contains pure binary data (for instance, a JPEG image), the +encoding for the channel should be configured to be \fBbinary\fR. Tcl +will then assign no interpretation to the data in the file and simply +read or write raw bytes. The Tcl \fBbinary\fR command can be used to +manipulate this byte-oriented data. It is usually better to set the +\fB\-translation\fR option to \fBbinary\fR when you want to transfer +binary data, as this turns off the other automatic interpretations of +the bytes in the stream as well. +.PP +The default encoding for newly opened channels is the same platform- +and locale-dependent system encoding used for interfacing with the +operating system, as returned by \fBencoding system\fR. +.RE +.TP +\fB\-eofchar\fR \fIchar\fR +.TP +\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR +. +This option supports DOS file systems that use Control-z (\ex1a) as an +end of file marker. If \fIchar\fR is not an empty string, then this +character signals end-of-file when it is encountered during input. +For output, the end-of-file character is output when the channel is +closed. If \fIchar\fR is the empty string, then there is no special +end of file character marker. For read-write channels, a two-element +list specifies the end of file marker for input and output, +respectively. As a convenience, when setting the end-of-file +character for a read-write channel you can specify a single value that +will apply to both reading and writing. When querying the end-of-file +character of a read-write channel, a two-element list will always be +returned. The default value for \fB\-eofchar\fR is the empty string +in all cases except for files under Windows. In that case the +\fB\-eofchar\fR is Control-z (\ex1a) for reading and the empty string +for writing. +The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f; +attempting to set \fB\-eofchar\fR to a value outside of this range will +generate an error. +.TP +\fB\-translation\fR \fImode\fR +.TP +\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR +. +In Tcl scripts the end of a line is always represented using a single +newline character (\en). However, in actual files and devices the end +of a line may be represented differently on different platforms, or +even for different devices on the same platform. For example, under +UNIX newlines are used in files, whereas carriage-return-linefeed +sequences are normally used in network connections. On input (i.e., +with \fBchan gets\fR and \fBchan read\fR) the Tcl I/O system +automatically translates the external end-of-line representation into +newline characters. Upon output (i.e., with \fBchan puts\fR), the I/O +system translates newlines to the external end-of-line representation. +The default translation mode, \fBauto\fR, handles all the common cases +automatically, but the \fB\-translation\fR option provides explicit +control over the end of line translations. +.RS +.PP +The value associated with \fB\-translation\fR is a single item for +read-only and write-only channels. The value is a two-element list for +read-write channels; the read translation mode is the first element of +the list, and the write translation mode is the second element. As a +convenience, when setting the translation mode for a read-write channel +you can specify a single value that will apply to both reading and +writing. When querying the translation mode of a read-write channel, a +two-element list will always be returned. The following values are +currently supported: +.TP +\fBauto\fR +. +As the input translation mode, \fBauto\fR treats any of newline +(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by +a newline (\fBcrlf\fR) as the end of line representation. The end of +line representation can even change from line-to-line, and all cases +are translated to a newline. As the output translation mode, +\fBauto\fR chooses a platform specific representation; for sockets on +all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses +\fBlf\fR, and for the various flavors of Windows it chooses +\fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR +for both input and output. +.TP +\fBbinary\fR +. +No end-of-line translations are performed. This is nearly identical +to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets +the end-of-file character to the empty string (which disables it) and +sets the encoding to \fBbinary\fR (which disables encoding filtering). +See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more +information. +.TP +\fBcr\fR +. +The end of a line in the underlying file or device is represented by a +single carriage return character. As the input translation mode, +\fBcr\fR mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fR mode translates newline characters +to carriage returns. +.TP +\fBcrlf\fR +. +The end of a line in the underlying file or device is represented by a +carriage return character followed by a linefeed character. As the +input translation mode, \fBcrlf\fR mode converts +carriage-return-linefeed sequences to newline characters. As the +output translation mode, \fBcrlf\fR mode translates newline characters +to carriage-return-linefeed sequences. This mode is typically used on +Windows platforms and for network connections. +.TP +\fBlf\fR +. +The end of a line in the underlying file or device is represented by a +single newline (linefeed) character. In this mode no translations +occur during either input or output. This mode is typically used on +UNIX platforms. +.RE +.RE +.TP +\fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? +. +Copy data from the channel \fIinputChan\fR, which must have been +opened for reading, to the channel \fIoutputChan\fR, which must have +been opened for writing. The \fBchan copy\fR command leverages the +buffering in the Tcl I/O system to avoid extra copies and to avoid +buffering too much data in main memory when copying large files to +slow destinations like network sockets. +.RS +.PP +The \fBchan copy\fR command transfers data from \fIinputChan\fR until +end of file or \fIsize\fR bytes have been transferred. If no +\fB\-size\fR argument is given, then the copy goes until end of file. +All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR. +Without the \fB\-command\fR option, \fBchan copy\fR blocks until the +copy is complete and returns the number of bytes written to +\fIoutputChan\fR. +.PP +The \fB\-command\fR argument makes \fBchan copy\fR work in the +background. In this case it returns immediately and the +\fIcallback\fR is invoked later when the copy completes. The +\fIcallback\fR is called with one or two additional arguments that +indicates how many bytes were written to \fIoutputChan\fR. If an +error occurred during the background copy, the second argument is the +error string associated with the error. With a background copy, it is +not necessary to put \fIinputChan\fR or \fIoutputChan\fR into +non-blocking mode; the \fBchan copy\fR command takes care of that +automatically. However, it is necessary to enter the event loop by +using the \fBvwait\fR command or by using Tk. +.PP +You are not allowed to do other I/O operations with \fIinputChan\fR or +\fIoutputChan\fR during a background \fBchan copy\fR. If either +\fIinputChan\fR or \fIoutputChan\fR get closed while the copy is in +progress, the current copy is stopped and the command callback is +\fInot\fR made. If \fIinputChan\fR is closed, then all data already +queued for \fIoutputChan\fR is written out. +.PP +Note that \fIinputChan\fR can become readable during a background +copy. You should turn off any \fBchan event\fR or \fBfileevent\fR +handlers during a background copy so those handlers do not interfere +with the copy. Any I/O attempted by a \fBchan event\fR or +\fBfileevent\fR handler will get a +.QW "channel busy" +error. +.PP +\fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR +and \fIoutputChan\fR according to the \fB\-translation\fR option for +these channels (see \fBchan configure\fR above). The translations +mean that the number of bytes read from \fIinputChan\fR can be +different than the number of bytes written to \fIoutputChan\fR. Only +the number of bytes written to \fIoutputChan\fR is reported, either as +the return value of a synchronous \fBchan copy\fR or as the argument +to the callback for an asynchronous \fBchan copy\fR. +.PP +\fBChan copy\fR obeys the encodings and character translations +configured for the channels. This means that the incoming characters +are converted internally first UTF-8 and then into the encoding of the +channel \fBchan copy\fR writes to (see \fBchan configure\fR above for +details on the \fB\-encoding\fR and \fB\-translation\fR options). No +conversion is done if both channels are set to encoding \fBbinary\fR +and have matching translations. If only the output channel is set to +encoding \fBbinary\fR the system will write the internal UTF-8 +representation of the incoming characters. If only the input channel +is set to encoding \fBbinary\fR the system will assume that the +incoming bytes are valid UTF-8 characters and convert them according +to the output encoding. The behaviour of the system for bytes which +are not valid UTF-8 characters is undefined in this case. +.RE +.TP +\fBchan create \fImode cmdPrefix\fR +. +This subcommand creates a new script level channel using the command +prefix \fIcmdPrefix\fR as its handler. Any such channel is called a +\fBreflected\fR channel. The specified command prefix, \fBcmdPrefix\fR, +must be a non-empty list, and should provide the API described in the +\fBreflectedchan\fR manual page. The handle of the new channel is +returned as the result of the \fBchan create\fR command, and the +channel is open. Use either \fBclose\fR or \fBchan close\fR to remove +the channel. +.RS +.PP +The argument \fImode\fR specifies if the new channel is opened for +reading, writing, or both. It has to be a list containing any of the +strings +.QW \fBread\fR +or +.QW \fBwrite\fR . +The list must have at least one +element, as a channel you can neither write to nor read from makes no +sense. The handler command for the new channel must support the chosen +mode, or an error is thrown. +.PP +The command prefix is executed in the global namespace, at the top of +call stack, following the appending of arguments as described in the +\fBreflectedchan\fR manual page. Command resolution happens at the +time of the call. Renaming the command, or destroying it means that +the next call of a handler method may fail, causing the channel +command invoking the handler to fail as well. Depending on the +subcommand being invoked, the error message may not be able to explain +the reason for that failure. +.PP +Every channel created with this subcommand knows which interpreter it +was created in, and only ever executes its handler command in that +interpreter, even if the channel was shared with and/or was moved into +a different interpreter. Each reflected channel also knows the thread +it was created in, and executes its handler command only in that +thread, even if the channel was moved into a different thread. To this +end all invocations of the handler are forwarded to the original +thread by posting special events to it. This means that the original +thread (i.e. the thread that executed the \fBchan create\fR command) +must have an active event loop, i.e. it must be able to process such +events. Otherwise the thread sending them will \fIblock +indefinitely\fR. Deadlock may occur. +.PP +Note that this permits the creation of a channel whose two endpoints +live in two different threads, providing a stream-oriented bridge +between these threads. In other words, we can provide a way for +regular stream communication between threads instead of having to send +commands. +.PP +When a thread or interpreter is deleted, all channels created with +this subcommand and using this thread/interpreter as their computing +base are deleted as well, in all interpreters they have been shared +with or moved into, and in whatever thread they have been transfered +to. While this pulls the rug out under the other thread(s) and/or +interpreter(s), this cannot be avoided. Trying to use such a channel +will cause the generation of a regular error about unknown channel +handles. +.PP +This subcommand is \fBsafe\fR and made accessible to safe +interpreters. While it arranges for the execution of arbitrary Tcl +code the system also makes sure that the code is always executed +within the safe interpreter. +.RE +.TP +\fBchan eof \fIchannelId\fR +. +Test whether the last input operation on the channel called +\fIchannelId\fR failed because the end of the data stream was reached, +returning 1 if end-of-file was reached, and 0 otherwise. +.TP +\fBchan event \fIchannelId event\fR ?\fIscript\fR? +. +Arrange for the Tcl script \fIscript\fR to be installed as a \fIfile +event handler\fR to be called whenever the channel called +\fIchannelId\fR enters the state described by \fIevent\fR (which must +be either \fBreadable\fR or \fBwritable\fR); only one such handler may +be installed per event per channel at a time. If \fIscript\fR is the +empty string, the current handler is deleted (this also happens if the +channel is closed or the interpreter deleted). If \fIscript\fR is +omitted, the currently installed script is returned (or an empty +string if no such handler is installed). The callback is only +performed if the event loop is being serviced (e.g. via \fBvwait\fR or +\fBupdate\fR). +.RS +.PP +A file event handler is a binding between a channel and a script, such +that the script is evaluated whenever the channel becomes readable or +writable. File event handlers are most commonly used to allow data to +be received from another process on an event-driven basis, so that the +receiver can continue to interact with the user or with other channels +while waiting for the data to arrive. If an application invokes +\fBchan gets\fR or \fBchan read\fR on a blocking channel when there is +no input data available, the process will block; until the input data +arrives, it will not be able to service other events, so it will +appear to the user to +.QW "freeze up" . +With \fBchan event\fR, the +process can tell when data is present and only invoke \fBchan gets\fR +or \fBchan read\fR when they will not block. +.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 nonblocking 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 on the underlying file or device. +Note that client sockets opened in asynchronous mode become writable +when they become connected or if the connection fails. +.PP +Event-driven I/O works best for channels that have been placed into +nonblocking mode with the \fBchan configure\fR command. In blocking +mode, a \fBchan puts\fR command may block if you give it more data +than the underlying file or device can accept, and a \fBchan gets\fR +or \fBchan read\fR command will block if you attempt to read more data +than is ready; no events will be processed while the commands block. +In nonblocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan +gets\fR never block. +.PP +The script for a file event is executed at global level (outside the +context of any Tcl procedure) in the interpreter in which the \fBchan +event\fR command was invoked. If an error occurs while executing the +script then the command registered with \fBinterp bgerror\fR is used +to report the error. In addition, the file event handler is deleted +if it ever returns an error; this is done in order to prevent infinite +loops due to buggy handlers. +.RE +.TP +\fBchan flush \fIchannelId\fR +. +Ensures that all pending output for the channel called \fIchannelId\fR +is written. +.RS +.PP +If the channel is in blocking mode the command does not return until +all the buffered output has been flushed to the channel. If the +channel is in nonblocking mode, the command may return before all +buffered output has been flushed; the remainder will be flushed in the +background as fast as the underlying file or device is able to absorb +it. +.RE +.TP +\fBchan gets \fIchannelId\fR ?\fIvarName\fR? +. +Reads the next line from the channel called \fIchannelId\fR. If +\fIvarName\fR is not specified, the result of the command will be the +line that has been read (without a trailing newline character) or an +empty string upon end-of-file or, in non-blocking mode, if the data +available is exhausted. If \fIvarName\fR is specified, the line that +has been read will be written to the variable called \fIvarName\fR and +result will be the number of characters that have been read or -1 if +end-of-file was reached or, in non-blocking mode, if the data +available is exhausted. +.RS +.PP +If an end-of-file occurs while part way through reading a line, the +partial line will be returned (or written into \fIvarName\fR). When +\fIvarName\fR is not specified, the end-of-file case can be +distinguished from an empty line using the \fBchan eof\fR command, and +the partial-line-but-nonblocking case can be distinguished with the +\fBchan blocked\fR command. +.RE +.TP +\fBchan names\fR ?\fIpattern\fR? +. +Produces a list of all channel names. If \fIpattern\fR is specified, +only those channel names that match it (according to the rules of +\fBstring match\fR) will be returned. +.TP +\fBchan pending \fImode channelId\fR +. +Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR, +returns the number of +bytes of input or output (respectively) currently buffered +internally for \fIchannelId\fR (especially useful in a readable event +callback to impose application-specific limits on input line lengths to avoid +a potential denial-of-service attack where a hostile user crafts +an extremely long line that exceeds the available memory to buffer it). +Returns -1 if the channel was not opened for the mode in question. +.TP +\fBchan postevent \fIchannelId eventSpec\fR +. +This subcommand is used by command handlers specified with \fBchan +create\fR. It notifies the channel represented by the handle +\fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have +occurred. The argument has to be a list containing any of the strings +\fBread\fR and \fBwrite\fR. The list must contain at least one +element as it does not make sense to invoke the command if there are +no events to post. +.RS +.PP +Note that this subcommand can only be used with channel handles that +were created/opened by \fBchan create\fR. All other channels will +cause this subcommand to report an error. +.PP +As only the Tcl level of a channel, i.e. its command handler, should +post events to it we also restrict the usage of this command to the +interpreter that created the channel. In other words, posting events +to a reflected channel from an interpreter that does not contain it's +implementation is not allowed. Attempting to post an event from any +other interpreter will cause this subcommand to report an error. +.PP +Another restriction is that it is not possible to post events that the +I/O core has not registered an interest in. Trying to do so will cause +the method to throw an error. See the command handler method +\fBwatch\fR described in \fBreflectedchan\fR, the document specifying +the API of command handlers for reflected channels. +.PP +This command is \fBsafe\fR and made accessible to safe interpreters. +It can trigger the execution of \fBchan event\fR handlers, whether in the +current interpreter or in other interpreters or other threads, even +where the event is posted from a safe interpreter and listened for by +a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR +executed in the interpreter that set them up. +.RE +.TP +\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR +. +Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a +newline character. A trailing newline character is written unless the +optional flag \fB\-nonewline\fR is given. If \fIchannelId\fR is +omitted, the string is written to the standard output channel, +\fBstdout\fR. +.RS +.PP +Newline characters in the output are translated by \fBchan puts\fR to +platform-specific end-of-line sequences according to the currently +configured value of the \fB\-translation\fR option for the channel +(for example, on PCs newlines are normally replaced with +carriage-return-linefeed sequences; see \fBchan configure\fR above for +details). +.PP +Tcl buffers output internally, so characters written with \fBchan +puts\fR may not appear immediately on the output file or device; Tcl +will normally delay output until the buffer is full or the channel is +closed. You can force output to appear immediately with the \fBchan +flush\fR command. +.PP +When the output buffer fills up, the \fBchan puts\fR command will +normally block until all the buffered data has been accepted for +output by the operating system. If \fIchannelId\fR is in nonblocking +mode then the \fBchan puts\fR command will not block even if the +operating system cannot accept the data. Instead, Tcl continues to +buffer the data and writes it in the background as fast as the +underlying file or device can accept it. The application must use the +Tcl event loop for nonblocking output to work; otherwise Tcl never +finds out that the file or device is ready for more output data. It +is possible for an arbitrarily large amount of data to be buffered for +a channel in nonblocking mode, which could consume a large amount of +memory. To avoid wasting memory, nonblocking I/O should normally be +used in an event-driven fashion with the \fBchan event\fR command +(do not invoke \fBchan puts\fR unless you have recently been notified +via a file event that the channel is ready for more output data). +.RE +.TP +\fBchan read \fIchannelId\fR ?\fInumChars\fR? +.TP +\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR +. +In the first form, the result will be the next \fInumChars\fR +characters read from the channel named \fIchannelId\fR; if +\fInumChars\fR is omitted, all characters up to the point when the +channel would signal a failure (whether an end-of-file, blocked or +other error condition) are read. In the second form (i.e. when +\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be +given to indicate that any trailing newline in the string that has +been read should be trimmed. +.RS +.PP +If \fIchannelId\fR is in nonblocking mode, \fBchan read\fR may not +read as many characters as requested: once all available input has +been read, the command will return the data that is available rather +than blocking for more input. If the channel is configured to use a +multi-byte encoding, then there may actually be some bytes remaining +in the internal buffers that do not form a complete character. These +bytes will not be returned until a complete character is available or +end-of-file is reached. The \fB\-nonewline\fR switch is ignored if +the command returns before reaching the end of the file. +.PP +\fBChan read\fR translates end-of-line sequences in the input into +newline characters according to the \fB\-translation\fR option for the +channel (see \fBchan configure\fR above for a discussion on the ways +in which \fBchan configure\fR will alter input). +.PP +When reading from a serial port, most applications should configure +the serial port channel to be nonblocking, like this: +.CS +\fBchan configure \fIchannelId \fB\-blocking \fI0\fR. +.CE +Then \fBchan read\fR behaves much like described above. Note that +most serial ports are comparatively slow; it is entirely possible to +get a \fBreadable\fR event for each character read from them. Care +must be taken when using \fBchan read\fR on blocking serial ports: +.TP +\fBchan read \fIchannelId numChars\fR +. +In this form \fBchan read\fR blocks until \fInumChars\fR have been +received from the serial port. +.TP +\fBchan read \fIchannelId\fR +. +In this form \fBchan read\fR blocks until the reception of the +end-of-file character, see \fBchan configure -eofchar\fR. If there no +end-of-file character has been configured for the channel, then +\fBchan read\fR will block forever. +.RE +.TP +\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? +. +Sets the current access position within the underlying data stream for +the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to +\fIorigin\fR. \fIOffset\fR must be an integer (which may be negative) +and \fIorigin\fR must be one of the following: +.RS +.TP 10 +\fBstart\fR +. +The new access position will be \fIoffset\fR bytes from the start +of the underlying file or device. +.TP 10 +\fBcurrent\fR +. +The new access position will be \fIoffset\fR bytes from the current +access position; a negative \fIoffset\fR moves the access position +backwards in the underlying file or device. +.TP 10 +\fBend\fR +. +The new access position will be \fIoffset\fR bytes from the end of the +file or device. A negative \fIoffset\fR places the access position +before the end of file, and a positive \fIoffset\fR places the access +position after the end of file. +.PP +The \fIorigin\fR argument defaults to \fBstart\fR. +.PP +\fBChan seek\fR flushes all buffered output for the channel before the +command returns, even if the channel is in nonblocking mode. It also +discards any buffered and unread input. This command returns an empty +string. An error occurs if this command is applied to channels whose +underlying file or device does not support seeking. +.PP +Note that \fIoffset\fR values are byte offsets, not character offsets. +Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, +not characters, unlike \fBchan read\fR. +.RE +.TP +\fBchan tell \fIchannelId\fR +. +Returns a number giving the current access position within the +underlying data stream for the channel named \fIchannelId\fR. This +value returned is a byte offset that can be passed to \fBchan seek\fR +in order to set the channel to a particular position. Note that this +value is in terms of bytes, not characters like \fBchan read\fR. The +value returned is -1 for channels that do not support seeking. +.TP +\fBchan truncate \fIchannelId\fR ?\fIlength\fR? +. +Sets the byte length of the underlying data stream for the channel +named \fIchannelId\fR to be \fIlength\fR (or to the current byte +offset within the underlying data stream if \fIlength\fR is +omitted). The channel is flushed before truncation. +.SH EXAMPLE +This opens a file using a known encoding (CP1252, a very common encoding +on Windows), searches for a string, rewrites that part, and truncates the +file after a further two lines. +.PP +.CS +set f [open somefile.txt r+] +\fBchan configure\fR $f -encoding cp1252 +set offset 0 + +\fI# Search for string "FOOBAR" in the file\fR +while {[\fBchan gets\fR $f line] >= 0} { + set idx [string first FOOBAR $line] + if {$idx > -1} { + \fI# Found it; rewrite line\fR + + \fBchan seek\fR $f [expr {$offset + $idx}] + \fBchan puts\fR -nonewline $f BARFOO + + \fI# Skip to end of following line, and truncate\fR + \fBchan gets\fR $f + \fBchan gets\fR $f + \fBchan truncate\fR $f + + \fI# Stop searching the file now\fR + break + } + + \fI# Save offset of start of next line for later\fR + set offset [\fBchan tell\fR $f] +} +\fBchan close\fR $f +.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) +.SH KEYWORDS +channel, input, output, events, offset |