Provided by: tcl8.6-doc_8.6.9+dfsg-2_all bug

NAME

       Tcl_GetReturnOptions,  Tcl_SetReturnOptions,  Tcl_AddErrorInfo,  Tcl_AppendObjToErrorInfo,
       Tcl_AddObjErrorInfo,    Tcl_SetObjErrorCode,     Tcl_SetErrorCode,     Tcl_SetErrorCodeVA,
       Tcl_SetErrorLine,  Tcl_GetErrorLine,  Tcl_PosixError,  Tcl_LogCommandInfo  -  retrieve  or
       record information about errors and other return options

SYNOPSIS

       #include <tcl.h>

       Tcl_Obj *
       Tcl_GetReturnOptions(interp, code)

       int
       Tcl_SetReturnOptions(interp, options)

       Tcl_AddErrorInfo(interp, message)

       Tcl_AppendObjToErrorInfo(interp, objPtr)

       Tcl_AddObjErrorInfo(interp, message, length)

       Tcl_SetObjErrorCode(interp, errorObjPtr)

       Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)

       Tcl_SetErrorCodeVA(interp, argList)

       Tcl_GetErrorLine(interp)

       Tcl_SetErrorLine(interp, lineNum)

       const char *
       Tcl_PosixError(interp)

       void
       Tcl_LogCommandInfo(interp, script, command, commandLength)

ARGUMENTS

       Tcl_Interp *interp (in)                Interpreter in which to record information.

       int          code                      The code returned from script evaluation.

       Tcl_Obj      *options                  A dictionary of return options.

       char *message (in)                     For Tcl_AddErrorInfo,  this  is  a  conventional  C
                                              string  to  append to the -errorinfo return option.
                                              For Tcl_AddObjErrorInfo, this points to  the  first
                                              byte  of  an  array  of  length  bytes containing a
                                              string to append to the -errorinfo  return  option.
                                              This  byte  array  may  contain embedded null bytes
                                              unless length is negative.

       Tcl_Obj *objPtr (in)                   A message to be appended to the  -errorinfo  return
                                              option in the form of a Tcl_Obj value.

       int length (in)                        The  number  of  bytes  to  copy  from message when
                                              appending to  the  -errorinfo  return  option.   If
                                              negative,  all  bytes up to the first null byte are
                                              used.

       Tcl_Obj *errorObjPtr (in)              The -errorcode return option will be  set  to  this
                                              value.

       char *element (in)                     String  to  record as one element of the -errorcode
                                              return option.  Last element argument must be NULL.

       va_list argList (in)                   An argument list which must have  been  initialized
                                              using va_start, and cleared using va_end.

       int          lineNum                   The   line  number  of  a  script  where  an  error
                                              occurred.

       const char *script (in)                Pointer to first  character  in  script  containing
                                              command (must be <= command)

       const char *command (in)               Pointer   to   first   character  in  command  that
                                              generated the error

       int commandLength (in)                 Number of bytes in command; -1 means use all  bytes
                                              up to first null byte
_________________________________________________________________________________________________

DESCRIPTION

       The Tcl_SetReturnOptions and Tcl_GetReturnOptions routines expose the same capabilities as
       the return and catch commands, respectively, in the form of a C interface.

       Tcl_GetReturnOptions retrieves the  dictionary  of  return  options  from  an  interpreter
       following  a script evaluation.  Routines such as Tcl_Eval are called to evaluate a script
       in an interpreter.  These routines return an integer completion code.  These routines also
       leave  in  the  interpreter  both a result and a dictionary of return options generated by
       script evaluation.  Just as Tcl_GetObjResult retrieves  the  result,  Tcl_GetReturnOptions
       retrieves  the dictionary of return options.  The integer completion code should be passed
       as the code argument to Tcl_GetReturnOptions so that all required options will be  present
       in  the  dictionary.  Specifically, a code value of TCL_ERROR will ensure that entries for
       the keys -errorinfo, -errorcode, and -errorline will appear in the dictionary.  Also,  the
       entries  for  the  keys  -code  and -level will be adjusted if necessary to agree with the
       value of code.  The (Tcl_Obj *) returned by Tcl_GetReturnOptions  points  to  an  unshared
       Tcl_Obj  with  reference  count of zero.  The dictionary may be written to, either adding,
       removing, or overwriting any entries in it, without the need to check for a shared  value.
       As  with  any  Tcl_Obj with reference count of zero, it is up to the caller to arrange for
       its disposal with Tcl_DecrRefCount or to a reference to it via Tcl_IncrRefCount (or one of
       the many functions that call that, notably including Tcl_SetObjResult and Tcl_SetVar2Ex).

       A  typical  usage  for  Tcl_GetReturnOptions  is  to  retrieve the stack trace when script
       evaluation returns TCL_ERROR, like so:

              int code = Tcl_Eval(interp, script);
              if (code == TCL_ERROR) {
                  Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);
                  Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
                  Tcl_Obj *stackTrace;
                  Tcl_IncrRefCount(key);
                  Tcl_DictObjGet(NULL, options, key, &stackTrace);
                  Tcl_DecrRefCount(key);
                  /* Do something with stackTrace */
                  Tcl_DecrRefCount(options);
              }

       Tcl_SetReturnOptions sets the return options of interp to be options.  If options contains
       any  invalid  value for any key, TCL_ERROR will be returned, and the interp result will be
       set to an appropriate error message.  Otherwise, a completion code in agreement  with  the
       -code and -level keys in options will be returned.

       As   an   example,   Tcl's  return  command  itself  could  be  implemented  in  terms  of
       Tcl_SetReturnOptions like so:

              if ((objc % 2) == 0) { /* explicit result argument */
                  objc--;
                  Tcl_SetObjResult(interp, objv[objc]);
              }
              return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));

       (It is not really implemented that way.  Internal  access  privileges  allow  for  a  more
       efficient alternative that meshes better with the bytecode compiler.)

       Note  that  a  newly  created Tcl_Obj may be passed in as the options argument without the
       need to tend to any reference counting.  This is analogous to Tcl_SetObjResult.

       While Tcl_SetReturnOptions provides a general interface to set any  collection  of  return
       options,  there  are  a  handful  of  return  options that are very frequently used.  Most
       notably the -errorinfo and -errorcode return options  should  be  set  properly  when  the
       command  procedure  of  a command returns TCL_ERROR.  The -errorline return option is also
       read by commands that  evaluate  scripts  and  wish  to  supply  detailed  error  location
       information  in  the  stack trace text they append to the -errorinfo option.  Tcl provides
       several simpler interfaces to more directly set these return options.

       The -errorinfo option holds a stack trace of the operations that were in progress when  an
       error  occurred,  and is intended to be human-readable.  The -errorcode option holds a Tcl
       list of items that are intended to be machine-readable.  The first item in the  -errorcode
       value  identifies the class of error that occurred (e.g., POSIX means an error occurred in
       a POSIX system call) and additional elements hold additional pieces  of  information  that
       depend  on  the  class.  See the manual entry on the errorCode variable for details on the
       various formats for the -errorcode option used by Tcl's built-in commands.

       The -errorinfo option value is gradually built up as an error unwinds through  the  nested
       operations.   Each time an error code is returned to Tcl_Eval, or any of the routines that
       performs script evaluation, the procedure Tcl_AddErrorInfo is  called  to  add  additional
       text to the -errorinfo value describing the command that was being executed when the error
       occurred.  By the time the error has been passed all the way back to the  application,  it
       will contain a complete trace of the activity in progress when the error occurred.

       It  is  sometimes useful to add additional information to the -errorinfo value beyond what
       can be supplied automatically by the script evaluation routines.  Tcl_AddErrorInfo may  be
       used  for this purpose: its message argument is an additional string to be appended to the
       -errorinfo option.  For example, when an error  arises  during  the  source  command,  the
       procedure  Tcl_AddErrorInfo  is  called to record the name of the file being processed and
       the line number on which the error  occurred.   Likewise,  when  an  error  arises  during
       evaluation  of  a  Tcl procedures, the procedure name and line number within the procedure
       are recorded, and so on.  The best time to call Tcl_AddErrorInfo is just  after  a  script
       evaluation  routine  has  returned  TCL_ERROR.   The value of the -errorline return option
       (retrieved via a call to Tcl_GetReturnOptions) often makes up a useful part of the message
       passed to Tcl_AddErrorInfo.

       Tcl_AppendObjToErrorInfo  is  an  alternative  interface  to  the  same  functionality  as
       Tcl_AddErrorInfo.  Tcl_AppendObjToErrorInfo is called when the string value to be appended
       to the -errorinfo option is available as a Tcl_Obj instead of as a char array.

       Tcl_AddObjErrorInfo  is  nearly  identical  to  Tcl_AddErrorInfo,  except  that  it has an
       additional length argument.  This allows the  message  string  to  contain  embedded  null
       bytes.   This  is essentially never a good idea.  If the message needs to contain the null
       character U+0000, Tcl's usual internal encoding rules should be used to avoid the need for
       a  null  byte.   If  the Tcl_AddObjErrorInfo interface is used at all, it should be with a
       negative length value.

       The procedure Tcl_SetObjErrorCode is used to set the -errorcode return option to the  list
       value  errorObjPtr  built up by the caller.  Tcl_SetObjErrorCode is typically invoked just
       before returning an error. If an error is returned without calling Tcl_SetObjErrorCode  or
       Tcl_SetErrorCode  the  Tcl  interpreter automatically sets the -errorcode return option to
       NONE.

       The procedure Tcl_SetErrorCode is also used to set the -errorcode return option.  However,
       it  takes  one  or  more strings to record instead of a value. Otherwise, it is similar to
       Tcl_SetObjErrorCode in behavior.

       Tcl_SetErrorCodeVA is the same  as  Tcl_SetErrorCode  except  that  instead  of  taking  a
       variable number of arguments it takes an argument list.

       The  procedure Tcl_GetErrorLine is used to read the integer value of the -errorline return
       option  without  the  overhead  of  a  full  call  to   Tcl_GetReturnOptions.    Likewise,
       Tcl_SetErrorLine sets the -errorline return option value.

       Tcl_PosixError  sets  the  -errorcode  variable after an error in a POSIX kernel call.  It
       reads the value of the errno C variable and calls Tcl_SetErrorCode to set  the  -errorcode
       return option in the POSIX format.  The caller must previously have called Tcl_SetErrno to
       set errno; this is necessary on some platforms (e.g. Windows) where Tcl is linked into  an
       application  as  a  shared  library,  or  when  the  error  occurs in a dynamically loaded
       extension. See the manual entry for Tcl_SetErrno for more information.

       Tcl_PosixError returns a human-readable diagnostic message for the error (this is the same
       value  that  will  appear  as  the  third  element  in  the  -errorcode value).  It may be
       convenient to include this string as part of the error message returned to the application
       in the interpreter's result.

       Tcl_LogCommandInfo  is  invoked  after  an  error  occurs  in  an  interpreter.   It  adds
       information about the command that was being executed  when  the  error  occurred  to  the
       -errorinfo value, and the line number stored internally in the interpreter is set.

       In  older  releases  of Tcl, there was no Tcl_GetReturnOptions routine.  In its place, the
       global Tcl variables errorInfo and errorCode were the only place  to  retrieve  the  error
       information.   Much  existing  code  written  for  older  Tcl  releases  still access this
       information via those global variables.

       It is important to realize that while  reading  from  those  global  variables  remains  a
       supported  way  to  access  these return option values, it is important not to assume that
       writing to those global variables will properly set the corresponding return options.   It
       has  long  been emphasized in this manual page that it is important to call the procedures
       described here rather than setting errorInfo or errorCode directly with Tcl_ObjSetVar2.

       If the procedure Tcl_ResetResult is called, it clears all of the state of the  interpreter
       associated  with  script  evaluation,  including the entire return options dictionary.  In
       particular, the -errorinfo and -errorcode options are reset.  If an  error  had  occurred,
       the  Tcl_ResetResult  call will clear the error state to make it appear as if no error had
       occurred after all.  The global variables errorInfo and  errorCode  are  not  modified  by
       Tcl_ResetResult  so  they  continue  to hold a record of information about the most recent
       error seen in an interpreter.

SEE ALSO

       Tcl_DecrRefCount(3tcl), Tcl_IncrRefCount(3tcl),  Tcl_Interp(3tcl),  Tcl_ResetResult(3tcl),
       Tcl_SetErrno(3tcl), errorCode(3tcl), errorInfo(3tcl)

KEYWORDS

       error, value, value result, stack, trace, variable