Tcl_SetChannelError man page on AIX

Man page or keyword search:  
man Server   4752 pages
apropos Keyword Search (all sections)
Output format
AIX logo
[printable version]

Tcl_SetChannelError(3)	    Tcl Library Procedures	Tcl_SetChannelError(3)

______________________________________________________________________________

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,  fol‐
				      lowed 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 chan‐
       nel is now held by the caller of the function and it is	its  responsi‐
       bility 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_SetChannelEr‐
       rorInterp  with	a  non-NULL  message. The msgPtr must not be NULL. The
       reference count of the message is not touched.	The  reference	previ‐
       ously 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

Tcl				      8.5		Tcl_SetChannelError(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net