Linux Manual Pages

Free Software * Books

Source Code

Free Media

Linux

Tcl_TraceCommand

NAME
SYNOPSIS
ARGUMENTS
DESCRIPTION
CALLING COMMANDS DURING TRACES
MULTIPLE TRACES
TCL_TRACE_DESTROYED FLAG
TCL_INTERP_DESTROYED
BUGS
KEYWORDS

___________________________

NAME

Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand − monitor renames and deletes of a command

SYNOPSIS

#include <tcl.h>

ClientData
Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)

int
Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)

void
Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)

ARGUMENTS

	Tcl_Interp *interp (in)		Interpreter containing the command.
	const char *cmdName (in)		Name of command.
	int flags (in)		OR’ed collection of the values TCL_TRACE_RENAME and TCL_TRACE_DELETE.
	Tcl_CommandTraceProc *proc (in)		Procedure to call when specified operations occur to cmdName.
	ClientData clientData (in)		Arbitrary argument to pass to proc.
	ClientData prevClientData (in)		If non-NULL, gives last value returned by Tcl_CommandTraceInfo, so this call will return information about next trace. If NULL, this call will return information about first trace.

______________

DESCRIPTION

Tcl_TraceCommand allows a C procedure to monitor operations performed on a Tcl command, so that the C procedure is invoked whenever the command is renamed or deleted. If the trace is created successfully then Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName specifies a non-existent command) then TCL_ERROR is returned and an error message is left in the interpreter’s result.

The flags argument to Tcl_TraceCommand indicates when the trace procedure is to be invoked. It consists of an OR’ed combination of any of the following values:
TCL_TRACE_RENAME

Invoke proc whenever the command is renamed.

TCL_TRACE_DELETE

Invoke proc when the command is deleted.

Whenever one of the specified operations occurs to the command, proc will be invoked. It should have arguments and result that match the type Tcl_CommandTraceProc:

typedef void Tcl_CommandTraceProc(
ClientData clientData,
Tcl_Interp *interp,
const char *oldName,
const char *newName,
int flags);

The clientData and interp parameters will have the same values as those passed to Tcl_TraceCommand when the trace was created. ClientData typically points to an application-specific data structure that describes what to do when proc is invoked. OldName gives the name of the command being renamed, and newName gives the name that the command is being renamed to (or an empty string or NULL when the command is being deleted.) Flags is an OR’ed combination of bits potentially providing several pieces of information. One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE will be set in flags to indicate which operation is being performed on the command. The bit TCL_TRACE_DESTROYED will be set in flags if the trace is about to be destroyed; this information may be useful to proc so that it can clean up its own internal data structures (see the section TCL_TRACE_DESTROYED below for more details). Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire interpreter is being destroyed. When this bit is set, proc must be especially careful in the things it does (see the section TCL_INTERP_DESTROYED below).

Tcl_UntraceCommand may be used to remove a trace. If the command specified by interp, cmdName, and flags has a trace set with flags, proc, and clientData, then the corresponding trace is removed. If no such trace exists, then the call to Tcl_UntraceCommand has no effect. The same bits are valid for flags as for calls to Tcl_TraceCommand.

Tcl_CommandTraceInfo may be used to retrieve information about traces set on a given command. The return value from Tcl_CommandTraceInfo is the clientData associated with a particular trace. The trace must be on the command specified by the interp, cmdName, and flags arguments (note that currently the flags are ignored; flags should be set to 0 for future compatibility) and its trace procedure must the same as the proc argument. If the prevClientData argument is NULL then the return value corresponds to the first (most recently created) matching trace, or NULL if there are no matching traces. If the prevClientData argument is not NULL, then it should be the return value from a previous call to Tcl_CommandTraceInfo. In this case, the new return value will correspond to the next matching trace after the one whose clientData matches prevClientData, or NULL if no trace matches prevClientData or if there are no more matching traces after it. This mechanism makes it possible to step through all of the traces for a given command that have the same proc.

CALLING COMMANDS DURING TRACES

During rename traces, the command being renamed is visible with both names simultaneously, and the command still exists during delete traces (if TCL_INTERP_DESTROYED is not set). However, there is no mechanism for signaling that an error occurred in a trace procedure, so great care should be taken that errors do not get silently lost.

MULTIPLE TRACES

It is possible for multiple traces to exist on the same command. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. Attempts to delete the command during a delete trace will fail silently, since the command is already scheduled for deletion anyway. If the command being renamed is renamed by one of its rename traces, that renaming takes precedence over the one that triggered the trace and the collection of traces will not be reexecuted; if several traces rename the command, the last renaming takes precedence.

TCL_TRACE_DESTROYED FLAG

In a delete callback to proc, the TCL_TRACE_DESTROYED bit is set in flags.

TCL_INTERP_DESTROYED

When an interpreter is destroyed, unset traces are called for all of its commands. The TCL_INTERP_DESTROYED bit will be set in the flags argument passed to the trace procedures. Trace procedures must be extremely careful in what they do if the TCL_INTERP_DESTROYED bit is set. It is not safe for the procedures to invoke any Tcl procedures on the interpreter, since its state is partially deleted. All that trace procedures should do under these circumstances is to clean up and free their own internal data structures.

BUGS

Tcl does not do any error checking to prevent trace procedures from misusing the interpreter during traces with TCL_INTERP_DESTROYED set.

KEYWORDS

clientData, trace, command

Opportunity

Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.

Education

Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.