Tcl_SetChannelError(3tcl) Tcl Library Procedures Tcl_SetChannelError(3tcl)
______________________________________________________________________________
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 by-
pass area is accessed.
Tcl_Obj* msg (in) Error message put into a bypass area. A
list of return options and values, fol-
lowed by a string message. Both message
and the option/value information are op-
tional.
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 permit the di-
rect return of arbitrary error messages, except for the setting and re-
trieval 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 value 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 value
goes up by one. Previously stored information will be discarded, by re-
leasing the reference held by the interpreter. The interpreter refer-
ence 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 by-
pass, that is, after an invocation all following invocations will re-
turn NULL, until an intervening invocation 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 chan-
nel is now held by the caller of the function and it is its responsi-
bility to release that reference when it is done with the value.
Tcl_GetChannelErrorInterp places either the error message held in the
bypass area of the specified interpreter into msgPtr, or NULL; and re-
sets the bypass, that is, after an invocation all following invocations
will return NULL, until an intervening invocation of Tcl_SetChannelEr-
rorInterp 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 value.
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; when these functions are called, the
channel may now contain a stored arbitrary error message requiring pro-
cessing by the caller.
Tcl_Flush Tcl_GetsObj Tcl_Gets
Tcl_ReadChars Tcl_ReadRaw Tcl_Read
Tcl_Seek Tcl_StackChannel Tcl_Tell
Tcl_WriteChars Tcl_WriteObj Tcl_WriteRaw
Tcl_Write
All other API functions are unchanged. In particular, the functions be-
low leave all their error information in the interpreter result.
Tcl_Close Tcl_UnstackChannel Tcl_UnregisterChannel
SEE ALSO
Tcl_Close(3tcl), Tcl_OpenFileChannel(3tcl), Tcl_SetErrno(3tcl)
KEYWORDS
channel driver, error messages, channel type
Tcl 8.5 Tcl_SetChannelError(3tcl)
Generated by dwww version 1.14 on Thu Jan 23 00:53:25 CET 2025.