Tcl_LogCommandInfo man page on OpenMandriva

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

Tcl_AddErrorInfo(3)	    Tcl Library Procedures	   Tcl_AddErrorInfo(3)

______________________________________________________________________________

NAME
       Tcl_GetReturnOptions,	  Tcl_SetReturnOptions,	     Tcl_AddErrorInfo,
       Tcl_AppendObjToErrorInfo,   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.

       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 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.

       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 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
       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 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
       location 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 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 tclvars manual entry 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 activ‐
       ity 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
       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	behav‐
       ior.

       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 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
       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 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
       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 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
       entire  return  options	dictionary.  In particular, the -errorinfo and
       -errorcode options are reset.  If an error had occurred, the  Tcl_Rese‐
       tResult	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	inter‐
       preter.

SEE ALSO
       Tcl_DecrRefCount(3),  Tcl_IncrRefCount(3),  Tcl_Interp(3), Tcl_ResetRe‐
       sult(3), Tcl_SetErrno(3), tclvars(n)

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

Tcl				      8.5		   Tcl_AddErrorInfo(3)
[top]

List of man pages available for OpenMandriva

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