Tcl_SetChannelError


HOME

Tcl_SetChannelError

NAME
SYNOPSIS
ARGUMENTS
DESCRIPTION
SEE ALSO
KEYWORDS

___________________________

NAME

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

SYNOPSIS

#include <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(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)

KEYWORDS

channel driver, error messages, channel type






Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.