1Tcl_SetChannelError(3)      Tcl Library Procedures      Tcl_SetChannelError(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_SetChannelError,   Tcl_SetChannelErrorInterp,  Tcl_GetChannelError,
9       Tcl_GetChannelErrorInterp - functions to create/intercept Tcl errors by
10       channel drivers.
11

SYNOPSIS

13       #include <tcl.h>
14
15       void
16       Tcl_SetChannelError(chan, msg)
17
18       void
19       Tcl_SetChannelErrorInterp(interp, msg)
20
21       void
22       Tcl_GetChannelError(chan, msgPtr)
23
24       void
25       Tcl_GetChannelErrorInterp(interp, msgPtr)
26
27

ARGUMENTS

29       Tcl_Channel chan (in)          Refers  to  the Tcl channel whose bypass
30                                      area is accessed.
31
32       Tcl_Interp* interp (in)        Refers  to  the  Tcl  interpreter  whose
33                                      bypass area is accessed.
34
35       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
41       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

DESCRIPTION

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
52       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
60       Tcl_SetChannelError stores error information in the bypass area of  the
61       specified channel. The number of references to the msg value goes up by
62       one. Previously stored information will be discarded, by releasing  the
63       reference held by the channel. The channel reference must not be NULL.
64
65       Tcl_SetChannelErrorInterp  stores  error information in the bypass area
66       of the specified interpreter. The number of references to the msg value
67       goes  up  by  one.  Previously stored information will be discarded, by
68       releasing the reference held by the interpreter. The interpreter refer‐
69       ence must not be NULL.
70
71       Tcl_GetChannelError  places either the error message held in the bypass
72       area of the specified channel into msgPtr,  or  NULL;  and  resets  the
73       bypass,  that  is,  after  an invocation all following invocations will
74       return NULL, until an  intervening  invocation  of  Tcl_SetChannelError
75       with  a  non-NULL  message.  The msgPtr must not be NULL. The reference
76       count of the message is not touched.  The reference previously held  by
77       the  channel  is  now  held by the caller of the function and it is its
78       responsibility to release that reference  when  it  is  done  with  the
79       value.
80
81       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, that is, after an invocation all following invoca‐
84       tions will return NULL, until an intervening invocation of Tcl_SetChan‐
85       nelErrorInterp  with  a  non-NULL message. The msgPtr must not be NULL.
86       The reference count of the message is not touched.  The reference  pre‐
87       viously  held by the interpreter is now held by the caller of the func‐
88       tion and it is its responsibility to release that reference when it  is
89       done with the value.
90
91       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
95       Tcl_DriverCloseProc
96              May use Tcl_SetChannelErrorInterp, and only this function.
97
98       Tcl_DriverInputProc
99              May use Tcl_SetChannelError, and only this function.
100
101       Tcl_DriverOutputProc
102              May use Tcl_SetChannelError, and only this function.
103
104       Tcl_DriverSeekProc
105              May use Tcl_SetChannelError, and only this function.
106
107       Tcl_DriverWideSeekProc
108              May use Tcl_SetChannelError, and only this function.
109
110       Tcl_DriverSetOptionProc
111              Has  already  the ability to pass arbitrary error messages. Must
112              not use any of the new functions.
113
114       Tcl_DriverGetOptionProc
115              Has already the ability to pass arbitrary error  messages.  Must
116              not use any of the new functions.
117
118       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
122       Tcl_DriverBlockModeProc
123              May use Tcl_SetChannelError, and only this function.
124
125       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
129       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
133       Given the information above the following public functions of the Tcl C
134       API are affected by these changes; when these functions are called, the
135       channel may now contain a stored arbitrary error message requiring pro‐
136       cessing by the caller.
137
138              Tcl_Flush          Tcl_GetsObj          Tcl_Gets
139              Tcl_ReadChars      Tcl_ReadRaw          Tcl_Read
140              Tcl_Seek           Tcl_StackChannel     Tcl_Tell
141              Tcl_WriteChars     Tcl_WriteObj         Tcl_WriteRaw
142              Tcl_Write
143
144
145       All  other  API  functions  are unchanged. In particular, the functions
146       below leave all their error information in the interpreter result.
147
148              Tcl_Close          Tcl_UnstackChannel   Tcl_UnregisterChannel
149
150

SEE ALSO

152       Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
153

KEYWORDS

155       channel driver, error messages, channel type
156
157
158
159Tcl                                   8.5               Tcl_SetChannelError(3)
Impressum