1Tcl_SetChannelError(3) Tcl Library Procedures Tcl_SetChannelError(3)
2______________________________________________________________________________
6
8 Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError,
9 Tcl_GetChannelErrorInterp - functions to create/intercept Tcl errors by
10 channel drivers.
11
13 #include <tcl.h>
14 void
16 Tcl_SetChannelError(chan, msg)
17 void
19 Tcl_SetChannelErrorInterp(interp, msg)
20 void
22 Tcl_GetChannelError(chan, msgPtr)
23 void
25 Tcl_GetChannelErrorInterp(interp, msgPtr)
26
29 Tcl_Channel chan (in) Refers to the Tcl channel whose bypass
30 area is accessed.
31 Tcl_Interp* interp (in) Refers to the Tcl interpreter whose
33 bypass area is accessed.
34 Tcl_Obj* msg (in) Error message put into a bypass area. A
36 list of return options and values, fol‐
37 lowed by a string message. Both message
38 and the option/value information are
39 optional.
40 Tcl_Obj** msgPtr (out) Reference to a place where the message
42 stored in the accessed bypass area can
43 be stored in.
44_________________________________________________________________
45
47 The current definition of a Tcl channel driver does not permit the
48 direct return of arbitrary error messages, except for the setting and
49 retrieval of channel options. All other functions are restricted to
50 POSIX error codes.
51 The functions described here overcome this limitation. Channel drivers
53 are allowed to use Tcl_SetChannelError and Tcl_SetChannelErrorInterp to
54 place arbitrary error messages in bypass areas defined for channels and
55 interpreters. And the generic I/O layer uses Tcl_GetChannelError and
56 Tcl_GetChannelErrorInterp to look for messages in the bypass areas and
57 arrange for their return as errors. The posix error codes set by a
58 driver are used now if and only if no messages are present.
59 Tcl_SetChannelError stores error information in the bypass area of the
61 specified channel. The number of references to the msg object goes up
62 by one. Previously stored information will be discarded, by releasing
63 the reference held by the channel. The channel reference must not be
64 NULL.
65 Tcl_SetChannelErrorInterp stores error information in the bypass area
67 of the specified interpreter. The number of references to the msg
68 object goes up by one. Previously stored information will be discarded,
69 by releasing the reference held by the interpreter. The interpreter
70 reference must not be NULL.
71 Tcl_GetChannelError places either the error message held in the bypass
73 area of the specified channel into msgPtr, or NULL; and resets the
74 bypass. I.e. after an invocation all following invocations will return
75 NULL, until an intervening invocation of Tcl_SetChannelError with a
76 non-NULL message. The msgPtr must not be NULL. The reference count of
77 the message is not touched. The reference previously held by the chan‐
78 nel is now held by the caller of the function and it is its responsi‐
79 bility to release that reference when it is done with the object.
80 Tcl_GetChannelErrorInterp places either the error message held in the
82 bypass area of the specified interpreter into msgPtr, or NULL; and
83 resets the bypass. I.e. after an invocation all following invocations
84 will return NULL, until an intervening invocation of Tcl_SetChannelEr‐
85 rorInterp with a non-NULL message. The msgPtr must not be NULL. The
86 reference count of the message is not touched. The reference previ‐
87 ously held by the interpreter is now held by the caller of the function
88 and it is its responsibility to release that reference when it is done
89 with the object.
90 Which functions of a channel driver are allowed to use which bypass
92 function is listed below, as is which functions of the public channel
93 API may leave a messages in the bypass areas.
94 Tcl_DriverCloseProc
96 May use Tcl_SetChannelErrorInterp, and only this function.
97 Tcl_DriverInputProc
99 May use Tcl_SetChannelError, and only this function.
100 Tcl_DriverOutputProc
102 May use Tcl_SetChannelError, and only this function.
103 Tcl_DriverSeekProc
105 May use Tcl_SetChannelError, and only this function.
106 Tcl_DriverWideSeekProc
108 May use Tcl_SetChannelError, and only this function.
109 Tcl_DriverSetOptionProc
111 Has already the ability to pass arbitrary error messages. Must
112 not use any of the new functions.
113 Tcl_DriverGetOptionProc
115 Has already the ability to pass arbitrary error messages. Must
116 not use any of the new functions.
117 Tcl_DriverWatchProc
119 Must not use any of the new functions. Is internally called and
120 has no ability to return any type of error whatsoever.
121 Tcl_DriverBlockModeProc
123 May use Tcl_SetChannelError, and only this function.
124 Tcl_DriverGetHandleProc
126 Must not use any of the new functions. It is only a low-level
127 function, and not used by Tcl commands.
128 Tcl_DriverHandlerProc
130 Must not use any of the new functions. Is internally called and
131 has no ability to return any type of error whatsoever.
132 Given the information above the following public functions of the Tcl C
134 API are affected by these changes. I.e. when these functions are called
135 the channel may now contain a stored arbitrary error message requiring
136 processing by the caller.
137 Tcl_StackChannel
139 Tcl_Seek
141 Tcl_Tell
143 Tcl_ReadRaw
145 Tcl_Read
147 Tcl_ReadChars
149 Tcl_Gets
151 Tcl_GetsObj
153 Tcl_Flush
155 Tcl_WriteRaw
157 Tcl_WriteObj
159 Tcl_Write
161 Tcl_WriteChars
163 All other API functions are unchanged. Especially the functions below
165 leave all their error information in the interpreter result.
166 Tcl_Close
168 Tcl_UnregisterChannel
170 Tcl_UnstackChannel
172
175 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
176
179 channel driver, error messages, channel type
180Tcl 8.5 Tcl_SetChannelError(3)