The return value of the method has to be a list containing the names of all subcommands supported 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 subcommand 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.

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).

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.

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.

Note that returning nothing (0 bytes) is a signal to the higher layers that EOF has been reached on the channel. To signal that the channel is out of data right now, but has not yet reached EOF, it is necessary to throw the error "EAGAIN", i.e. to either

return -code error EAGAIN

error EAGAIN

For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "errno" to the absolute value of this number, signaling a system error. This means that both

return -code error -11

error -11

are equivalent to the examples above, using the more readable string "EAGAIN". No other error value has such a mapping to a symbolic string.

If the subcommand throws any other 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.

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.

To signal that the channel is not able to accept data for writing right now, it is necessary to throw the error "EAGAIN", i.e. to either

return -code error EAGAIN

error EAGAIN

For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "errno" to the absolute value of this number, signaling a system error. However, note that the exact mapping between these error numbers and their meanings is operating system dependent.

For example, while on Linux both

return -code error -11

error -11

are equivalent to the examples above, using the more readable string "EAGAIN", this is not true for BSD, where the equivalent number is -35.

The symbolic string however is the same across systems, and internally translated to the correct number. No other error value has such a mapping to a symbolic string.

If the subcommand throws any other 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.

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.

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.

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.

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.

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.