watcher(1) CLIX watcher(1)
NAME
watcher - Runs CRM utility for monitoring process events
SYNOPSIS
/usr/ip32/crm/watcher [-V] [-U boot_image] events [display_options]
[output_option] input_option
FLAGS
-U boot_image Provides the file specification of the CLIX image which
was booted. This flag is required only if the boot image
has been moved since the system was booted. (The default
boot image used is set with the Operating System
Parameters item of the workstation Utility Pages; usually,
the image is the /unix file. However, if the user moves
the boot image to a different directory, the -U flag must
be used to tell the CRM utilities where to find the boot
image.)
-V (Verbose.) Displays a complete list of keywords which may
be used with events, display_options, and input_options.
One or more of the following events must be specified.
-f fault_types
Enables monitoring of process page faults. The default is ALL,
which provides monitoring of all process fault types. For a
complete listing of fault types, use the -v (verbose) flag.
-s system_call_types
Enables monitoring of process system calls. The default is ALL,
which enables monitoring of all of the process' system calls.
Specifying IO enables the monitoring of only those system calls
associated with I/O. For a complete listing of system call types,
use the -v (verbose) flag.
-t trace_arguments
Enables single-step program tracing. This flag causes a trace trap
in the target process for each instruction executed. Each
instruction is displayed prior to execution.
-c call_tracing_arguments
Enables subroutine call tracing. This flag causes a trace trap in
the target process for each instruction executed. The entry into
and return from subroutines is displayed.
The following display_options, which enhance the output, are available.
These flags are not required.
2/94 - Intergraph Corporation 1
watcher(1) CLIX watcher(1)
-a Enables address translation. If the program was compiled to include
debugger symbols (such as those to be used by dbg), watcher can read
these symbols and provide more logical values for the program counter
(PC).
-b Enables the ``by-file'' I/O system call tracking. This flag causes a
summary (at the exit of watcher) of I/O system call statistics
displayed on a per-file basis. This flag requires the -s flag, with
the ``open'' system call type, in addition to any other system call
types of interest.
-d Enables instruction decoding. When the -t flag is used, the binary
instruction stream displays as the target process executes. With
this flag, the binary instruction stream is back-translated to
assembly language for display.
-m Enables module history tracking. When used with the -t flag, this
flag causes a summary (at the exit of watcher) of the number of
instructions executed per subroutine. When used with the -c flag,
this flag causes a summary (at the exit of watcher) of the number of
calls made to a subroutine, broken down into number of calls per
caller.
The following output_option is available. This flag is not required or
recommended.
-o output_file Specifies an output_file in which to store raw data. A
hyphen (-) for output_file directs output to stdout.
The following input_options are available. One and only one flag is
required to specify the target process.
-i input_file
Reads the data from the specified input_file. The input_file must
have been created as an output_file using the -o flag. A hyphen
(-) for input_file reads input from stdin.
-p pid Specifies the process ID (PID) number of the process to monitor.
The user can enter ps -e at the system prompt to determine the PID
of a running process.
-n process_name
Specifies the name of the process to monitor. The user can enter
ps -e at the system prompt to determine the name of a running
process. If a process with the specified name is not found,
watcher keeps looping through the system's process table until a
process is found.
-e command [arg ... ]
Allows the user to run, provide arguments for, and monitor a
program.
2 Intergraph Corporation - 2/94
watcher(1) CLIX watcher(1)
DESCRIPTION
The watcher command uses the /proc file system to monitor specified events
in a target process. These events include page faults, system calls, and
trace traps. The watcher command does not require that the target program
include debugger symbols.
When an event specified with watcher occurs, the target process is ``put
to sleep'' and the watcher process ``wakes up.'' The watcher command then
gathers information about the event from the target process. By default,
this information is formatted and displayed to the user.
Each command line flag specifying an event type to be watched accepts
keywords to define which events to watch. If no keywords are specified,
the keyword ALL is assumed. If conflicting keywords are specified, the
last keyword is used.
The watcher displays optional summaries of the various event types before
exiting. To disable the summary for an event type, use the NOSUMMARY
keyword. To see only the summary for an event type, use the SUMMARY
keyword.
For a complete online listing of available keywords use -V, the verbose
usage flag.
The watcher command exits if the target process exits. To stop watching
the target process prior to that process' exit, send an interrupt signal
(the <Ctrl-C> sequence) to watcher. If watcher ran the target process
with the -e input_option and receives an interrupt signal, it sends a kill
signal to the target process prior to its exit. Any summaries are
displayed before watcher exits.
EXAMPLES
The following examples use a program called user_program as the target of
watcher. The program is as follows:
main() { printf("Hello world\n"); }
This program was built with the following command:
cc -O user_program.c -o user_program
1. To run a program and watch the system calls made by that process,
enter the following command:
watcher -s -e user_program
This command produces the following output:
2/94 - Intergraph Corporation 3
watcher(1) CLIX watcher(1)
0x2af2: IOCTL(0x1,0x5401,0xbffffc44) = 0
Hello world
0x3292: WRITE(0x1,0x4015c0,0xc) = 12
0x29f6: CLOSE(0) = 0
0x29f6: CLOSE(0x1) = 0
0x29f6: CLOSE(0x2) = 0
0x3366: EXIT(0xc)
SYSTEM CALL SUMMARY
EXIT: 1 WRITE: 1 CLOSE: 3 IOCTL: 1
Total system calls: 6
Notice that each system call is preceded by the PC of the process
where the system call was made. The arguments of the system call are
listed after the name of the system call. Finally, the return status
of the system call is listed. If the user looks up the arguments to
the write() system call, the user finds that the first argument is the
file descriptor (0x1 in this case, or stdout), the second argument is
the buffer address (0x4015c0), and the third argument is the number of
bytes to write (0xc). The write() system call returns the number of
bytes actually written (12 in this example).
2. To run a program and watch the page faults by that process, enter the
following command:
watcher -f -e user_program
This command produces the following output.
0xe8: FILE-FAULT ADDRESS:0xe8
0x118: CACHE-FAULT ADDRESS:0x400370
0x118: CW-FAULT ADDRESS:0x400370
0x1e18: CACHE-FAULT ADDRESS:0x1e18
0x2a08: CACHE-FAULT ADDRESS:0x2a08
0x2aa8: CACHE-FAULT ADDRESS:0x401148
0x32c8: CACHE-FAULT ADDRESS:0x32c8
0x32c8: CW-FAULT ADDRESS:0x401148
Hello world
SYSTEM PAGEFAULT SUMMARY
Sequential faults:
CACHE: 4 FILE: 0 CW: 1
Total sequential faults: 5
Total faults:
CACHE: 5 FILE: 1 CW: 2
Total system faults: 8
4 Intergraph Corporation - 2/94
watcher(1) CLIX watcher(1)
3. To single-step a program from the beginning enter this command:
watcher -t -e user_program
This command produces a long (6100 line) output, part of which looks
like this:
0xea: 0x004763af00000000
0xec: 0x8bbf004763af0000
0xee: 0xfff88bbf004763af
0xf2: 0x60828478fff88bbf
0xf6: 0x4993a60260828478
0xf8: 0x000a4993a6026082
0xfa: 0x8248000a4993a602
0xfc: 0x49908248000a4993
0x100: 0x8248fff649908248
0x102: 0x60728248fff64990
0xf8: 0x000a4993a6026082
0xfa: 0x8248000a4993a602
0xfc: 0x49908248000a4993
A more useful representation of the same information may be acquired
by the addition of two display_options:
watcher -t -d -a -e user_program
This command produces the following output.
start() + 0x2: noop
start() + 0x4: noop
start() + 0x6: loada 0x4(sp),r7 [istart+0xffffff24]
start() + 0xa: andi 0xfff8,sp [_etext+0xcc88]
start() + 0xe: movw r7,r8
start() + 0x10: loadw (r8),r2
start() + 0x12: cmpq 0x0,r2
start() + 0x14: bceq 0xa(pc) [start+0x1e]
start() + 0x18: addq 0x4,r8
start() + 0x1a: b 0xfffffff6(pc) [start+0x10]
start() + 0x10: loadw (r8),r2
start() + 0x12: cmpq 0x0,r2
start() + 0x14: bceq 0xa(pc) [start+0x1e]
4. To watch ls do I/O related system calls, find out whether the I/O came
from or went to disk buffer cache, and get a summary of the I/O on a
per-file basis, enter the following command:
watcher -s IO CACHE -b -e ls -l /usr/tmp
This is the resulting output.
2/94 - Intergraph Corporation 5
watcher(1) CLIX watcher(1)
0x11712: OPEN("/usr/tmp",0) = 3
0xebb6: FSTAT(0x3) = 0
0xc082: GETDENTS(0x3,0x4101a0,0x418) = 48 Cache hit
0xc082: GETDENTS(0x3,0x4101a0,0x418) = 0 Cache hit
0x1101e: CLOSE(0x3) = 0
0x1111a: IOCTL(0x1,0x5401,0xbffff9dc) = 0
total 2
0x118b2: WRITE(0x1,0x407260,0x8) = 8 Cache hit
0x11712: OPEN("/etc/domainname",0) = 3
0x1111a: IOCTL(0x3,0x5401,0xbffff6b4) = -1
0x1172a: READ(0x3,0x410188,0x400) = 1 Cache miss
0x1101e: CLOSE(0x3) = 0
0x11712: OPEN("/etc/passwd",0) = 3
0x1111a: IOCTL(0x3,0x5401,0xbffff6dc) = -1
0x1172a: READ(0x3,0x410188,0x400) = 1024 Cache miss
0x1101e: CLOSE(0x3) = 0
0x11712: OPEN("/etc/domainname",0) = 3
0x1111a: IOCTL(0x3,0x5401,0xbffff6b4) = -1
0x1172a: READ(0x3,0x410188,0x400) = 1 Cache miss
0x1101e: CLOSE(0x3) = 0
0x11712: OPEN("/etc/group",0) = 3
0x1111a: IOCTL(0x3,0x5401,0xbffff6dc) = -1
0x1172a: READ(0x3,0x410188,0x400) = 229 Cache miss
0x1101e: CLOSE(0x3) = 0
-rw-rw-r-- 1 tstusr users 759 Sep 24 16:30 foo.dat
0x118b2: WRITE(0x1,0x407260,0x3e) = 62 Cache hit
0x1101e: CLOSE(0) = 0
0x1101e: CLOSE(0x1) = 0
0x1101e: CLOSE(0x2) = 0
SYSTEM CALL SUMMARY
READ: 4 WRITE: 2 OPEN: 5 CLOSE: 8
FSTAT: 1 IOCTL: 5 GETDENTS: 2
Total system calls: 27
FILE SUMMARY
File: <STDERR>
open=0, close=1
File: <STDOUT>
open=0, close=1
write=2, bytes=70, average/write=35.00, cache hits=2 (100.00%)
ioctl=1
File: <STDIN>
open=0, close=1
File: /etc/group
open=1, close=1
read=1, bytes=229, cache hits=0 (0.00%)
ioctl=1
6 Intergraph Corporation - 2/94
watcher(1) CLIX watcher(1)
File: /etc/domainname
open=2, close=2
read=2, bytes=2, average/read=1.00, cache hits=0 (0.00%)
ioctl=2
File: /etc/passwd
open=1, close=1
read=1, bytes=1024, cache hits=0 (0.00%)
ioctl=1
File: /usr/tmp
open=1, close=1
getdents=2, bytes=48, average/getdents=24.00, cache hits=2 (100.00%)
fstat=1
FILES
The watcher command requires read access to the following files:
/dev/kmem Allows watcher access to kernel virtual memory space.
/dev/mem Allows watcher access to kernel physical memory space.
/proc/????? The proc file system entry for the target process, where ?????
is the five-digit process ID.
/unix The default CLIX image. The watcher command looks up offsets
into the kernel using the symbols from the boot_image.
NOTES
Superuser privileges are required to run this monitor on processes other
than those owned by the user.
CAUTIONS
Sending raw data to a file can create a very large file, which may result
in unexplained ``disk full'' messages.
Single-stepping even a short program takes a very long time.
If the target process has graphics output, make sure that watcher's
display is to a nongraphics device. If watcher stops a process at a
graphics output event (like a system call) and then tries to display a
line of output to a graphics window, a deadlock will occur. In a
deadlock, no process that sends output to the graphics screen will run.
The screen is locked up. The only workaround is to kill watcher, which
does not always free the screen. In order to avoid this problem
altogether, watch a graphics program from an attached alphanumeric
terminal, or from a remote system.
EXIT VALUES
2/94 - Intergraph Corporation 7
watcher(1) CLIX watcher(1)
The exit values are not valid.
RELATED INFORMATION
Commands: acc(1), crm(1), ps(1), ls(1), dbg(1)
8 Intergraph Corporation - 2/94