diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:13:18 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:13:18 (GMT) |
commit | 07e464099b99459d0a37757771791598ef3395d9 (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/SetChanErr.3 | |
parent | deb3650e37f26f651f280e480c4df3d7dde87bae (diff) | |
download | blt-07e464099b99459d0a37757771791598ef3395d9.zip blt-07e464099b99459d0a37757771791598ef3395d9.tar.gz blt-07e464099b99459d0a37757771791598ef3395d9.tar.bz2 |
new subtree for tcl/tk
Diffstat (limited to 'tcl8.6/doc/SetChanErr.3')
-rw-r--r-- | tcl8.6/doc/SetChanErr.3 | 140 |
1 files changed, 0 insertions, 140 deletions
diff --git a/tcl8.6/doc/SetChanErr.3 b/tcl8.6/doc/SetChanErr.3 deleted file mode 100644 index 5bb86be..0000000 --- a/tcl8.6/doc/SetChanErr.3 +++ /dev/null @@ -1,140 +0,0 @@ -'\" -'\" 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. -'\" -.TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures" -.so man.macros -.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\fR 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 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. -.PP -\fBTcl_SetChannelErrorInterp\fR stores error information in the bypass area of -the specified interpreter. The number of references to the \fBmsg\fR value -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, that is, 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 value. -.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, that is, 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 value. -.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. -.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 \fInot\fR use -any of the new functions. -.IP \fBTcl_DriverGetOptionProc\fR -Has already the ability to pass arbitrary error messages. Must -\fInot\fR use any of the new functions. -.IP \fBTcl_DriverWatchProc\fR -Must \fInot\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 \fInot\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 \fInot\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; when these functions are called, the channel -may now contain a stored arbitrary error message requiring processing by the -caller. -.DS -.ta 1.9i 4i -\fBTcl_Flush\fR \fBTcl_GetsObj\fR \fBTcl_Gets\fR -\fBTcl_ReadChars\fR \fBTcl_ReadRaw\fR \fBTcl_Read\fR -\fBTcl_Seek\fR \fBTcl_StackChannel\fR \fBTcl_Tell\fR -\fBTcl_WriteChars\fR \fBTcl_WriteObj\fR \fBTcl_WriteRaw\fR -\fBTcl_Write\fR -.DE -.PP -All other API functions are unchanged. In particular, the functions below -leave all their error information in the interpreter result. -.DS -.ta 1.9i 4i -\fBTcl_Close\fR \fBTcl_UnstackChannel\fR \fBTcl_UnregisterChannel\fR -.DE -.SH "SEE ALSO" -Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) -.SH KEYWORDS -channel driver, error messages, channel type |