dwatch

Defines a watchpoint

Format:

Defines a watchpoint for a variable

dwatch variable [ -length byte-count ] [ -g | -p | -t ]
        [ [ -l lang ] -e expr ] [ -t type ]

Defines a watchpoint for an address

dwatch -address addr -length byte-count [ -g | -p | -t ]
        [ [-l lang ] -e expr ] [ -t type ]

Arguments:

variable

A symbol name corresponding to a scalar or aggregate identifier, an element of an aggregate, or a dereferenced pointer.

-address addr

An absolute address in the file.

-length byte-count

The number of bytes to watch. If a variable is named, the default is the variable's byte length.

If you are watching a variable, you only need to specify the amount of storage to watch if you want to override the default value.

-g

Tells TotalView to stop all processes in the process's control group when the watchpoint is hit.

-p

Tells TotalView to stop the process that hit this watchpoint.

-t

Tells TotalView to stop the thread that hit this watchpoint.

-l lang

Specifies the language used when writing an expression. The values you can use for lang are c, c++, f7, f9, and asm, for C, C++, FORTRAN 77, Fortran-9x, and assembler, respectively. If you do not use a language code, TotalView picks one based on the variable's type. If only an address is used, TotalView uses the C language.

Not all languages are supported on all systems.

-e expr

When the watchpoint is triggered, evaluates expr in the context of the thread that hit the watchpoint. In most cases, you need to enclose the expression in braces ({ }).

-t type

The data type of $oldval/$newval in the expression.

Description:

A dwatch command defines a watchpoint on a memory location where the specified variables are stored. The watchpoint triggers whenever the value of the variables changes. The CLI returns the ID of the newly created watchpoint.

Note:   Watchpoints are not available on Alpha Linux and HP.

The default action is controlled by the STOP_ALL variable.

The watched variable can be a scalar, array, record, or structure object, or a reference to a particular element in an array, record, or structure. It can also be a dereferenced pointer variable.

The CLI lets you obtain a variable's address in the following two ways if your application demands that you specify a watchpoint with an address instead of a variable name:

• dprint &variable
   
• dwhat variable

The dprint command displays an error message if the variable is within a register.

Note:   Chapter 8 of the TotalView Users Guide contains additional information on watchpoints.

If you do not use the -length modifier, the CLI uses the length attribute from the program's symbol table. This means that the watchpoint applies to the data object named; that is, specifying the name of an array lets you watch all elements of the array. Alternatively, you can specify that a certain number of bytes be watched, starting at the named location.

Note:   In all cases, the CLI watches addresses. If you specify a variable as the target of a watchpoint, the CLI resolves the variable to an absolute address. If you are watching a local stack variable, the position being watched is just where the variable happened to be when space for the variable was allocated.

The focus establishes the processes (not individual threads) for which the watchpoint is in effect.

The CLI prints a message showing the action point identifier, the location being watched, the current execution location of the triggering thread, and the identifier of the triggering threads.

One possibly confusing aspect of using expressions is that their syntax differs from that of Tcl. This is because you will need to embed code written in Fortran, C, or assembler within Tcl commands. In addition, your expressions will often include TotalView intrinsic functions.

Command alias:

You may find the following alias useful:

Alias	Definition	Meaning
wa	{dwatch}	Defines a watchpoint.

Examples:

For these examples, assume that the current process set at the time of the dwatch command consists only of process 2, and that p is a global variable that is a pointer.

dwatch *p

Watches the address stored in pointer p at the time the watchpoint is defined, for changes made by process 2. Only process 2 is stopped. Note that the watchpoint location does not change when the value of p changes.

dwatch {*p}

Performs the same action as the previous example. Because the argument to dwatch contains a space, Tcl requires that you place the argument within braces.

dfocus {p2 p3} wa *p

Watches the address pointed to by p in processes 2 and 3. Because this example does not contain either a -p or -g option, the value of the STOP_ALL state variable lets the CLI know if it should stop processes or groups.

dfocus {p2 p3 p4} dwatch -p *p

Watches the address pointed to by p in processes 2, 3, and 4. The -p option indicates that only the process triggering the watchpoint is stopped.

wa * aString -length 30 -e {goto $447}

Watches 30 bytes of data beginning at the location pointed to by aString. If any of these bytes change, execution control transfers to line 447.

wa my_vbl -type long -e { if ($newval == 0x11ffff38) $stop; }

Watches the my_vbl variable and triggers when 0x11ffff38 is stored into it.

wa my_vbl -e { if (my_vbl == 0x11ffff38) $stop; }

Performs the same function as the previous example. Note that this tests the variable directly rather than by using $newval.