'\"
'\" 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.
'\"
'\" RCS: @(#) $Id: SetChanErr.3,v 1.4.2.1 2009/11/27 14:53:54 dkf Exp $
.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