chan(3tcl) Tcl Built-In Commands chan(3tcl)
______________________________________________________________________________
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 manipulating 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, out-
put and error streams respectively). Option indicates what to do with
the channel; 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 re-
turns 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 ?direction?
Close and destroy the channel called channelId. Note that this
deletes all existing file-events registered on the channel. If │
the direction argument (which must be read or write 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. With- │
out the direction argument, the channel is closed for both read- │
ing 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.
As part of closing the channel, all buffered output is flushed
to the 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 channelId becomes unavailable for
future use (both only if the channel is being completely
closed).
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 immedi-
ately; 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 chan-
nel is registered invokes chan close (or close), the cleanup ac-
tions 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 interp command for a description of
channel sharing.
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.
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.)
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.
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 containing alternating option names and values
for the channel. If optionName is supplied 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 com-
mand 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 channel type may add options that only it sup-
ports. See 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 socket
command for additional options for sockets, and the open command
for additional options for serial devices.
-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 non-blocking mode it will affect the opera-
tion of the chan gets, chan read, chan puts, chan flush,
and chan close commands; see the documentation for those
commands for details. For non-blocking mode to work cor-
rectly, 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 out-
put until its internal 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 chan-
nel 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 termi-
nal-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 chan-
nel 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 in-
stance, in order for Tcl to read characters from a Japa-
nese 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 con-
verted to the specified encoding on output.
If a file contains pure binary data (for instance, a JPEG
image), the encoding 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 inter-
pretations 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 out-
put, 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 -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 newline character (\n). However, in ac-
tual files and devices the end of a line may be repre-
sented differently on different platforms, or even for
different devices on the same platform. For example, un-
der UNIX newlines are used in files, whereas carriage-re-
turn-linefeed sequences are normally used in network con-
nections. 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 translations.
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 channels; the read trans-
lation mode is the first element of the list, and the
write translation mode is the second element. As a con-
venience, 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:
auto As the input translation mode, auto treats any of
newline (lf), carriage return (cr), or carriage
return followed by a newline (crlf) as the end of
line representation. The end of line representa-
tion can even change from line-to-line, and all
cases are translated to a newline. As the output
translation mode, auto chooses a platform specific
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 ad-
dition binary mode also sets the end-of-file char-
acter to the empty string (which disables it) and
sets the encoding to binary (which disables encod-
ing 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 charac-
ter. As the input translation mode, cr mode con-
verts carriage returns to newline characters. As
the output translation mode, cr mode translates
newline characters to carriage returns.
crlf The end of a line in the underlying file or device
is represented by a carriage return character fol-
lowed by a linefeed character. As the input
translation mode, crlf mode converts carriage-re-
turn-linefeed sequences to newline characters. As
the output translation mode, crlf mode translates
newline characters to carriage-return-linefeed se-
quences. 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 typi-
cally 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 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.
The chan copy command transfers data from inputChan until end of
file or size bytes or characters have been transferred; size is
in bytes if the two channels are using the same encoding, and is
in characters otherwise. If no -size argument is given, then
the copy goes until end of file. All the data read from in-
putChan is copied to outputChan. Without the -command option,
chan copy blocks until the copy is complete and returns the num-
ber of bytes or characters (using the same rules as for the
-size option) 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 back-
ground copy, the second argument is the error string associated
with the error. With a background 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
necessary 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 cur-
rent copy is stopped and the command callback is not made. If
inputChan is closed, then all data already queued for outputChan
is written 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 han-
dler will get a “channel busy” error.
Chan copy translates end-of-line sequences in inputChan and out-
putChan according to the -translation option for these channels
(see chan configure above). The translations mean that the num-
ber of bytes read from inputChan can be different than the num-
ber of bytes written to outputChan. Only the number of bytes
written to outputChan 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 config-
ured for the channels. 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 conver-
sion 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 repre-
sentation of the incoming characters. If only the input channel
is set to encoding binary the system will assume that the incom-
ing 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 cmdPrefix as its handler. Any such channel is
called a reflected channel. The specified command prefix, cmd-
Prefix, must be a non-empty list, and should provide the API de-
scribed in the refchan manual page. The handle of the new chan-
nel 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 chosen 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 de-
scribed in the refchan 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. De-
pending 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 inter-
preter 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 spe-
cial events to it. This means that the original thread (i.e. the
thread that executed the chan create command) must have an ac-
tive event loop, i.e. it must be able to process such events.
Otherwise the thread sending them will block indefinitely. Dead-
lock may occur.
Note that this permits the creation of a channel whose two end-
points live in two different threads, providing a stream-ori-
ented bridge between these threads. In other words, we can pro-
vide a way for regular stream communication between threads in-
stead 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 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 reg-
ular error about unknown channel handles.
This subcommand is safe and made accessible to safe inter-
preters. 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 read-
able or writable); only one such handler may be installed per
event per channel at a time. If script is the empty string, the
current handler 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 com-
monly used to allow data to be received from another process on
an event-driven basis, so that the receiver can continue to in-
teract with the user or with other channels while waiting for
the data to arrive. If an application invokes chan gets or chan
read on a blocking channel when there is no input data avail-
able, 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 consid-
ered 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 com-
plete line in the input buffer. This feature allows a file to
be read a line at a time in non-blocking mode using events. A
channel is also considered to be readable if an end of file or
error condition is present on the underlying file or device. It
is important for 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 asynchronous
mode become writable when they become connected or if the con-
nection fails.
Event-driven I/O works best for channels that have been placed
into non-blocking 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 com-
mands block. In non-blocking 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 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.
chan gets channelId ?varName?
Reads the next line from the channel called channelId. If var-
Name 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 dis-
tinguished from an empty line using the chan eof command, and
the partial-line-but-non-blocking 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 pipe
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 stderr and stdout 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 par- │
ent. This is necessary to get an EOF on the read side once the │
child has exited or otherwise closed its output. │
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 in- │
stantly to the input side. This is a fundamental difference and │
Tcl cannot conceal it. The overall stream semantics are compati- │
ble, so blocking reads and writes will not see most of the dif- │
ferences, 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. │
chan pop channelId
Removes the topmost transformation from the channel channelId, │
if there is any. If there are no transformations added to chan- │
nelId, this is equivalent to chan close of that channel. The re- │
sult 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).
chan postevent channelId eventSpec
This subcommand is used by command handlers specified with chan
create. It notifies the channel represented by the handle chan-
nelId 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 created/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 com-
mand 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. At-
tempting 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 refchan, the document specify-
ing 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 interpreter
and listened for by a trusted interpreter. Chan event handlers
are always executed in the interpreter that set them up.
chan push channelId cmdPrefix
Adds a new transformation on top of the channel channelId. The │
cmdPrefix argument describes a list of one or more words which │
represent a handler that will be used to implement the transfor- │
mation. The command prefix must provide the API described in the │
transchan manual page. The result of this subcommand is a han- │
dle to the transformation. Note that it is important to make │
sure that the transformation is capable of supporting the chan- │
nel mode that it is used with or this can make the channel nei- │
ther readable nor writable.
chan puts ?-nonewline? ?channelId? string
Writes string to the channel named channelId followed by a new-
line 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, stdout.
Newline characters in the output are translated by chan puts to
platform-specific end-of-line sequences according to the cur-
rently configured value of the -translation option for the chan-
nel (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 immediately
with the chan flush command.
When the output buffer fills up, the chan puts command will nor-
mally block until all the buffered data has been accepted for
output by the operating system. If channelId is in non-blocking
mode then the chan puts command will not block even if the oper-
ating 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 non-blocking output to work; other-
wise 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 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 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 charac-
ters read from the channel named channelId; if numChars is omit-
ted, all characters up to the point when the channel would sig-
nal 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 non-blocking 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 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 -nonew-
line 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 con-
figure the serial port channel to be non-blocking, 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 possi-
ble to get a readable event for each character 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 character, 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 rela-
tive to origin. Offset must be an integer (which may be nega-
tive) and origin must be one of the following:
start The new access position will be offset bytes from the
start of the underlying 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 pos-
itive 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 non-blocking mode.
It also discards any buffered and unread input. This command
returns an empty string. An error occurs if this command is ap-
plied to channels whose underlying file or device does not sup-
port seeking.
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 seek-
ing.
chan truncate channelId ?length?
Sets the byte length of the underlying data stream for the chan-
nel 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.
EXAMPLES
This opens a file using a known encoding (CP1252, a very common encod-
ing on Windows), searches for a string, rewrites that part, and trun-
cates 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
A network server that does echoing of its input line-by-line without
preventing servicing of other connections at the same time.
# This is a very simple logger...
proc log {message} {
chan puts 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"
chan configure $chan -blocking 0 -buffering line
chan event $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} {
chan gets $chan line
if {[chan eof $chan]} {
log "finishing connection from $clientName"
chan close $chan
} elseif {![chan blocked $chan]} {
# Didn't block waiting for end-of-line
log "$clientName - $line"
chan puts $chan $line
}
}
# Create the server socket and enter the event-loop to wait
# for incoming connections...
socket -server connect 12345
vwait forever
SEE ALSO
close(3tcl), eof(3tcl), fblocked(3tcl), fconfigure(3tcl), fcopy(3tcl),
file(3tcl), fileevent(3tcl), flush(3tcl), gets(3tcl), open(3tcl),
puts(3tcl), read(3tcl), seek(3tcl), socket(3tcl), tell(3tcl), re-
fchan(3tcl), transchan(3tcl)
KEYWORDS
channel, input, output, events, offset
Tcl 8.5 chan(3tcl)
Generated by dwww version 1.14 on Thu Jan 23 00:35:02 CET 2025.