Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  by-
				      pass 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 op-
				      tional.

       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 di-
       rect return of arbitrary	error messages,	except for the setting and re-
       trieval 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 ob-
       ject 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 by-
       pass. 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  re-
       sets  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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_GetChannelError.tcl85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help