Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_SetChannelError(3)                     Tcl Library Procedures                     Tcl_SetChannelError(3)



____________________________________________________________________________________________________________

NAME
       Tcl_SetChannelError,   Tcl_SetChannelErrorInterp,  Tcl_GetChannelError,  Tcl_GetChannelErrorInterp  -functions Tcl_GetChannelErrorInterpfunctions
       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 dis-carded, discarded,
       carded,  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 msg-Ptr msgPtr
       Ptr  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 invo-cations invocations
       cations  will  return  NULL, until an intervening invocation of Tcl_SetChannelErrorInterp with a non-NULL nonNULL
       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 func-tions. functions.
              tions.

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

       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  informa-tion information
       tion 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)