1 10/16/84  watch
 2 
 3 Syntax as a command:  watch {locations} {-control_args}
 4 
 5 
 6 Function: manipulates the table of virtual memory locations under
 7 scrutiny by the trace facility, which can monitor up to 1024 locations
 8 for content changes.  The word at each location is checked whenever any
 9 entrypoint in the trace table is called or returns.  When a change is
10 detected, execution is stopped and the old and new contents are
11 displayed.  (See trace.info for more information about the trace
12 facility.)
13 
14 
15 Arguments:
16 locations
17    represent virtual memory locations in a form acceptable to the
18    cv_ptr_ subroutine.  You must separate multiple locations by spaces
19    (see "Notes on the syntax of locations").
20 
21 
22 Control arguments: tell what to do with the specified locations.  If
23    you select neither -add nor -remove, -add is assumed.
24 -add
25    adds the specified locations to the watch table.  When a location is
26    added to the watch table, its content is saved there for later
27    comparison; when a specified location is already in the watch table,
28    its saved content is brought up to date.
29 -changed
30    specifies all locations with content changes.
31 -remove, -rm
32    removes the specified locations from the watch table.
33 -status, -st
34    displays the specified locations and their contents from the watch
35    table.
36 
37 
38 Notes: To prevent trace messages while watching, use the "-trace off"
39 argument to the trace command when adding entrypoints to the trace
40 table.
41 
42 The order of entrypoints in the watch table is determined by their
43 segment numbers and word offsets.  The table is ordered first by
44 ascending segment number and then by ascending word offset.
45 
46 
47 All locations in the watch table are checked whenever any entrypoint in
48 the trace table is called or returns unless the entrypoint is off or
49 all tracing is disabled.  If any locations have changed, the trace
50 facility prints a stop message, displays the old and new contents, and
51 calls the -stop_proc.  When the -stop_proc returns, the new contents
52 are recorded in the watch table and execution resumes.  Unless you
53 change it, the -stop_proc is the command processor, so you can invoke a
54 debugger to get further information.  To get a trace of the changing
55 contents without stopping, use the command "trace -stop_proc nothing".
56 
57 
58 Notes on the syntax of locations: Acceptable representations include
59 the following:
60    pathname|word_number
61    pathname                   (same as pathname|0)
62    pathname|entryname
63    pathname$entryname         (pathname must contain > or <)
64    reference_name$word_number
65    reference_name$            (same as reference_name$0)
66    reference_name$entryname
67    segment_number|word_number
68    segment_number              (same as segment_number|0)
69    segment_number|entryname
70    *                           (all locations in the watch table)
71 
72 
73 Pathnames can be relative or absolute.  All numbers are octal.  Bit
74 offsets are ignored.  If you use *, you can't specify any other
75 locations.