1 | '\" |
---|
2 | '\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: SetChanErr.3,v 1.4 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | .so man.macros |
---|
9 | .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures" |
---|
10 | .BS |
---|
11 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
12 | .SH NAME |
---|
13 | Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp \- functions to create/intercept Tcl errors by channel drivers. |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | void |
---|
19 | \fBTcl_SetChannelError\fR(\fIchan, msg\fR) |
---|
20 | .sp |
---|
21 | void |
---|
22 | \fBTcl_SetChannelErrorInterp\fR(\fIinterp, msg\fR) |
---|
23 | .sp |
---|
24 | void |
---|
25 | \fBTcl_GetChannelError\fR(\fIchan, msgPtr\fR) |
---|
26 | .sp |
---|
27 | void |
---|
28 | \fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR) |
---|
29 | .sp |
---|
30 | .SH ARGUMENTS |
---|
31 | .AS Tcl_Channel chan |
---|
32 | .AP Tcl_Channel chan in |
---|
33 | Refers to the Tcl channel whose bypass area is accessed. |
---|
34 | .AP Tcl_Interp* interp in |
---|
35 | Refers to the Tcl interpreter whose bypass area is accessed. |
---|
36 | .AP Tcl_Obj* msg in |
---|
37 | Error message put into a bypass area. A list of return options and |
---|
38 | values, followed by a string message. Both message and the |
---|
39 | option/value information are optional. |
---|
40 | .AP Tcl_Obj** msgPtr out |
---|
41 | Reference to a place where the message stored in the accessed bypass |
---|
42 | area can be stored in. |
---|
43 | .BE |
---|
44 | .SH DESCRIPTION |
---|
45 | .PP |
---|
46 | The current definition of a Tcl channel driver does not permit the |
---|
47 | direct return of arbitrary error messages, except for the setting and |
---|
48 | retrieval of channel options. All other functions are restricted to |
---|
49 | POSIX error codes. |
---|
50 | .PP |
---|
51 | The functions described here overcome this limitation. Channel drivers |
---|
52 | are allowed to use \fBTcl_SetChannelError\fR and |
---|
53 | \fBTcl_SetChannelErrorInterp\fR to place arbitrary error messages in |
---|
54 | \fBbypass areas\fI defined for channels and interpreters. And the |
---|
55 | generic I/O layer uses \fBTcl_GetChannelError\fR and |
---|
56 | \fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass |
---|
57 | areas and arrange for their return as errors. The posix error codes |
---|
58 | set by a driver are used now if and only if no messages are present. |
---|
59 | .PP |
---|
60 | \fBTcl_SetChannelError\fR stores error information in the bypass area |
---|
61 | of the specified channel. The number of references to the \fBmsg\fR |
---|
62 | object goes up by one. Previously stored information will be |
---|
63 | discarded, by releasing the reference held by the channel. The channel |
---|
64 | reference must not be NULL. |
---|
65 | .PP |
---|
66 | \fBTcl_SetChannelErrorInterp\fR stores error information in the bypass |
---|
67 | area of the specified interpreter. The number of references to the |
---|
68 | \fBmsg\fR object goes up by one. Previously stored information will be |
---|
69 | discarded, by releasing the reference held by the interpreter. The |
---|
70 | interpreter reference must not be NULL. |
---|
71 | .PP |
---|
72 | \fBTcl_GetChannelError\fR places either the error message held in the |
---|
73 | bypass area of the specified channel into \fImsgPtr\fR, or NULL; and |
---|
74 | resets the bypass. I.e. after an invokation all following invokations |
---|
75 | will return NULL, until an intervening invokation of |
---|
76 | \fBTcl_SetChannelError\fR with a non-NULL message. The \fImsgPtr\fR |
---|
77 | must not be NULL. The reference count of the message is not touched. |
---|
78 | The reference previously held by the channel is now held by the caller |
---|
79 | of the function and it is its responsibility to release that reference |
---|
80 | when it is done with the object. |
---|
81 | .PP |
---|
82 | \fBTcl_GetChannelErrorInterp\fR places either the error message held |
---|
83 | in the bypass area of the specified interpreter into \fImsgPtr\fR, or |
---|
84 | NULL; and resets the bypass. I.e. after an invokation all following |
---|
85 | invokations will return NULL, until an intervening invokation of |
---|
86 | \fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The |
---|
87 | \fImsgPtr\fR must not be NULL. The reference count of the message is |
---|
88 | not touched. The reference previously held by the interpreter is now |
---|
89 | held by the caller of the function and it is its responsibility to |
---|
90 | release that reference when it is done with the object. |
---|
91 | .PP |
---|
92 | Which functions of a channel driver are allowed to use which bypass |
---|
93 | function is listed below, as is which functions of the public channel |
---|
94 | API may leave a messages in the bypass areas. |
---|
95 | .PP |
---|
96 | .IP \fBTcl_DriverCloseProc\fR |
---|
97 | May use \fBTcl_SetChannelErrorInterp\fR, and only this function. |
---|
98 | .IP \fBTcl_DriverInputProc\fR |
---|
99 | May use \fBTcl_SetChannelError\fR, and only this function. |
---|
100 | .IP \fBTcl_DriverOutputProc\fR |
---|
101 | May use \fBTcl_SetChannelError\fR, and only this function. |
---|
102 | .IP \fBTcl_DriverSeekProc\fR |
---|
103 | May use \fBTcl_SetChannelError\fR, and only this function. |
---|
104 | .IP \fBTcl_DriverWideSeekProc\fR |
---|
105 | May use \fBTcl_SetChannelError\fR, and only this function. |
---|
106 | .IP \fBTcl_DriverSetOptionProc\fR |
---|
107 | Has already the ability to pass arbitrary error messages. Must |
---|
108 | \fBnot\fR use any of the new functions. |
---|
109 | .IP \fBTcl_DriverGetOptionProc\fR |
---|
110 | Has already the ability to pass arbitrary error messages. Must |
---|
111 | \fBnot\fR use any of the new functions. |
---|
112 | .IP \fBTcl_DriverWatchProc\fR |
---|
113 | Must \fBnot\fR use any of the new functions. Is internally called and |
---|
114 | has no ability to return any type of error whatsoever. |
---|
115 | .IP \fBTcl_DriverBlockModeProc\fR |
---|
116 | May use \fBTcl_SetChannelError\fR, and only this function. |
---|
117 | .IP \fBTcl_DriverGetHandleProc\fR |
---|
118 | Must \fBnot\fR use any of the new functions. It is only a low-level |
---|
119 | function, and not used by Tcl commands. |
---|
120 | .IP \fBTcl_DriverHandlerProc\fR |
---|
121 | Must \fBnot\fR use any of the new functions. Is internally called and |
---|
122 | has no ability to return any type of error whatsoever. |
---|
123 | .PP |
---|
124 | Given the information above the following public functions of the Tcl |
---|
125 | C API are affected by these changes. I.e. when these functions are |
---|
126 | called the channel may now contain a stored arbitrary error message |
---|
127 | requiring processing by the caller. |
---|
128 | .PP |
---|
129 | .IP \fBTcl_StackChannel\fR |
---|
130 | .IP \fBTcl_Seek\fR |
---|
131 | .IP \fBTcl_Tell\fR |
---|
132 | .IP \fBTcl_ReadRaw\fR |
---|
133 | .IP \fBTcl_Read\fR |
---|
134 | .IP \fBTcl_ReadChars\fR |
---|
135 | .IP \fBTcl_Gets\fR |
---|
136 | .IP \fBTcl_GetsObj\fR |
---|
137 | .IP \fBTcl_Flush\fR |
---|
138 | .IP \fBTcl_WriteRaw\fR |
---|
139 | .IP \fBTcl_WriteObj\fR |
---|
140 | .IP \fBTcl_Write\fR |
---|
141 | .IP \fBTcl_WriteChars\fR |
---|
142 | .PP |
---|
143 | All other API functions are unchanged. Especially the functions below |
---|
144 | leave all their error information in the interpreter result. |
---|
145 | .PP |
---|
146 | .IP \fBTcl_Close\fR |
---|
147 | .IP \fBTcl_UnregisterChannel\fR |
---|
148 | .IP \fBTcl_UnstackChannel\fR |
---|
149 | |
---|
150 | .SH "SEE ALSO" |
---|
151 | Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) |
---|
152 | |
---|
153 | .SH KEYWORDS |
---|
154 | channel driver, error messages, channel type |
---|