AUG 1 Introduction
This guide is intended to be read by technical staff who have a desire to understand and use Aprobe. Users of Aprobe should be able to write programs in Ada, C++, C, or Java and run them at the command line.
The motivation and applications for Aprobe are given in separate documents available from OC Systems.
Using this Book
For information on installation and system requirements, see Installation Notes shipped with your software, or as described in the README file on the CD.
First time users should read Chapter 2, "Aprobe Basics", then do the on-line examples under
$APROBE/examples/evaluate]. (Ada users should read
$APROBE/ada_examples/] in place of
$APROBE/examples throughout this manual.)
After you've completed these examples, you should understand the basic steps of compiling, running and formatting probes for native (C, C++, or Ada) programs.
If you intend to use Aprobe primarily for native programs, then proceed to Chapter 3, "Writing APC Probes" and look over the rest of this book to get a more complete idea of what Aprobe can do. After that, simply use it as a reference when developing probes.
If you intend to use Aprobe primarily for Java programs, then work through the examples in Chapter 5, "Writing Java Probes", try some on your own application, and contact OC Systems if you have questions.
Aprobe is a sophisticated software tool that supports patching of executables and their supporting libraries. With Aprobe, you can write additions to your executable program and add them in a straightforward manner directly into the executable program just as it starts execution. These additions are called probes.
For compiled applications (C, C++, and Ada), probes are written using the C programming language. They are portions of C code which can be added into the executable under the control of Aprobe without having to recompile any of the original source code. The full ANSI C language is supported, so probes have the full power of both C and the C libraries at their disposal.
For Java applications, probes are also written in Java, as extensions of classes in the package com.ocsystems.aprobe. Because Java probes execute at a "higher" level, and are "straight Java" that are described in their entirety in Chapter 5, "Writing Java Probes".
In addition to being able to add compiled C code into the executable, Aprobe also provides many useful utility routines which allow the probes to do such things as automatically log and format data in a non-invasive manner and to obtain stack tracebacks. Aprobe also provides a preprocessor that makes it easy to reference all of the data and functions within the executable program being patched.
Aprobe allows you to add code (probes) to the executable:
- without requiring access to the source code,
- without relinking the application, and
- without modifying the executable program file.
Aprobe also works on shared libraries and on third party software for which you may not have source code.
Aprobe comes with some probes which you can use immediately (see Predefined Probes. However, the ability to write your own probes in C will prove to be even more valuable than these predefined probes.
It is especially important for users who intend to write probes to take the time to work through the on-line exercises as described in
$APROBE/examples/evaluate/README]. These illustrate many of the key features of Aprobe, including:
- Reading and changing program data.
- Logging data for post-run-time formatting.
- Automatic generation of probes using the debug information in your program.
- Predefined probes for tracing program flow.
- Analysis of multi-threaded programs.
- Probing C constructors and destructors.
- Handling, reporting on and raising exceptions.
- Probing the execution of any and all source lines in your program.
As you can see there are many topics to cover, and these graduated examples help to make the best use of your time. (It should take about 45 minutes to go though them.)