|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
refchan(n) Tcl Built-In Commands refchan(n)
____________________________________________________________________________________________________________
NAME
refchan - Command handler API of reflected channels, version 1
SYNOPSIS
cmdPrefix option ?arg arg ...?
____________________________________________________________________________________________________________
DESCRIPTION
The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an ensem-ble, ensemble,
ble, as it is a command such as that created by namespace ensemble create, though the implementation
of handlers for reflected channel is not tied to namespace ensembles in any way). Note that cmdPrefix
is whatever was specified in the call to chan create, and may consist of multiple arguments; this
will be expanded to multiple words in place of the prefix.
Of all the possible subcommands, the handler must support initialize, finalize, and watch. Support
for the other subcommands is optional.
MANDATORY SUBCOMMANDS
cmdPrefix initialize channelId mode
An invocation of this subcommand will be the first call the cmdPrefix will receive for the
specified new channelId. It is the responsibility of this subcommand to set up any internal
data structures required to keep track of the channel and its state.
The return value of the method has to be a list containing the names of all subcommands sup-ported supported
ported by the cmdPrefix. This also tells the Tcl core which version of the API for reflected
channels is used by this command handler.
Any error thrown by the method will abort the creation of the channel and no channel will be
created. The thrown error will appear as error thrown by chan create. Any exception other than
an error (e.g. break, etc.) is treated as (and converted to) an error.
Note: If the creation of the channel was aborted due to failures here, then the finalize sub-command subcommand
command will not be called.
The mode argument tells the handler whether the channel was opened for reading, writing, or
both. It is a list containing any of the strings read or write. The list will always contain
at least one element.
The subcommand must throw an error if the chosen mode is not supported by the cmdPrefix.
cmdPrefix finalize channelId
An invocation of this subcommand will be the last call the cmdPrefix will receive for the
specified channelId. It will be generated just before the destruction of the data structures
of the channel held by the Tcl core. The command handler must not access the channelId anymore
in no way. Upon this subcommand being called, any internal resources allocated to this channel
must be cleaned up.
The return value of this subcommand is ignored.
If the subcommand throws an error the command which caused its invocation (usually close) will
appear to have thrown this error. Any exception beyond error (e.g. break, etc.) is treated as
(and converted to) an error.
This subcommand is not invoked if the creation of the channel was aborted during initialize
(See above).
cmdPrefix watch channelId eventspec
This subcommand notifies the cmdPrefix that the specified channelId is interested in the
events listed in the eventspec. This argument is a list containing any of read and write. The
list may be empty, which signals that the channel does not wish to be notified of any events.
In that situation, the handler should disable event generation completely.
Warning: Any return value of the subcommand is ignored. This includes all errors thrown by the
subcommand, break, continue, and custom return codes.
This subcommand interacts with chan postevent. Trying to post an event which was not listed in
the last call to watch will cause chan postevent to throw an error.
OPTIONAL SUBCOMMANDS
cmdPrefix read channelId count
This optional subcommand is called when the user requests data from the channel channelId.
count specifies how many bytes have been requested. If the subcommand is not supported then it
is not possible to read from the channel handled by the command.
The return value of this subcommand is taken as the requested data bytes. If the returned data
contains more bytes than requested, an error will be signaled and later thrown by the command
which performed the read (usually gets or read). However, returning fewer bytes than requested
is acceptable.
If the subcommand throws an error, the command which caused its invocation (usually gets, or
read) will appear to have thrown this error. Any exception beyond error, (e.g. break, etc.)
is treated as and converted to an error.
cmdPrefix write channelId data
This optional subcommand is called when the user writes data to the channel channelId. The
data argument contains bytes, not characters. Any type of transformation (EOL, encoding) con-figured configured
figured for the channel has already been applied at this point. If this subcommand is not sup-ported supported
ported then it is not possible to write to the channel handled by the command.
The return value of the subcommand is taken as the number of bytes written by the channel.
Anything non-numeric will cause an error to be signaled and later thrown by the command which
performed the write. A negative value implies that the write failed. Returning a value greater
than the number of bytes given to the handler, or zero, is forbidden and will cause the Tcl
core to throw an error.
If the subcommand throws an error the command which caused its invocation (usually puts) will
appear to have thrown this error. Any exception beyond error (e.g. break, etc.) is treated as
and converted to an error.
cmdPrefix seek channelId offset base
This optional subcommand is responsible for the handling of seek and tell requests on the
channel channelId. If it is not supported then seeking will not be possible for the channel.
The base argument is one of
start Seeking is relative to the beginning of the channel.
current Seeking is relative to the current seek position.
end Seeking is relative to the end of the channel.
The base argument of the builtin chan seek command takes the same names.
The offset is an integer number specifying the amount of bytes to seek forward or backward. A
positive number should seek forward, and a negative number should seek backward.
A channel may provide only limited seeking. For example sockets can seek forward, but not
backward.
The return value of the subcommand is taken as the (new) location of the channel, counted from
the start. This has to be an integer number greater than or equal to zero.
If the subcommand throws an error the command which caused its invocation (usually seek, or
tell) will appear to have thrown this error. Any exception beyond error (e.g. break, etc.) is
treated as and converted to an error.
The offset/base combination of 0/current signals a tell request, i.e. seek nothing relative to
the current location, making the new location identical to the current one, which is then
returned.
cmdPrefix configure channelId option value
This optional subcommand is for setting the type-specific options of channel channelId. The
option argument indicates the option to be written, and the value argument indicates the value
to set the option to.
This subcommand will never try to update more than one option at a time; that is behavior
implemented in the Tcl channel core.
The return value of the subcommand is ignored.
If the subcommand throws an error the command which performed the (re)configuration or query
(usually fconfigure or chan configure) will appear to have thrown this error. Any exception
beyond error (e.g. break, etc.) is treated as and converted to an error.
cmdPrefix cget channelId option
This optional subcommand is used when reading a single type-specific option of channel chan-nelId. channelId.
nelId. If this subcommand is supported then the subcommand cgetall must be supported as well.
The subcommand should return the value of the specified option.
If the subcommand throws an error, the command which performed the (re)configuration or query
(usually fconfigure) will appear to have thrown this error. Any exception beyond error (e.g.
break, etc.) is treated as and converted to an error.
cmdPrefix cgetall channelId
This optional subcommand is used for reading all type-specific options of channel channelId.
If this subcommand is supported then the subcommand cget has to be supported as well.
The subcommand should return a list of all options and their values. This list must have an
even number of elements.
If the subcommand throws an error the command which performed the (re)configuration or query
(usually fconfigure) will appear to have thrown this error. Any exception beyond error (e.g.
break, etc.) is treated as and converted to an error.
cmdPrefix blocking channelId mode
This optional subcommand handles changes to the blocking mode of the channel channelId. The
mode is a boolean flag. A true value means that the channel has to be set to blocking, and a
false value means that the channel should be non-blocking.
The return value of the subcommand is ignored.
If the subcommand throws an error the command which caused its invocation (usually fconfigure)
will appear to have thrown this error. Any exception beyond error (e.g. break, etc.) is
treated as and converted to an error.
NOTES
Some of the functions supported in channels defined in Tcl's C interface are not available to chan-nels channels
nels reflected to the Tcl level.
The function Tcl_DriverGetHandleProc is not supported; i.e. reflected channels do not have OS spe-cific specific
cific handles.
The function Tcl_DriverHandlerProc is not supported. This driver function is relevant only for
stacked channels, i.e. transformations. Reflected channels are always base channels, not transforma-tions. transformations.
tions.
The function Tcl_DriverFlushProc is not supported. This is because the current generic I/O layer of
Tcl does not use this function anywhere at all. Therefore support at the Tcl level makes no sense
either. This may be altered in the future (through extending the API defined here and changing its
version number) should the function be used at some time in the future.
SEE ALSO
chan(n)
KEYWORDS
channel, reflection
Tcl 8.5 refchan(n)
|
The way to report a problem with this manual page depends on the type of problem: