diff options
Diffstat (limited to 'doc/chan.n')
| -rw-r--r-- | doc/chan.n | 557 |
1 files changed, 513 insertions, 44 deletions
@@ -4,7 +4,7 @@ '\" 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.1 2005/06/06 23:45:41 dkf Exp $ +'\" RCS: @(#) $Id: chan.n,v 1.2 2005/06/10 15:22:43 dkf Exp $ .so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -19,73 +19,463 @@ chan \- Read, write and manipulate channels .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). \fIOption\fR indicates -what to do with the channel; any unique abbreviation for \fIoption\fR -is acceptable. Valid options are: +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 -Test whether the last input operation on the channel called +. +This tests whether the last input operation on the channel called \fIchannelId\fR failed because it would have otherwise caused the -process to block. +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 outpuot 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 (see \fBfconfigure\fR for details). -'\" FIXME: describe common channel options here and refer to creator -'\" commands for special option descriptions. -.TP -\fBchan copy \fIinput output\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? -Copy the contents of the channel \fIinput\fR, which must have been -opened for reading, to the channel \fIoutput\fR, which must have been -opened for writing. If \fIsize\fR is specified, only that many bytes -will be transferred. If \fIcallback\fR is specified, this command -returns immediately and arranges for \fIcallback\fR to be called when -the requested transfer has completed or an error occurs (assuming that -the event loop is running) with extra arguments appended to -\fIcallback\fR to indicate what happened. +\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. +.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\fP and \fBchan read\fP) 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 +system translates newlines to the external end-of-line representation. +The default translation mode, \fBauto\fP, 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\fP), carriage return (\fBcr\fP), or carriage return followed by +a newline (\fBcrlf\fP) 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\fP mode, except that in addition \fBbinary\fP 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\fP mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fP 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 +carriage-return-linefeed sequences to newline characters. As the +output translation mode, \fBcrlf\fP 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\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 +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 +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 +automatically. However, it is necessary to enter the event loop by +using the \fBvwait\fP 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 +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 +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. +.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\fP or as the argument +to the callback for an asynchronous \fBchan copy\fP. +.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 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. +\fIchannelId\fR failed because the end of the data stream was reached, +returning 1 if end-fo-file was reached, and 0 otherwise. .TP -\fBchan event \fIchannelId mode\fR ?\fIscript\fR? -Arrange for the Tcl script \fIscript\fR to be called whenever the -channel called \fIchannelId\fR enters the state described by -\fImode\fR (which must be either \fBreadable\fR or \fBwritable\fR). If -\fIscript\fR is omitted, the currently installed script is returned. -The callback is only performed if the event loop is being serviced. +\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 ``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. +.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 a 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 error. 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 an error -occurred. +. +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 puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR -Writes \fIstring\fR to the channel named \fIchannelId\fR (by default, -to the standard output stream) followed by a newline character. If the -optional flag \fB\-nonewline\fR is given, no trailing newline -character is written. +. +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 +(don't 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 @@ -94,21 +484,100 @@ 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 position within the underlying data stream for the -channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to -\fIorigin\fR. \fIOrigin\fR should be one of \fBstart\fR (the default -origin), \fBcurrent\fR or \fBend\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 -Reports the current byte offset within the underlying data stream for -the channel named \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). +offset within the underlying data stream if \fIlength\fR is +omitted). The channel is flushed before truncation. .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), |