Provided by: tcl8.5-doc_8.5.15-2ubuntu1_all bug

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 ensemble, 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  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.

       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.

              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
              or
                     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
              and
                     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.

       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) configured for the channel has already been  applied
              at this point. If this subcommand is not supported 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.

              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
              or
                     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
              and
                     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.

       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 channelId. 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 channels reflected to the Tcl level.

       The function Tcl_DriverGetHandleProc is not supported; i.e.   reflected  channels  do  not
       have OS specific 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 transformations.

       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(3tcl)

KEYWORDS

       channel, reflection