Man Pages

refchan(n) - phpMan refchan(n) - phpMan

Command: man perldoc info search(apropos)  


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 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  subcom-
              mand 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 speci-
              fies 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 con-
              verted 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.

              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 chan-
              nelId. 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 con-
              verted to an error.

              The offset/base combination of 0/current signals a tell request, i.e. seek nothing relative to the  cur-
              rent 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 argu-
              ment 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  con-
              verted 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  han-
       dles.

       The  function  Tcl_DriverHandlerProc  is not supported. This driver function is relevant only for stacked chan-
       nels, 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 func-
       tion be used at some time in the future.

SEE ALSO
       chan(n)

KEYWORDS
       channel, reflection



Tcl                                   8.5                           refchan(n)