diff options
Diffstat (limited to 'doc/SetChanErr.3')
| -rw-r--r-- | doc/SetChanErr.3 | 15 |
1 files changed, 12 insertions, 3 deletions
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index 5bb86be..473b61c 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -35,20 +35,20 @@ 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. +are optional. This \fImust\fR be a well-formed list. .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 +The standard 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 +to place arbitrary error messages in \fIbypass 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 @@ -134,6 +134,15 @@ leave all their error information in the interpreter result. .ta 1.9i 4i \fBTcl_Close\fR \fBTcl_UnstackChannel\fR \fBTcl_UnregisterChannel\fR .DE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fImsg\fR argument to \fBTcl_SetChannelError\fR and +\fBTcl_SetChannelErrorInterp\fR, if not NULL, may have any reference count; +these functions will copy. +.PP +\fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR write a value +reference into their \fImsgPtr\fR, but do not manipulate its reference count. +The reference count will be at least 1 (unless the reference is NULL). .SH "SEE ALSO" Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) .SH KEYWORDS |