On Apache
Under GNU General Public License
2024-04-16 06:58 @18.224.67.149 CrawledBy claudebot
Tcl_SetChannelError(3) Tcl Library Procedures Tcl_SetChannelError(3)
_________________________________________________________________________________________________
NAME
Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelError-
Interp - 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 permit the direct return of arbi-
trary 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 speci-
fied 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_SetChannel-
Error 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 invoca-
tion 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 refer-
ence count of the message is not touched. The reference previously held by the inter-
preter 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
SEE ALSO
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
KEYWORDS
channel driver, error messages, channel type
Tcl 8.5 Tcl_SetChannelError(3)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-04-16 06:58 @18.224.67.149 CrawledBy claudebot