On Apache
Under GNU General Public License
2024-04-25 17:21 @18.224.32.86 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
chan(n) Tcl Built-In Commands chan(n)
_________________________________________________________________________________________________
NAME
chan - Read, write and manipulate channels
SYNOPSIS
chan option ?arg arg ...?
_________________________________________________________________
DESCRIPTION
This command provides several operations for reading from, writing to and otherwise manip-
ulating open channels (such as have been created with the open and socket commands, or the
default named channels stdin, stdout or stderr which correspond to the process's standard
input, output and error streams respectively). Option indicates what to do with the chan-
nel; any unique abbreviation for option is acceptable. Valid options are:
chan blocked channelId
This tests whether the last input operation on the channel called channelId 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.
chan close channelId
Close and destroy the channel called channelId. Note that this deletes all existing
file-events registered on the channel.
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 channelId becomes unavailable for future use.
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.
If channelId is a blocking channel for a command pipeline then chan close waits for
the child processes to complete.
If the channel is shared between interpreters, then chan close makes channelId
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 chan close (or close), the cleanup actions
described above occur. See the interp command for a description of channel sharing.
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.
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 open
returns an error, chan close generates an error (similar to the exec command.)
chan configure channelId ?optionName? ?value? ?optionName value?...
Query or set the configuration options of the channel named channelId.
If no optionName or value arguments are supplied, the command returns a list con-
taining alternating option names and values for the channel. If optionName is sup-
plied but no value then the command returns the current value of the given option.
If one or more pairs of optionName and value are supplied, the command sets each of
the named options to the corresponding value; in this case the return value is an
empty string.
The options described below are supported for all channels. In addition, each chan-
nel type may add options that only it supports. See the manual entry for the com-
mand that creates each type of channels for the options that that specific type of
channel supports. For example, see the manual entry for the socket command for its
additional options.
-blocking boolean
The -blocking 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 chan
gets, chan read, chan puts, chan flush, and chan close 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
Tcl_DoOneEvent or invoking the vwait command).
-buffering newValue
If newValue is full then the I/O system will buffer output until its inter-
nal buffer is full or until the chan flush command is invoked. If newValue
is line, then the I/O system will automatically flush output for the channel
whenever a newline character is output. If newValue is none, the I/O system
will flush automatically after every output operation. The default is for
-buffering to be set to full except for channels that connect to terminal-
like devices; for these channels the initial setting is line. Additionally,
stdin and stdout are initially set to line, and stderr is set to none.
-buffersize newSize
Newvalue 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.
Newvalue must be a number of no more than one million, allowing buffers of
up to one million bytes in size.
-encoding name
This option is used to specify the encoding of the channel as one of the
named encodings returned by encoding names or the special value binary, 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
shiftjis and properly process and display the contents, the encoding would
be set to shiftjis. 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.
If a file contains pure binary data (for instance, a JPEG image), the encod-
ing for the channel should be configured to be binary. Tcl will then assign
no interpretation to the data in the file and simply read or write raw
bytes. The Tcl binary command can be used to manipulate this byte-oriented
data. It is usually better to set the -translation option to binary when
you want to transfer binary data, as this turns off the other automatic
interpretations of the bytes in the stream as well.
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 encoding system.
-eofchar char
-eofchar {inChar outChar}
This option supports DOS file systems that use Control-z (\x1a) as an end of
file marker. If char 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 char 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 char-
acter of a read-write channel, a two-element list will always be returned.
The default value for -eofchar is the empty string in all cases except for
files under Windows. In that case the -eofchar is Control-z (\x1a) for
reading and the empty string for writing. The acceptable range for -eofchar
values is \x01 - \x7f; attempting to set -eofchar to a value outside of this
range will generate an error.
-translation mode
-translation {inMode outMode}
In Tcl scripts the end of a line is always represented using a single new-
line character (\n). 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 net-
work connections. On input (i.e., with chan gets and chan read) the Tcl I/O
system automatically translates the external end-of-line representation into
newline characters. Upon output (i.e., with chan puts), the I/O system
translates newlines to the external end-of-line representation. The default
translation mode, auto, handles all the common cases automatically, but the
-translation option provides explicit control over the end of line transla-
tions.
The value associated with -translation is a single item for read-only and
write-only channels. The value is a two-element list for read-write chan-
nels; the read translation mode is the first element of the list, and the
write translation mode is the second element. As a convenience, when set-
ting 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 trans-
lation mode of a read-write channel, a two-element list will always be
returned. The following values are currently supported:
auto As the input translation mode, auto treats any of newline (lf), car-
riage return (cr), or carriage return followed by a newline (crlf) 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 new-
line. As the output translation mode, auto chooses a platform spe-
cific representation; for sockets on all platforms Tcl chooses crlf,
for all Unix flavors, it chooses lf, and for the various flavors of
Windows it chooses crlf. The default setting for -translation is
auto for both input and output.
binary No end-of-line translations are performed. This is nearly identical
to lf mode, except that in addition binary mode also sets the end-of-
file character to the empty string (which disables it) and sets the
encoding to binary (which disables encoding filtering). See the
description of -eofchar and -encoding for more information.
cr The end of a line in the underlying file or device is represented by
a single carriage return character. As the input translation mode,
cr mode converts carriage returns to newline characters. As the out-
put translation mode, cr mode translates newline characters to car-
riage returns.
crlf 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, crlf mode converts carriage-return-linefeed
sequences to newline characters. As the output translation mode,
crlf mode translates newline characters to carriage-return-linefeed
sequences. This mode is typically used on Windows platforms and for
network connections.
lf 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.
chan copy inputChan outputChan ?-size size? ?-command callback?
Copy data from the channel inputChan, which must have been opened for reading, to
the channel outputChan, which must have been opened for writing. The chan copy com-
mand 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 des-
tinations like network sockets.
The chan copy command transfers data from inputChan until end of file or size bytes
have been transferred. If no -size argument is given, then the copy goes until end
of file. All the data read from inputChan is copied to outputChan. Without the
-command option, chan copy blocks until the copy is complete and returns the number
of bytes written to outputChan.
The -command argument makes chan copy work in the background. In this case it
returns immediately and the callback is invoked later when the copy completes. The
callback is called with one or two additional arguments that indicates how many
bytes were written to outputChan. If an error occurred during the background copy,
the second argument is the error string associated with the error. With a back-
ground copy, it is not necessary to put inputChan or outputChan into non-blocking
mode; the chan copy command takes care of that automatically. However, it is nec-
essary to enter the event loop by using the vwait command or by using Tk.
You are not allowed to do other I/O operations with inputChan or outputChan during
a background chan copy. If either inputChan or outputChan get closed while the
copy is in progress, the current copy is stopped and the command callback is not
made. If inputChan is closed, then all data already queued for outputChan is writ-
ten out.
Note that inputChan can become readable during a background copy. You should turn
off any chan event or fileevent handlers during a background copy so those handlers
do not interfere with the copy. Any I/O attempted by a chan event or fileevent
handler will get a "channel busy" error.
Chan copy translates end-of-line sequences in inputChan and outputChan according to
the -translation option for these channels (see chan configure above). The trans-
lations mean that the number of bytes read from inputChan can be different than the
number of bytes written to outputChan. Only the number of bytes written to out-
putChan is reported, either as the return value of a synchronous chan copy or as
the argument to the callback for an asynchronous chan copy.
Chan copy obeys the encodings and character translations configured for the chan-
nels. This means that the incoming characters are converted internally first UTF-8
and then into the encoding of the channel chan copy writes to (see chan configure
above for details on the -encoding and -translation options). No conversion is done
if both channels are set to encoding binary and have matching translations. If only
the output channel is set to encoding binary the system will write the internal
UTF-8 representation of the incoming characters. If only the input channel is set
to encoding binary 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.
chan create mode cmdPrefix
This subcommand creates a new script level channel using the command prefix cmdPre-
fix as its handler. Any such channel is called a reflected channel. The specified
command prefix, cmdPrefix, must be a non-empty list, and should provide the API
described in the reflectedchan manual page. The handle of the new channel is
returned as the result of the chan create command, and the channel is open. Use
either close or chan close to remove the channel.
The argument mode specifies if the new channel is opened for reading, writing, or
both. It has to be a list containing any of the strings "read" or "write". 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 cho-
sen mode, or an error is thrown.
The command prefix is executed in the global namespace, at the top of call stack,
following the appending of arguments as described in the reflectedchan 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.
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 chan create command) must have an active event loop, i.e. it must
be able to process such events. Otherwise the thread sending them will block indef-
initely. Deadlock may occur.
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.
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 chan-
nel will cause the generation of a regular error about unknown channel handles.
This subcommand is safe 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.
chan eof channelId
Test whether the last input operation on the channel called channelId failed
because the end of the data stream was reached, returning 1 if end-of-file was
reached, and 0 otherwise.
chan event channelId event ?script?
Arrange for the Tcl script script to be installed as a file event handler to be
called whenever the channel called channelId enters the state described by event
(which must be either readable or writable); only one such handler may be installed
per event per channel at a time. If script is the empty string, the current han-
dler is deleted (this also happens if the channel is closed or the interpreter
deleted). If script 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 vwait or update).
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 applica-
tion invokes chan gets or chan read 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 chan event, the process can tell when data is present and only invoke chan
gets or chan read when they will not block.
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 chan gets 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 script 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 script reads no data, returns, and is immediately invoked again.
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 asyn-
chronous mode become writable when they become connected or if the connection
fails.
Event-driven I/O works best for channels that have been placed into nonblocking
mode with the chan configure command. In blocking mode, a chan puts command may
block if you give it more data than the underlying file or device can accept, and a
chan gets or chan read 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
chan puts, chan read, and chan gets never block.
The script for a file event is executed at global level (outside the context of any
Tcl procedure) in the interpreter in which the chan event command was invoked. If
an error occurs while executing the script then the command registered with interp
bgerror 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.
chan flush channelId
Ensures that all pending output for the channel called channelId is written.
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.
chan gets channelId ?varName?
Reads the next line from the channel called channelId. If varName 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 varName is specified, the line that has been
read will be written to the variable called varName 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.
If an end-of-file occurs while part way through reading a line, the partial line
will be returned (or written into varName). When varName is not specified, the end-
of-file case can be distinguished from an empty line using the chan eof command,
and the partial-line-but-nonblocking case can be distinguished with the chan
blocked command.
chan names ?pattern?
Produces a list of all channel names. If pattern is specified, only those channel
names that match it (according to the rules of string match) will be returned.
chan pending mode channelId
Depending on whether mode is input or output, returns the number of bytes of input
or output (respectively) currently buffered internally for channelId (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.
chan postevent channelId eventSpec
This subcommand is used by command handlers specified with chan create. It notifies
the channel represented by the handle channelId that the event(s) listed in the
eventSpec have occurred. The argument has to be a list containing any of the
strings read and write. 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.
Note that this subcommand can only be used with channel handles that were cre-
ated/opened by chan create. All other channels will cause this subcommand to report
an error.
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.
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 watch described in reflectedchan, the docu-
ment specifying the API of command handlers for reflected channels.
This command is safe and made accessible to safe interpreters. It can trigger the
execution of chan event handlers, whether in the current interpreter or in other
interpreters or other threads, even where the event is posted from a safe inter-
preter and listened for by a trusted interpreter. Chan event handlers are always
executed in the interpreter that set them up.
chan puts ?-nonewline? ?channelId? string
Writes string to the channel named channelId followed by a newline character. A
trailing newline character is written unless the optional flag -nonewline is given.
If channelId is omitted, the string is written to the standard output channel, std-
out.
Newline characters in the output are translated by chan puts to platform-specific
end-of-line sequences according to the currently configured value of the -transla-
tion option for the channel (for example, on PCs newlines are normally replaced
with carriage-return-linefeed sequences; see chan configure above for details).
Tcl buffers output internally, so characters written with chan puts 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 immedi-
ately with the chan flush command.
When the output buffer fills up, the chan puts command will normally block until
all the buffered data has been accepted for output by the operating system. If
channelId is in nonblocking mode then the chan puts 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 out-
put 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 chan event command (do not invoke chan puts unless you have
recently been notified via a file event that the channel is ready for more output
data).
chan read channelId ?numChars?
chan read ?-nonewline? channelId
In the first form, the result will be the next numChars characters read from the
channel named channelId; if numChars 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 numChars has been omitted)
the flag -nonewline may be given to indicate that any trailing newline in the
string that has been read should be trimmed.
If channelId is in nonblocking mode, chan read 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 config-
ured 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 -nonewline switch is ignored if the command returns before reaching the end of
the file.
Chan read translates end-of-line sequences in the input into newline characters
according to the -translation option for the channel (see chan configure above for
a discussion on the ways in which chan configure will alter input).
When reading from a serial port, most applications should configure the serial port
channel to be nonblocking, like this:
chan configure channelId -blocking 0.
Then chan read behaves much like described above. Note that most serial ports are
comparatively slow; it is entirely possible to get a readable event for each char-
acter read from them. Care must be taken when using chan read on blocking serial
ports:
chan read channelId numChars
In this form chan read blocks until numChars have been received from the
serial port.
chan read channelId
In this form chan read blocks until the reception of the end-of-file charac-
ter, see chan configure -eofchar. If there no end-of-file character has been
configured for the channel, then chan read will block forever.
chan seek channelId offset ?origin?
Sets the current access position within the underlying data stream for the channel
named channelId to be offset bytes relative to origin. Offset must be an integer
(which may be negative) and origin must be one of the following:
start The new access position will be offset bytes from the start of the under-
lying file or device.
current The new access position will be offset bytes from the current access
position; a negative offset moves the access position backwards in the
underlying file or device.
end The new access position will be offset bytes from the end of the file or
device. A negative offset places the access position before the end of
file, and a positive offset places the access position after the end of
file.
The origin argument defaults to start.
Chan seek 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 com-
mand is applied to channels whose underlying file or device does not support seek-
ing.
Note that offset values are byte offsets, not character offsets. Both chan seek
and chan tell operate in terms of bytes, not characters, unlike chan read.
chan tell channelId
Returns a number giving the current access position within the underlying data
stream for the channel named channelId. This value returned is a byte offset that
can be passed to chan seek in order to set the channel to a particular position.
Note that this value is in terms of bytes, not characters like chan read. The
value returned is -1 for channels that do not support seeking.
chan truncate channelId ?length?
Sets the byte length of the underlying data stream for the channel named channelId
to be length (or to the current byte offset within the underlying data stream if
length is omitted). The channel is flushed before truncation.
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.
set f [open somefile.txt r+]
chan configure $f -encoding cp1252
set offset 0
# Search for string "FOOBAR" in the file
while {[chan gets $f line] >= 0} {
set idx [string first FOOBAR $line]
if {$idx > -1} {
# Found it; rewrite line
chan seek $f [expr {$offset + $idx}]
chan puts -nonewline $f BARFOO
# Skip to end of following line, and truncate
chan gets $f
chan gets $f
chan truncate $f
# Stop searching the file now
break
}
# Save offset of start of next line for later
set offset [chan tell $f]
}
chan close $f
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)
KEYWORDS
channel, input, output, events, offset
Tcl 8.5 chan(n)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-04-25 17:21 @18.224.32.86 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)