Tcl_SetChannelError manual page - Tcl Library Procedures

## Tcl8.5.15/Tk8.5.15 Documentation > TclLib > SetChanErr

### Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

  NAME
    Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChannelErrorInterp - functions to create/intercept Tcl errors by channel drivers.
  SYNOPSIS
    #include <tcl8.5/tcl.h>
    void
    Tcl_SetChannelError(chan, msg)
    void
    Tcl_SetChannelErrorInterp(interp, msg)
    void
    Tcl_GetChannelError(chan, msgPtr)
    void
    Tcl_GetChannelErrorInterp(interp, msgPtr)
  ARGUMENTS
  DESCRIPTION
    Tcl_DriverCloseProc
    Tcl_DriverInputProc
    Tcl_DriverOutputProc
    Tcl_DriverSeekProc
    Tcl_DriverWideSeekProc
    Tcl_DriverSetOptionProc
    Tcl_DriverGetOptionProc
    Tcl_DriverWatchProc
    Tcl_DriverBlockModeProc
    Tcl_DriverGetHandleProc
    Tcl_DriverHandlerProc
    Tcl_StackChannel
    Tcl_Seek
    Tcl_Tell
    Tcl_ReadRaw
    Tcl_Read
    Tcl_ReadChars
    Tcl_Gets
    Tcl_GetsObj
    Tcl_Flush
    Tcl_WriteRaw
    Tcl_WriteObj
    Tcl_Write
    Tcl_WriteChars
    Tcl_Close
    Tcl_UnregisterChannel
    Tcl_UnstackChannel
  SEE ALSO
  KEYWORDS

### NAME

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

### SYNOPSIS

#include <tcl8.5/tcl.h>
void
Tcl_SetChannelError(chan, msg)
void
Tcl_SetChannelErrorInterp(interp, msg)
void
Tcl_GetChannelError(chan, msgPtr)
void
Tcl_GetChannelErrorInterp(interp, msgPtr)

### ARGUMENTS

Tcl_Channel chan (in)
  Refers to the Tcl channel whose bypass area is accessed.

Tcl_Interp* interp (in)
  Refers to the Tcl interpreter whose bypass area is accessed.

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.

Tcl_Obj** msgPtr (out)
  Reference to a place where the message stored in the accessed bypass area can be stored in.

### DESCRIPTION

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.

The functions described here overcome this limitation. Channel drivers are allowed to use Tcl_SetChannelError and Tcl_SetChannelErrorInterp to place arbitrary error messages in bypass areas defined for channels and interpreters. And the generic I/O layer uses Tcl_GetChannelError and Tcl_GetChannelErrorInterp 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.

Tcl_SetChannelError stores error information in the bypass area of the specified channel. The number of references to the msg 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.

Tcl_SetChannelErrorInterp stores error information in the bypass area of the specified interpreter. The number of references to the msg 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.

Tcl_GetChannelError places either the error message held in the bypass area of the specified channel into msgPtr, or NULL; and resets the bypass. I.e. after an invocation all following invocations will return NULL, until an intervening invocation of Tcl_SetChannelError with a non-NULL message. The msgPtr 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.

Tcl_GetChannelErrorInterp places either the error message held in the bypass area of the specified interpreter into msgPtr, or NULL; and resets the bypass. I.e. after an invocation all following invocations will return NULL, until an intervening invocation of Tcl_SetChannelErrorInterp with a non-NULL message. The msgPtr 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.

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.

Tcl_DriverCloseProc
  May use Tcl_SetChannelErrorInterp, and only this function.

Tcl_DriverInputProc
  May use Tcl_SetChannelError, and only this function.

Tcl_DriverOutputProc
  May use Tcl_SetChannelError, and only this function.

Tcl_DriverSeekProc
  May use Tcl_SetChannelError, and only this function.

Tcl_DriverWideSeekProc
  May use Tcl_SetChannelError, and only this function.

Tcl_DriverSetOptionProc
  Has already the ability to pass arbitrary error messages. Must not use any of the new functions.

Tcl_DriverGetOptionProc
  Has already the ability to pass arbitrary error messages. Must not use any of the new functions.

Tcl_DriverWatchProc
  Must not use any of the new functions. Is internally called and has no ability to return any type of error whatsoever.

Tcl_DriverBlockModeProc
  May use Tcl_SetChannelError, and only this function.

Tcl_DriverGetHandleProc
  Must not use any of the new functions. It is only a low-level function, and not used by Tcl commands.

Tcl_DriverHandlerProc
  Must not use any of the new functions. Is internally called and has no ability to return any type of error whatsoever.

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.

Tcl_StackChannel

Tcl_Seek

Tcl_Tell

Tcl_ReadRaw

Tcl_Read

Tcl_ReadChars

Tcl_Gets

Tcl_GetsObj

Tcl_Flush

Tcl_WriteRaw

Tcl_WriteObj

Tcl_Write

Tcl_WriteChars

All other API functions are unchanged. Especially the functions below leave all their error information in the interpreter result.

Tcl_Close

Tcl_UnregisterChannel

Tcl_UnstackChannel

### SEE ALSO

Tcl_Close, Tcl_OpenFileChannel, Tcl_SetErrno

### KEYWORDS

channel driver, error messages, channel type
Copyright © 1995-1997 Roger E. Critchlow Jr. Copyright © 2005 Andreas Kupries <andreas_kupries(at)users.sourceforge.net>