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