diff options
Diffstat (limited to 'doc/chan.n')
| -rw-r--r-- | doc/chan.n | 333 |
1 files changed, 251 insertions, 82 deletions
@@ -1,12 +1,10 @@ -'\" -'\" Copyright (c) 2005 Donal K. Fellows +'\" +'\" 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. -'\" -'\" RCS: @(#) $Id: chan.n,v 1.3 2006/03/17 17:24:10 andreas_kupries Exp $ -.so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -33,22 +31,35 @@ 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 +\fBchan close \fIchannelId\fR ?\fIdirection\fR? . Close and destroy the channel called \fIchannelId\fR. Note that this deletes all existing file-events registered on the channel. +.VS 8.6 +If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or +any unique abbreviation of them) is present, the channel will only be +half-closed, so that it can go from being read-write to write-only or +read-only respectively. If a read-only channel is closed for reading, it is +the same as if the channel is fully closed, and respectively similar for +write-only channels. Without the \fIdirection\fR argument, the channel is +closed for both reading and writing (but only if those directions are +currently open). It is an error to close a read-only channel for writing, or a +write-only channel for reading. +.VE 8.6 .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. +channel's output device (only if the channel is ceasing to be writable), any +buffered input is discarded (only if the channel is ceasing to be readable), +the underlying operating system resource is closed and \fIchannelId\fR becomes +unavailable for future use (both only if the channel is being completely +closed). +.PP +If the channel is blocking and the channel is ceasing to be writable, the +command does not return until all output is flushed. If the channel is +non-blocking 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. @@ -58,10 +69,12 @@ 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. +described above occur. With half-closing, the half-close of the channel only +applies to the current interpreter's view of the channel until all channels +have closed it in that direction (or completely). +See the \fBinterp\fR command for a description of channel sharing. .PP -Channels are automatically closed when an interpreter is destroyed and +Channels are automatically fully 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 @@ -69,6 +82,13 @@ 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.) +.PP +.VS 8.6 +Note that half-closes of sockets and command pipelines can have important side +effects because they result in a shutdown() or close() of the underlying +system resource, which can change how other processes or systems respond to +the Tcl program. +.VE 8.6 .RE .TP \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... @@ -87,20 +107,21 @@ the command sets each of the named options to the corresponding .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. +the manual entry for the command that creates each type of channel +for the options supported by that specific type of channel. For +example, see the manual entry for the \fBsocket\fR command for additional +options for sockets, and the \fBopen\fR command for additional options for +serial devices. .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 +blocking mode; if a channel is placed into non-blocking 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 +documentation for those commands for details. For non-blocking 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). @@ -173,10 +194,13 @@ 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 +\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 @@ -184,11 +208,11 @@ 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\fP and \fBchan read\fP) the Tcl I/O system +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\fP), the I/O +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\fP, handles all the common cases +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 @@ -206,8 +230,8 @@ currently supported: \fBauto\fR . As the input translation mode, \fBauto\fR treats any of newline -(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by -a newline (\fBcrlf\fP) as the end of line representation. The end of +(\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 @@ -216,10 +240,10 @@ all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR for both input and output. .TP -\fBbinary\fR +\fBbinary\fR . No end-of-line translations are performed. This is nearly identical -to \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets +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 @@ -229,17 +253,17 @@ information. . 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\fP mode converts carriage returns to newline characters. As the -output translation mode, \fBcr\fP mode translates newline characters +\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\fP mode converts +input translation mode, \fBcrlf\fR mode converts carriage-return-linefeed sequences to newline characters. As the -output translation mode, \fBcrlf\fP mode translates newline characters +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 @@ -262,38 +286,42 @@ buffering too much data in main memory when copying large files to slow destinations like network sockets. .RS .PP -The \fBchan copy\fP command transfers data from \fIinputChan\fR until -end of file or \fIsize\fP bytes have been transferred. If no -\fB\-size\fP 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\fP option, \fBchan copy\fP blocks until the -copy is complete and returns the number of bytes written to -\fIoutputChan\fR. -.PP -The \fB\-command\fP argument makes \fBchan copy\fP work in the +The \fBchan copy\fR command transfers data from \fIinputChan\fR until +end of file or \fIsize\fR bytes or characters have been transferred; +\fIsize\fR is in bytes if the two channels are using the same encoding, +and is in characters otherwise. 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 or characters (using the same +rules as for the \fB\-size\fR option) 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\fP is invoked later when the copy completes. The -\fIcallback\fP is called with one or two additional arguments that +\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\fP command takes care of that +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\fP command or by using Tk. +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\fP made. If \fIinputChan\fR is closed, then all data already +\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\fP or \fBfileevent\fR +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\fP handler will get a "channel busy" error. +\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 @@ -301,8 +329,8 @@ 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\fP or as the argument -to the callback for an asynchronous \fBchan copy\fP. +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 @@ -325,21 +353,26 @@ 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 +\fBrefchan\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 "\fBread\fR" or "\fBwrite\fR". The list must have at least one +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 +\fBrefchan\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 @@ -352,7 +385,7 @@ 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 invokations of the handler are forwarded to the original +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 @@ -368,7 +401,7 @@ commands. 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 +with or moved into, and in whatever thread they have been transferred 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 @@ -384,7 +417,7 @@ within the safe interpreter. . 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-fo-file was reached, and 0 otherwise. +returning 1 if end-of-file was reached, and 0 otherwise. .TP \fBchan event \fIchannelId event\fR ?\fIscript\fR? . @@ -410,9 +443,11 @@ 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 ``freeze up''. With \fBchan event\fR, the +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 won't block. +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 @@ -420,7 +455,7 @@ 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 +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 @@ -435,12 +470,12 @@ 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 +non-blocking 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 +In non-blocking 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 @@ -460,7 +495,7 @@ is written. .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 +channel is in non-blocking 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. @@ -483,7 +518,7 @@ 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 +the partial-line-but-non-blocking case can be distinguished with the \fBchan blocked\fR command. .RE .TP @@ -493,16 +528,61 @@ 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 postevent \fIchannel eventspec\fR +\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 pipe\fR +.VS 8.6 +Creates a standalone pipe whose read- and write-side channels are +returned as a 2-element list, the first element being the read side and +the second the write side. Can be useful e.g. to redirect +separately \fBstderr\fR and \fBstdout\fR from a subprocess. To do +this, spawn with "2>@" or +">@" redirection operators onto the write side of a pipe, and then +immediately close it in the parent. This is necessary to get an EOF on +the read side once the child has exited or otherwise closed its output. +.RS +.PP +Note that the pipe buffering semantics can vary at the operating system level +substantially; it is not safe to assume that a write performed on the output +side of the pipe will appear instantly to the input side. This is a +fundamental difference and Tcl cannot conceal it. The overall stream semantics +\fIare\fR compatible, so blocking reads and writes will not see most of the +differences, but the details of what exactly gets written when are not. This +is most likely to show up when using pipelines for testing; care should be +taken to ensure that deadlocks do not occur and that potential short reads are +allowed for. +.RE +.VE 8.6 +.TP +\fBchan pop \fIchannelId\fR +.VS 8.6 +Removes the topmost transformation from the channel \fIchannelId\fR, if there +is any. If there are no transformations added to \fIchannelId\fR, this is +equivalent to \fBchan close\fR of that channel. The result is normally the +empty string, but can be an error in some situations (i.e. where the +underlying system stream is closed and that results in an error). +.VE 8.6 +.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 -\fIchannel\fR that the event(s) listed in the \fIeventspec\fR have +\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 +\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. @@ -517,7 +597,7 @@ other interpreter will cause this subcommand to report an error. 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 +\fBwatch\fR described in \fBrefchan\fR, the document specifying the API of command handlers for reflected channels. .PP This command is \fBsafe\fR and made accessible to safe interpreters. @@ -528,6 +608,18 @@ a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR executed in the interpreter that set them up. .RE .TP +\fBchan push \fIchannelId cmdPrefix\fR +.VS 8.6 +Adds a new transformation on top of the channel \fIchannelId\fR. The +\fIcmdPrefix\fR argument describes a list of one or more words which represent +a handler that will be used to implement the transformation. The command +prefix must provide the API described in the \fBtranschan\fR manual page. +The result of this subcommand is a handle to the transformation. Note that it +is important to make sure that the transformation is capable of supporting the +channel mode that it is used with or this can make the channel neither +readable nor writable. +.VE 8.6 +.TP \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR . Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a @@ -552,18 +644,18 @@ 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 +output by the operating system. If \fIchannelId\fR is in non-blocking 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 +Tcl event loop for non-blocking 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 +a channel in non-blocking mode, which could consume a large amount of +memory. To avoid wasting memory, non-blocking I/O should normally be used in an event-driven fashion with the \fBchan event\fR command -(don't invoke \fBchan puts\fR unless you have recently been notified +(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 @@ -581,7 +673,7 @@ 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 +If \fIchannelId\fR is in non-blocking 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 @@ -597,21 +689,23 @@ 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: +the serial port channel to be non-blocking, like this: +.PP .CS \fBchan configure \fIchannelId \fB\-blocking \fI0\fR. .CE +.PP 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 +\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 +\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 @@ -648,7 +742,7 @@ position after the end of file. 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 +command returns, even if the channel is in non-blocking 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. @@ -673,9 +767,84 @@ 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 EXAMPLES +.PP +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 +.PP +A network server that does echoing of 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} { + \fBchan puts\fR stdout $message +} + +# This is called whenever a new client connects to the server +proc connect {chan host port} { + set clientName [format <%s:%d> $host $port] + log "connection from $clientName" + \fBchan configure\fR $chan -blocking 0 -buffering line + \fBchan event\fR $chan readable [list echoLine $chan $clientName] +} + +# This is called whenever either at least one byte of input +# data is available, or the channel was closed by the client. +proc echoLine {chan clientName} { + \fBchan gets\fR $chan line + if {[\fBchan eof\fR $chan]} { + log "finishing connection from $clientName" + \fBchan close\fR $chan + } elseif {![\fBchan blocked\fR $chan]} { + # Didn't block waiting for end-of-line + log "$clientName - $line" + \fBchan puts\fR $chan $line + } +} + +# Create the server socket and enter the event-loop to wait +# for incoming connections... +socket -server connect 12345 +vwait forever +.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), reflectedchan(n) +socket(n), tell(n), refchan(n), transchan(n) .SH KEYWORDS channel, input, output, events, offset +'\" Local Variables: +'\" mode: nroff +'\" End: |