util/X86LINUX64/man/man3/Tcl_GetChannelErrorInterp.3

   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 .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 '\" Note:  do not modify the .SH NAME line immediately below!
 277 .SH NAME
 278 Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp \- functions to create/intercept Tcl errors by channel drivers.
 279 .SH SYNOPSIS
 280 .nf
 281 \fB#include <tcl.h>\fR
 282 .sp
 283 void
 284 \fBTcl_SetChannelError\fR(\fIchan, msg\fR)
 285 .sp
 286 void
 287 \fBTcl_SetChannelErrorInterp\fR(\fIinterp, msg\fR)
 288 .sp
 289 void
 290 \fBTcl_GetChannelError\fR(\fIchan, msgPtr\fR)
 291 .sp
 292 void
 293 \fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR)
 294 .sp
 295 .SH ARGUMENTS
 296 .AS Tcl_Channel chan
 297 .AP Tcl_Channel chan in
 298 Refers to the Tcl channel whose bypass area is accessed.
 299 .AP Tcl_Interp* interp in
 300 Refers to the Tcl interpreter whose bypass area is accessed.
 301 .AP Tcl_Obj* msg in
 302 Error message put into a bypass area. A list of return options and values,
 303 followed by a string message. Both message and the option/value information
 304 are optional.
 305 .AP Tcl_Obj** msgPtr out
 306 Reference to a place where the message stored in the accessed bypass area can
 307 be stored in.
 308 .BE
 309 .SH DESCRIPTION
 310 .PP
 311 The current definition of a Tcl channel driver does not permit the direct
 312 return of arbitrary error messages, except for the setting and retrieval of
 313 channel options. All other functions are restricted to POSIX error codes.
 314 .PP
 315 The functions described here overcome this limitation. Channel drivers are
 316 allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR
 317 to place arbitrary error messages in \fBbypass areas\fR defined for channels
 318 and interpreters. And the generic I/O layer uses \fBTcl_GetChannelError\fR and
 319 \fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass areas and
 320 arrange for their return as errors. The POSIX error codes set by a driver are
 321 used now if and only if no messages are present.
 322 .PP
 323 \fBTcl_SetChannelError\fR stores error information in the bypass area of the
 324 specified channel. The number of references to the \fBmsg\fR value goes up by
 325 one. Previously stored information will be discarded, by releasing the
 326 reference held by the channel. The channel reference must not be NULL.
 327 .PP
 328 \fBTcl_SetChannelErrorInterp\fR stores error information in the bypass area of
 329 the specified interpreter. The number of references to the \fBmsg\fR value
 330 goes up by one. Previously stored information will be discarded, by releasing
 331 the reference held by the interpreter. The interpreter reference must not be
 332 NULL.
 333 .PP
 334 \fBTcl_GetChannelError\fR places either the error message held in the bypass
 335 area of the specified channel into \fImsgPtr\fR, or NULL; and resets the
 336 bypass, that is, after an invocation all following invocations will return
 337 NULL, until an intervening invocation of \fBTcl_SetChannelError\fR with a
 338 non-NULL message. The \fImsgPtr\fR must not be NULL. The reference count of
 339 the message is not touched.  The reference previously held by the channel is
 340 now held by the caller of the function and it is its responsibility to release
 341 that reference when it is done with the value.
 342 .PP
 343 \fBTcl_GetChannelErrorInterp\fR places either the error message held in the
 344 bypass area of the specified interpreter into \fImsgPtr\fR, or NULL; and
 345 resets the bypass, that is, after an invocation all following invocations will
 346 return NULL, until an intervening invocation of
 347 \fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The \fImsgPtr\fR must
 348 not be NULL. The reference count of the message is not touched.  The reference
 349 previously held by the interpreter is now held by the caller of the function
 350 and it is its responsibility to release that reference when it is done with
 351 the value.
 352 .PP
 353 Which functions of a channel driver are allowed to use which bypass function
 354 is listed below, as is which functions of the public channel API may leave a
 355 messages in the bypass areas.
 356 .IP \fBTcl_DriverCloseProc\fR
 357 May use \fBTcl_SetChannelErrorInterp\fR, and only this function.
 358 .IP \fBTcl_DriverInputProc\fR
 359 May use \fBTcl_SetChannelError\fR, and only this function.
 360 .IP \fBTcl_DriverOutputProc\fR
 361 May use \fBTcl_SetChannelError\fR, and only this function.
 362 .IP \fBTcl_DriverSeekProc\fR
 363 May use \fBTcl_SetChannelError\fR, and only this function.
 364 .IP \fBTcl_DriverWideSeekProc\fR
 365 May use \fBTcl_SetChannelError\fR, and only this function.
 366 .IP \fBTcl_DriverSetOptionProc\fR
 367 Has already the ability to pass arbitrary error messages. Must \fInot\fR use
 368 any of the new functions.
 369 .IP \fBTcl_DriverGetOptionProc\fR
 370 Has already the ability to pass arbitrary error messages. Must
 371 \fInot\fR use any of the new functions.
 372 .IP \fBTcl_DriverWatchProc\fR
 373 Must \fInot\fR use any of the new functions. Is internally called and has no
 374 ability to return any type of error whatsoever.
 375 .IP \fBTcl_DriverBlockModeProc\fR
 376 May use \fBTcl_SetChannelError\fR, and only this function.
 377 .IP \fBTcl_DriverGetHandleProc\fR
 378 Must \fInot\fR use any of the new functions. It is only a low-level function,
 379 and not used by Tcl commands.
 380 .IP \fBTcl_DriverHandlerProc\fR
 381 Must \fInot\fR use any of the new functions. Is internally called and has no
 382 ability to return any type of error whatsoever.
 383 .PP
 384 Given the information above the following public functions of the Tcl C API
 385 are affected by these changes; when these functions are called, the channel
 386 may now contain a stored arbitrary error message requiring processing by the
 387 caller.
 388 .DS
 389 .ta 1.9i 4i
 390 \fBTcl_Flush\fR \fBTcl_GetsObj\fR       \fBTcl_Gets\fR
 391 \fBTcl_ReadChars\fR     \fBTcl_ReadRaw\fR       \fBTcl_Read\fR
 392 \fBTcl_Seek\fR  \fBTcl_StackChannel\fR  \fBTcl_Tell\fR
 393 \fBTcl_WriteChars\fR    \fBTcl_WriteObj\fR      \fBTcl_WriteRaw\fR
 394 \fBTcl_Write\fR
 395 .DE
 396 .PP
 397 All other API functions are unchanged. In particular, the functions below
 398 leave all their error information in the interpreter result.
 399 .DS
 400 .ta 1.9i 4i
 401 \fBTcl_Close\fR \fBTcl_UnstackChannel\fR        \fBTcl_UnregisterChannel\fR
 402 .DE
 403 .SH "SEE ALSO"
 404 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
 405 .SH KEYWORDS
 406 channel driver, error messages, channel type