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 you enter a variable, the default is the variable’s byte length.

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

–g

Stops all processes in the process’s control group when the watchpoint triggers.

–p

Stops the process that hit this watchpoint.

–t

Stops the thread that hit this watchpoint.

–l lang

Specifies the language in which you are 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 you specify only an address, 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. If you do not use this option, TotalView uses the variable’s datatype. If you specify an address and you also use an expression, you must use this option.

Description: 

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

Watchpoints are not available on Macintosh computers running OS X, IBM PowerPC computers running Linux Power, IBM Blue Gene/L, and Hewlett Packard (HP) computers running or HP-UX.

The value set in the STOP_ALL variable indicates which processes and threads stop executing.

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.

To obtain a variable’s address 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 in a register.

See “Using Watchpoints” in the TotalView User Guide for additional information on watchpoints.

If you do not use the –length option, 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 watch a certain number of bytes, starting at the named location.

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 need to embed code written in Fortran, C, or assembler within Tcl commands. In addition, your expressions often include TotalView built-in functions.

Command alias: 

 

Alias	Definition	Description
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 ptr is a global variable that is a pointer.

dwatch *ptr

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

dwatch {*ptr}

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

dfocus {p2 p3} wa *ptr

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

dfocus {p2 p3 p4} dwatch –p *ptr

Watches the address pointed to by ptr in processes 2, 3, and 4. The –p option indicates that TotalView only stops the process triggering the watchpoint.

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

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

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