Command Directory

monitor

m{onitor}

Format 1: monitor
EXPRESSION [LENGTH | CTYPE)] [in FUNCTION-NAME] [print] [where]

Format 2: monitor
EXPRESSION [LENGTH | (CTYPE)] [in (SECTION-NAME)] [print] [where]

Format 3: monitor
EXPRESSION [LENGTH | (CTYPE)] [library] [print] [where]

DESCRIPTION

The monitor command causes the debugger to test for changes in the value of the monitored object at every line-number hook. If the value changes, the program is interrupted.

The request itself is called a monitor. When the monitor command is used to request the debugger to check for changes in the value of an object, the debugger is said to be monitoring the object. A change in the value of the monitored object causes the monitor to be triggered.

EXPRESSION identifies the object (such as a variable) to be monitored.

The following options can be specified in any order:

LENGTH: is the number of bytes to be monitored. It does not need to be the same as the length of the object.
(CTYPE): is either a structure|union tag or a type defined with a typedef , or an arithmetic type. If neither LENGTH nor CTYPE is specified, the length used is the length corresponding to the type of the object.
in FUNCTION-NAME: specifies that the debugger monitor the object only when the named function is executing. You cannot use this argument with the in (SECTION-NAME) option or with library.
in (SECTION-NAME): specifies that the debugger monitor the object only when functions in the named section are executing. You cannot use this argument with the in FUNCTION-NAME option or with library.
library: specifies that the debugger also monitor the object during calls to C library functions. If you do not use this keyword, the object is not monitored during these calls. Use library only if you suspect that an object is being modified inadvertently by a library function. You cannot use this keyword with the in (FUNCTION-NAME) or in (SECTION-NAME) options.
print: causes the debugger to issue a print command when the monitor is triggered. If print is used, the debugger prints the new value of the object. If the object is no more than 256 bytes in length, the debugger also prints the old value. The values are formatted appropriately for the type of the object. If the object is an aggregate and less than 256 bytes in length, only those fields that have changed are displayed.
where: causes the debugger to issue a where command when the monitor is triggered. The traceback is produced only once, even if more than one monitor is triggered at the same line-number hook.

Monitor requests are maintained in the same way as breakpoints. Each monitor is associated with a number that can be displayed by the query command. Monitor requests can be disabled, enabled, or dropped like breakpoints.

If the object is identified by the form arr[index_expression] , where the index expression is not constant, then the current value of the index expression is used to determine the location of the object to be monitored. This means that the monitored location does not change if the value of the index expression changes.

The debugger distinguishes monitor requests by the class and type of the object. In this context, an object can have one of three classes: auto, static, or address.

A simple identifier has class auto if it is an automatic variable or a parameter. The identifier has class static if it is a static or extern variable. Expressions used to represent portions of an array or structure (for example, arr[index_expression] , *(arr + index_expression) , where arr is an array, or str.mem1 , where str is a structure) have the same class as the array or structure. Expressions that involve some form of indirection (for example, *(p+5), p-->a , where p is a pointer or *0p address) have class address.

The class affects the way the query command displays the monitor request. With one exception, query displays auto and static monitor requests symbolically (that is, the identifier or expression used in the monitor command) and class address monitor requests by hexadecimal address. The exception is monitor requests for an element of an array, when the element is distinguished by an expression. In this case, query displays the monitor request using the value of the expression at the time the monitor command is issued. This emphasizes that a fixed element of the array is being monitored.

The class also affects the scope of the monitor. If the class is auto, the monitor is enabled only while the function is executing. If the function is recursive, then a separate monitor is used for the current and any future occurrences of the function. Thus, a single monitor request can monitor multiple occurrences of the expression. However, only one request number is associated with the request. Therefore, it is not possible to drop, disable, or enable individual occurrences. Similarly, it is not possible to display or modify any occurrence of the object except the current one.

If a static object is in a subsidiary load module, and the load module is unloaded via the unloadm function, the debugger automatically drops the monitor and issues a message to that effect. Similarly, if a monitored object of class address is in storage that was allocated via the malloc function, and the storage is freed by free, the debugger drops the monitor and issues a message.

The debugger distinguishes monitor requests by the type of the object. Types of Objects for the monitor Command shows how the debugger treats monitor requests for objects by type.

Types of Objects for the monitor Command
Type
Notes

1 arithmetic The object is monitored. LENGTH is not usually specified because the length can be determined by the C type. If LENGTH is used, the debugger monitors the number of bytes specified starting at &EXPRESSION.

2 pointer This is the same as type 1, arithmetic.

3 structure or union This is the same as type 1, arithmetic.

4 array This is the same as type 5, address.

5 address An address cannot be monitored. Storage at an address, however, can be monitored. For example, monitor *0p12345678 20 monitors 20 bytes of storage, starting at the address 0p12345678.

6 enum constant An enum constant cannot be monitored.

7 bitfield All bytes that contain the bitfield are monitored. However, the debugger does not interrupt the program unless the bits in the bitfield are changed.

8 function A function cannot be monitored.

***Types of Objects for the monitor Command***
Type		Notes
1	arithmetic	The object is monitored. LENGTH is not usually specified because the length can be determined by the C type. If LENGTH is used, the debugger monitors the number of bytes specified starting at &EXPRESSION.
2	pointer	This is the same as type 1, arithmetic.
3	structure or union	This is the same as type 1, arithmetic.
4	array	This is the same as type 5, address.
5	address	An address cannot be monitored. Storage at an address, however, can be monitored. For example, *`monitor 0p12345678 20`** monitors 20 bytes of storage, starting at the address 0p12345678.
6	`enum` constant	An `enum` constant cannot be monitored.
7	bitfield	All bytes that contain the bitfield are monitored. However, the debugger does not interrupt the program unless the bits in the bitfield are changed.
8	function	A function cannot be monitored.

Identical requests: If a monitor request is made that is identical to an existing one, the identical request is not installed. This is true whether the request to be installed is within an on command or typed in at the command line.

If an identical request is issued and the original request is disabled, the identical request is discarded and the original request is automatically enabled without an indication.

EXAMPLES

The following examples illustrate the monitor command, given the following declarations:

   int loopcnt;
   struct ABC *p;
   int arr[10] ;
   char buf[100] ;

monitor loopcnt print: monitors the loopcnt variable. If the monitor is triggered, both the old and new values are printed.
monitor *p library: monitors the structure pointed to by p . The value of p when the monitor is installed is used to determine the address being monitored. The debugger checks for changes to the structure, even while library functions are executing.
monitor *p 20 in (sect1): monitors 20 bytes, starting at the location pointed to by p when any function in sect1 is executing. The value of p when the monitor is installed is used to determine the address being monitored.
monitor *arr where: monitors the first element of arr . If the monitor is triggered, the debugger produces a traceback.
monitor *buf 8 in func1: monitors the first 8 bytes of buf , only when func1 is executing.

SYSTEM DEPENDENCIES

none

COMMAND CAN BE ISSUED FROM

PROFILE no

configuration file no

Source window prefix none

SCOPE

The monitor command uses command scope to resolve references to all identifiers.

RETURN CODES SET

	Unsuccessful: 1
	Successful: 0

Format 1:	`monitor`	EXPRESSION [LENGTH \| CTYPE)] [in FUNCTION-NAME] [`print`] [`where`]
Format 2:	`monitor`	EXPRESSION [LENGTH \| (CTYPE)] [in (SECTION-NAME)] [`print`] [`where`]
Format 3:	`monitor`	EXPRESSION [LENGTH \| (CTYPE)] [`library`] [`print`] [`where`]