diff options
Diffstat (limited to 'doc/SetChanErr.3')
| -rw-r--r-- | doc/SetChanErr.3 | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 new file mode 100644 index 0000000..13bd94a --- /dev/null +++ b/doc/SetChanErr.3 @@ -0,0 +1,153 @@ +'\" +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.so man.macros +.TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp \- functions to create/intercept Tcl errors by channel drivers. +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +void +\fBTcl_SetChannelError\fR(\fIchan, msg\fR) +.sp +void +\fBTcl_SetChannelErrorInterp\fR(\fIinterp, msg\fR) +.sp +void +\fBTcl_GetChannelError\fR(\fIchan, msgPtr\fR) +.sp +void +\fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR) +.sp +.SH ARGUMENTS +.AS Tcl_Channel chan +.AP Tcl_Channel chan in +Refers to the Tcl channel whose bypass area is accessed. +.AP Tcl_Interp* interp in +Refers to the Tcl interpreter whose bypass area is accessed. +.AP 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. +.AP Tcl_Obj** msgPtr out +Reference to a place where the message stored in the accessed bypass +area can be stored in. +.BE +.SH DESCRIPTION +.PP +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. +.PP +The functions described here overcome this limitation. Channel drivers +are allowed to use \fBTcl_SetChannelError\fR and +\fBTcl_SetChannelErrorInterp\fR to place arbitrary error messages in +\fBbypass areas\fI defined for channels and interpreters. And the +generic I/O layer uses \fBTcl_GetChannelError\fR and +\fBTcl_GetChannelErrorInterp\fR 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. +.PP +\fBTcl_SetChannelError\fR stores error information in the bypass area +of the specified channel. The number of references to the \fBmsg\fR +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. +.PP +\fBTcl_SetChannelErrorInterp\fR stores error information in the bypass +area of the specified interpreter. The number of references to the +\fBmsg\fR 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. +.PP +\fBTcl_GetChannelError\fR places either the error message held in the +bypass area of the specified channel into \fImsgPtr\fR, or NULL; and +resets the bypass. I.e. after an invocation all following invocations +will return NULL, until an intervening invocation of +\fBTcl_SetChannelError\fR with a non-NULL message. The \fImsgPtr\fR +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. +.PP +\fBTcl_GetChannelErrorInterp\fR places either the error message held +in the bypass area of the specified interpreter into \fImsgPtr\fR, or +NULL; and resets the bypass. I.e. after an invocation all following +invocations will return NULL, until an intervening invocation of +\fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The +\fImsgPtr\fR 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. +.PP +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. +.PP +.IP \fBTcl_DriverCloseProc\fR +May use \fBTcl_SetChannelErrorInterp\fR, and only this function. +.IP \fBTcl_DriverInputProc\fR +May use \fBTcl_SetChannelError\fR, and only this function. +.IP \fBTcl_DriverOutputProc\fR +May use \fBTcl_SetChannelError\fR, and only this function. +.IP \fBTcl_DriverSeekProc\fR +May use \fBTcl_SetChannelError\fR, and only this function. +.IP \fBTcl_DriverWideSeekProc\fR +May use \fBTcl_SetChannelError\fR, and only this function. +.IP \fBTcl_DriverSetOptionProc\fR +Has already the ability to pass arbitrary error messages. Must +\fBnot\fR use any of the new functions. +.IP \fBTcl_DriverGetOptionProc\fR +Has already the ability to pass arbitrary error messages. Must +\fBnot\fR use any of the new functions. +.IP \fBTcl_DriverWatchProc\fR +Must \fBnot\fR use any of the new functions. Is internally called and +has no ability to return any type of error whatsoever. +.IP \fBTcl_DriverBlockModeProc\fR +May use \fBTcl_SetChannelError\fR, and only this function. +.IP \fBTcl_DriverGetHandleProc\fR +Must \fBnot\fR use any of the new functions. It is only a low-level +function, and not used by Tcl commands. +.IP \fBTcl_DriverHandlerProc\fR +Must \fBnot\fR use any of the new functions. Is internally called and +has no ability to return any type of error whatsoever. +.PP +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. +.PP +.IP \fBTcl_StackChannel\fR +.IP \fBTcl_Seek\fR +.IP \fBTcl_Tell\fR +.IP \fBTcl_ReadRaw\fR +.IP \fBTcl_Read\fR +.IP \fBTcl_ReadChars\fR +.IP \fBTcl_Gets\fR +.IP \fBTcl_GetsObj\fR +.IP \fBTcl_Flush\fR +.IP \fBTcl_WriteRaw\fR +.IP \fBTcl_WriteObj\fR +.IP \fBTcl_Write\fR +.IP \fBTcl_WriteChars\fR +.PP +All other API functions are unchanged. Especially the functions below +leave all their error information in the interpreter result. +.PP +.IP \fBTcl_Close\fR +.IP \fBTcl_UnregisterChannel\fR +.IP \fBTcl_UnstackChannel\fR + +.SH "SEE ALSO" +Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) + +.SH KEYWORDS +channel driver, error messages, channel type |