You can either load your program with prex or attach prex to an already running process. The following two sections explain both procedures.
When you start your program with prex, it preloads the libtnfprobe library into the target program, so the program does not have to be explicitly linked with libtnfprobe.
prex starts your program running, then stops the program before any user code is executed. Execution is stopped even before the .init() sections are executed, so you can place probe points in the .init() sections to trace initialization code.
In the simplest case, with an executable named a.out that takes no arguments and that contains probe points, the following command can be used:
$ prex a.out
(prex uses the $PATH environment variable to find the executable.)
prex [-o outfilename] [-s kbytes_size] [-l sharedobjs] cmd [cmdargs...]
The -o, -s, and -l options are explained in "Command Line Options for prex ".
If the program named a.out is running and the ps(1) command shows that a.out has a process ID (PID) of 2374, then the following command attaches prex to a.out:
$ prex -p 2374
If you are attaching prex to your already-running program, libtnfprobe must be linked to your program first. If you have not linked with libtnfprobe, prex exits with the error message that libtnfprobe is not linked to your program.
Linking with the library increases the size of your program by about 33 kilobytes (25 kilobytes shareable) and by the size of the trace file that is allocated (controllable through a command line option to prex). If you are never going to attach to a running program using prex, don't link with libtnfprobe.
However, if a program is not easy to restart and is a long-running program that you might someday want to gather information about, then do link with libtnfprobe. A window server is a good example of this--not the sort of program you want to stop and restart often--so you probably want to link with libtnfprobe before you start it running.
You can link with libtnfprobe in one of two ways:
If you are compiling your program, include -ltnfprobe on the cc line (if using -lthread, always put -ltnfprobe before -lthread).
$ cc -ltnfprobe -lthread -o cookie cookie.c
If your program is already compiled or you don't want to build your program with an explicit dependency on libtnfprobe, use the following command:
$ LD_PRELOAD=libtnfprobe.so.1 executable_object_name
See the Linker and Libraries Guide for an explanation of LD_PRELOAD.
After you use prex to load the program, or attach prex to a running program, use Control-c to stop your program and pass control to prex.
When you see the prex prompt, prex is running and your program is halted.
prex>
Enter prex commands to control the probe points. For example, you can list probe points, turn on tracing, and debug your program.
To continue running your program, enter the continue command.
prex> continue
To stop your program and return to prex, press Control-c.
$ ^c prex>
Table 1-1 lists the standard prex command line options.
Option |
Definition |
---|---|
-otrace_file |
The trace file contains information gathered by the prex command. The trace_file location is assumed to be relative to the directory from which you started prex. When no trace_file is specified, the default location is $TMPDIR/trace-pid where pid is the process ID of your program. If $TMPDIR is not set, /tmp is used.
When a program is traced, the trace file that is set at the start (the default or the -o name) is used for the life of the program. |
-l libraries |
The libraries argument contains the names of libraries to preload for your programs. It follows the LD_PRELOAD (see ld(1)) rules on how libraries should be specified and where they are found. Enclose the space-separated list of library names in double quotes.
When prex loads the program, the default library is libtnfprobe.so.1. You cannot use this option when attaching prex to an already-running process. |
-s size |
size is the size of the trace file in kilobytes (210 bytes). The default size of a trace file is four megabytes. The minimum size that can be specified is 128 kilobytes. |