dwww Home | Manual pages | Find package

Tcl_AddErrorInfo(3tcl)      Tcl Library Procedures      Tcl_AddErrorInfo(3tcl)

______________________________________________________________________________

NAME
       Tcl_GetReturnOptions,  Tcl_SetReturnOptions,  Tcl_AddErrorInfo, Tcl_Ap-
       pendObjToErrorInfo,      Tcl_AddObjErrorInfo,      Tcl_SetObjErrorCode,
       Tcl_SetErrorCode,  Tcl_SetErrorCodeVA,  Tcl_SetErrorLine, Tcl_GetError-
       Line, Tcl_PosixError, Tcl_LogCommandInfo - retrieve or record  informa-
       tion 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.

       const 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 -er-
                                              rorinfo  return  option.    This
                                              byte  array may contain embedded
                                              null bytes unless length is neg-
                                              ative.

       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.

       const 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 re-
       turn an integer completion code.  These routines also leave in the  in-
       terpreter 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 refer-
       ence 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_SetOb-
       jResult 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 al-
       low for a more efficient alternative that meshes better with the  byte-
       code compiler.)

       Note that a newly created Tcl_Obj may be passed in as the options argu-
       ment without the need to tend to any reference counting.  This is anal-
       ogous to Tcl_SetObjResult.

       While Tcl_SetReturnOptions provides a general interface to set any col-
       lection 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 lo-
       cation  information  in the stack trace text they append to the -error-
       info 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-read-
       able.   The  -errorcode  option  holds a Tcl list of items that are in-
       tended 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  addi-
       tional  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 -er-
       rorinfo  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 evalua-
       tion routines.  Tcl_AddErrorInfo may be used for this purpose: its mes-
       sage  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.  Like-
       wise,  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  func-
       tionality 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_SetO-
       bjErrorCode  is typically invoked just before returning an error. If an
       error is returned without calling Tcl_SetObjErrorCode or  Tcl_SetError-
       Code  the  Tcl interpreter automatically sets the -errorcode return op-
       tion to NONE.

       The procedure Tcl_SetErrorCode is also used to set the  -errorcode  re-
       turn 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_Ge-
       tReturnOptions.   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  for-
       mat.  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 er-
       ror (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  inter-
       preter'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 in-
       ternally 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 writ-
       ten  for  older  Tcl  releases  still access this information via those
       global variables.

       It is important to realize that while reading from those  global  vari-
       ables  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 empha-
       sized 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 en-
       tire return options dictionary.  In particular, the -errorinfo and -er-
       rorcode  options are reset.  If an error had occurred, the Tcl_ResetRe-
       sult 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),   error-
       Info(3tcl)

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

Tcl                                   8.5               Tcl_AddErrorInfo(3tcl)

Generated by dwww version 1.14 on Thu Dec 19 13:23:20 CET 2024.