Tcl_SetChannelError(3tcl)
Tcl_SetChannelError(3)Tcl Library ProcedureTcl_SetChannelError(3)
_________________________________________________________________
NAME
Tcl_SetChannelError, Tcl_SetChannelErrorInterp,
Tcl_GetChannelError, Tcl_GetChannelErrorInterp - functions
to create/intercept Tcl errors by channel drivers.
SYNOPSIS
#include <tcl.h>
void
Tcl_SetChannelError(chan, msg)
void
Tcl_SetChannelErrorInterp(interp, msg)
void
Tcl_GetChannelError(chan, msgPtr)
void
Tcl_GetChannelErrorInterp(interp, msgPtr)
ARGUMENTS
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.
_________________________________________________________________
DESCRIPTION
The current definition of a Tcl channel driver does not per-
mit 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.
Tcl Last change: 8.5 1
Tcl_SetChannelError(3)Tcl Library ProcedureTcl_SetChannelError(3)
The functions described here overcome this limitation. Chan-
nel 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 invocation all
following invocations will return NULL, until an intervening
invocation of Tcl_SetChannelError with a non-NULL message.
The msgPtr must not be NULL. The reference count of the mes-
sage 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 invo-
cation all following invocations will return NULL, until an
intervening invocation 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 previ-
ously 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
Tcl Last change: 8.5 2
Tcl_SetChannelError(3)Tcl Library ProcedureTcl_SetChannelError(3)
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 mes-
sages. Must not use any of the new functions.
Tcl_DriverGetOptionProc
Has already the ability to pass arbitrary error mes-
sages. 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 Last change: 8.5 3
Tcl_SetChannelError(3)Tcl Library ProcedureTcl_SetChannelError(3)
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 func-
tions below leave all their error information in the inter-
preter result.
Tcl_Close
Tcl_UnregisterChannel
Tcl_UnstackChannel
SEE ALSO
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
KEYWORDS
channel driver, error messages, channel type
Tcl Last change: 8.5 4
Man(1) output converted with
man2html