|
ActiveTcl User Guide |
|
- NAME
- Tcl_SetChannelError, Tcl_SetChannelErrorInterp,
Tcl_GetChannelError, Tcl_GetChannelErrorInterp - functions to
create/intercept Tcl errors by channel drivers.
- SYNOPSIS
- ARGUMENTS
- DESCRIPTION
- Tcl_DriverCloseProc
- Tcl_DriverInputProc
- Tcl_DriverOutputProc
- Tcl_DriverSeekProc
- Tcl_DriverWideSeekProc
- Tcl_DriverSetOptionProc
- Tcl_DriverGetOptionProc
- Tcl_DriverWatchProc
- Tcl_DriverBlockModeProc
- Tcl_DriverGetHandleProc
- Tcl_DriverHandlerProc
- Tcl_StackChannel
- Tcl_Seek
- Tcl_Tell
- Tcl_ReadRaw
- Tcl_Read
- Tcl_ReadChars
- Tcl_Gets
- Tcl_GetsObj
- Tcl_Flush
- Tcl_WriteRaw
- Tcl_WriteObj
- Tcl_Write
- Tcl_WriteChars
- Tcl_Close
- Tcl_UnregisterChannel
- Tcl_UnstackChannel
- SEE ALSO
- KEYWORDS
Tcl_SetChannelError, Tcl_SetChannelErrorInterp,
Tcl_GetChannelError, Tcl_GetChannelErrorInterp - functions to
create/intercept Tcl errors by channel drivers.
#include <tcl.h>
void
Tcl_SetChannelError(chan, msg)
void
Tcl_SetChannelErrorInterp(interp, msg)
void
Tcl_GetChannelError(chan, msgPtr)
void
Tcl_GetChannelErrorInterp(interp, msgPtr)
- Tcl_Channel chan
(in)
- Refers to the Tcl channel whose bypass area is accessed.
- Tcl_Interp* interp (in)
- Refers to the Tcl interpreter whose bypass area is
accessed.
- Tcl_Obj* msg (in)
- Error message put into a bypass area. A list of return options
and values, followed by a string message. Both message and the
option/value information are optional.
- Tcl_Obj** msgPtr (out)
- Reference to a place where the message stored in the accessed
bypass area can be stored in.
The current definition of a Tcl channel driver does not permit the
direct return of arbitrary error messages, except for the setting
and retrieval of channel options. All other functions are
restricted to POSIX error codes.
The functions described here overcome this limitation. Channel
drivers are allowed to use Tcl_SetChannelError and
Tcl_SetChannelErrorInterp to place arbitrary error messages
in bypass areas defined for channels and interpreters.
And the generic I/O layer uses Tcl_GetChannelError and
Tcl_GetChannelErrorInterp to look for messages in the bypass
areas and arrange for their return as errors. The posix error codes
set by a driver are used now if and only if no messages are
present.
Tcl_SetChannelError stores error information in the
bypass area of the specified channel. The number of references to
the msg object goes up by one. Previously stored information
will be discarded, by releasing the reference held by the channel.
The channel reference must not be NULL.
Tcl_SetChannelErrorInterp stores error information in the
bypass area of the specified interpreter. The number of references
to the msg object goes up by one. Previously stored
information will be discarded, by releasing the reference held by
the interpreter. The interpreter reference must not be NULL.
Tcl_GetChannelError places either the error message held
in the bypass area of the specified channel into msgPtr, or
NULL; and resets the bypass. I.e. after an invokation all following
invokations will return NULL, until an intervening invokation of
Tcl_SetChannelError with a non-NULL message. The
msgPtr must not be NULL. The reference count of the message
is not touched. The reference previously held by the channel is now
held by the caller of the function and it is its responsibility to
release that reference when it is done with the object.
Tcl_GetChannelErrorInterp places either the error message
held in the bypass area of the specified interpreter into
msgPtr, or NULL; and resets the bypass. I.e. after an
invokation all following invokations will return NULL, until an
intervening invokation of Tcl_SetChannelErrorInterp with a
non-NULL message. The msgPtr must not be NULL. The reference
count of the message is not touched. The reference previously held
by the interpreter is now held by the caller of the function and it
is its responsibility to release that reference when it is done
with the object.
Which functions of a channel driver are allowed to use which
bypass function is listed below, as is which functions of the
public channel API may leave a messages in the bypass areas.
- Tcl_DriverCloseProc
- May use Tcl_SetChannelErrorInterp, and only this
function.
- Tcl_DriverInputProc
- May use Tcl_SetChannelError, and only this
function.
- Tcl_DriverOutputProc
- May use Tcl_SetChannelError, and only this
function.
- Tcl_DriverSeekProc
- May use Tcl_SetChannelError, and only this
function.
- Tcl_DriverWideSeekProc
- May use Tcl_SetChannelError, and only this
function.
- Tcl_DriverSetOptionProc
- Has already the ability to pass arbitrary error messages. Must
not use any of the new functions.
- Tcl_DriverGetOptionProc
- Has already the ability to pass arbitrary error messages. Must
not use any of the new functions.
- Tcl_DriverWatchProc
- Must not use any of the new functions. Is internally
called and has no ability to return any type of error
whatsoever.
- Tcl_DriverBlockModeProc
- May use Tcl_SetChannelError, and only this
function.
- Tcl_DriverGetHandleProc
- Must not use any of the new functions. It is only a
low-level function, and not used by Tcl commands.
- Tcl_DriverHandlerProc
- Must not use any of the new functions. Is internally
called and has no ability to return any type of error
whatsoever.
Given the information above the following public functions of
the Tcl C API are affected by these changes. I.e. when these
functions are called the channel may now contain a stored arbitrary
error message requiring processing by the caller.
- Tcl_StackChannel
- Tcl_Seek
- Tcl_Tell
- Tcl_ReadRaw
- Tcl_Read
- Tcl_ReadChars
- Tcl_Gets
- Tcl_GetsObj
- Tcl_Flush
- Tcl_WriteRaw
- Tcl_WriteObj
- Tcl_Write
- Tcl_WriteChars
All other API functions are unchanged. Especially the functions
below leave all their error information in the interpreter
result.
- Tcl_Close
- Tcl_UnregisterChannel
- Tcl_UnstackChannel
Tcl_Close, Tcl_OpenFileChannel,
Tcl_SetErrno
channel driver, error messages, channel type
Copyright © 1995-1997 Roger E. Critchlow Jr.
Copyright © 2005 Andreas Kupries
<andreas_kupries(at)users.sourceforge.net>