AUG Tools Reference

From OC Systems Wiki!
Jump to: navigation, search

Contents

Tools Reference


Overview

This Appendix is a reference for all the command-line tools provided with Aprobe. The standard "man page" format is generally followed, but the on-line version of this information must be viewed with an HTML browser and is not accessible with the man command.

The commands apc, apcgen, apinfo, apjava, apmkadi, aprobe, apformat, apsymbols, atcmerge, apbc, and abrmerge are described in this Appendix. The first section describes the Environment Variables referenced by these tools.


Environment Variables

The following environment variables are referenced by the tools described in this Appendix.

APC_LD_COMMAND

(Solaris only) gives the full path of the system linker that is to be used by the apc compiler to link UAL files. Note that the SUN ld command (or a completely compatible linker) must be used. By default it is assumed to be at /usr/ccs/bin/ld.

APC_LD_COMMAND is defined in the setup or setup.csh files created at installation. To change this, edit the setup script(s) or set APC_LD_COMMAND prior to re-running the RootCause installation script.

APROBE

APROBE is referenced by all tools to determine where Aprobe is installed. It must be defined and point to a valid Aprobe installation for any of the tools to work. Note that the value of $APROBE/bin must also be in your PATH environment variable.

APROBE_BIND_PROCESSOR

(AIX only) if aprobe is running on a multiprocessor machine under AIX version 4.3, aprobe calls the system function bindprocessor() to map aprobe and the target program process to processor 0. If the value of this environment variable is defined to a value of 1 or greater, this is interpreted as a processor number to be used instead of 0. If APROBE_BIND_PROCESSOR is set to -1, bindprocessor() is not called, which will allow an AIX bug to manifest itself which may cause a core dump.

APROBE_CC_COMMAND

specifies name of the compiler profile (not the cc command itself) for the C compiler to be used by the apc compiler. The valid compiler profile names are those that appear after the PROFILENAME keyword in the $APROBE/lib/compiler_profiles file (see "compiler_profiles file"). The APROBE_CC_COMMAND environment variable is set by the $APROBE/setup script if necessary.

APROBE_COMPILER_PROFILES

specifies the full path to a compiler_profiles file to be used in place of the default one in $APROBE/lib/compiler_profiles.

APROBE_DISABLE_PATCHAREA

if defined and non-blank, this indicates that Aprobe should not look for patch area symbols on AIX.

APROBE_DISABLE_SACRIFICE

if defined and non-blank, this indicates that Aprobe should not try function sacrificing. This will greatly reduce the ability of Aprobe to probe functions on AIX.

APROBE_DO_NOT_SACRIFICE_FILE

specifies the full path to a file containing function names (in Aprobe syntax) one per line. The named functions will not be sacrificed on AIX. This can be used interchangeably with the -q do_not_sacrifice=file command line option.

APROBE_LIBPATH

If defined, this is a colon-separated list of directories (like PATH and LIBPATH) in which to search for UAL files. See "UAL SEARCH ORDER" for more information.

APROBE_POWERADA_LIBRARY

If defined, is interpreted as the path to a Powerada library list file which overrides any such definition embedded in modules provided to the apc compiler. Can be used in cases where the Ada library is not available at the path defined at compile time, or to establish an Ada library context in cases where multiple modules are provided to apc and none of those modules defines an appropriate library list.

APROBE_RING_SIZE

If defined, this defines the maximum number of files in the ring of APD files generated by Aprobe. This is superseded by the command-line values specified on the aprobe command. See "APD file" for more information.

APROBE_SEARCH_PATH

(Solaris only) If defined, this is a colon-separated list of directories (like PATH and LIBPATH) in which to search for an object file containing debug data if it is not found in the directory where it resided when the executable was linked. For example, if a program is linked from object files in directories /build/common, /build/console, and /build/gui, and the directory /build is mounted on a different machine as /tmp/build, you could do:
export APROBE_SEARCH_PATH=\
"/tmp/build/common:/tmp/build/console:/tmp/build/gui"

apc

Compiling Probes

NAME

apc - Preprocesses and compiles APC to generate a User Action Library (UAL).

SYNOPSIS

apc [-c] [-C] [-d][-g][-h] [-u] [-v]
  [-o UAL_file ][-x object_or_header_file ]
  [-e name] [-l dir]
  [-D name[=def]] [-I directory]
  [-cc_command name]
  [-compiler "compiler_options"]
  [-linker "linker_options"]
  input_files ...

DESCRIPTION

This command preprocesses the source code (APC) files of probes that are written in ANSI C and possibly interspersed with Aprobe preprocessor directives. Then it passes the preprocessed files to the target C compiler and linker, which compiles and optionally links them with other object code and places the resulting object code into a User Action Library (UAL file).

The apc command can also process assembler source files, object files and C files, because it invokes the target C compiler or linkage editor on these files.

The following are the allowed file suffixes for the input files and their meanings:

'.apc'
an APC source file
'.ual'
a UAL file generated by a previous apc command
'.c '
a C source file.
'.o '
an object file for the linker command.
'.s'
an assembler source file
'.so'
a shared object file
'.a '
an archive library.

When referencing a previously-built UAL from your APC, note that the referenced UAL is a shared object file (like a .so file), and so must:

  • have exported symbols using the apc -e option; and
  • be available when the new UAL is executed.

OPTIONS

'-c'
Compile only; do not create a UAL file.
'-C'
Retain the C code generated by preprocessing; the resulting file is APC_source_file_c.c; For example if an APC_source file is foo.apc, the corresponding C file is foo.apc_c.c.
'-cc_command' name
Specifies the name of the compiler profile (not the cc command itself) for the C compiler to be used by the apc compiler. The valid compiler profile names are those that appear after the PROFILENAME keyword in the file$APROBE/lib/compiler_profiles(see "compiler_profiles file").
'-compiler "compiler_options"'''
Specifies options to be passed directly to the target C compiler. The collection of options must be enclosed in a single string that is enclosed in quotation marks. For example, -compiler "-g -v". You may specify -compiler multiple times, each with its own option string.
'-D' name[=def]]
Define name to the C preprocessor as in #define directive. If def is not specified, 1 is assumed. This may be specified multiple times for different names.
'-d'
Force reading of all debug information from the file(s) specified by the -x argument(s) before parsing APC. This may be necessary in some cases of forward-references.
'-e' name
Export the function or global symbol name when linking the UAL, so it may be referenced from other UALs.
'-g'
generate debugging information in the output (.ual) file, and also save the intermediate C source file (as is done by -C).
'-h'
Print brief command-line help to standard output.
'-I' directory
(Uppercase i): Search in directory for include files that do not start with an absolute path. This option may be specified more than once.
'-l' directory
(Lowercase L): Evaluate -x args relative to directory. This is necessary if the application references statically-loaded modules using relative pathnames.
'-linker "linker_options"'''
Options to be passed directly to the target linker. The collection of options must be enclosed in a single string that is enclosed in quotation marks. For example, -linker "-lposix4 -lm". You may specify -linker multiple times, each with its own option string. Special case -linker xlC on AIX and -linker g++ on Linux forces link with C++ compiler rather than ld to allow C++ object files to be linked into the UAL.
'-o' UAL_file
Specify the name of the output User Action Library. The default file name is the name of the first part of the APC_source_file with an extension of ".ual" (e.g., for foo.apc, the default name is foo.ual).
'-u'
Allow unresolved symbols to remain in the UAL so that code that references application symbols may be bound in.
'-v'
Verbose; echo tool command-lines and display progress messages.
'-x' object_or_header_file
Specifies the file from which source-level debug information is to be read from which expressions in the input files may be resolved. This may be one of:
  • the executable file to be probed;
  • a shared library file defining the probed functions;
  • an unlinked object file defining probed functions.
  • a C header (.h) file defining prototypes for functions being probed.

Important: Source files for which source-level information is referenced must have been compiled with -g, and the executable may not be stripped.

PARAMETERS

input_files

A list of one or more file names separated by spaces. See the "DESCRIPTION" above for details on what files may be specified.

EXAMPLES

Preprocess and compile foo.apc, compile foosup.c, and link in gensup.o, to produce foo.ual, and reference foo.exe to resolve target expressions:

apc -x foo.exe foo.apc foosup.c gensup.o

Preprocess and compile maze.apc and link with /usr/lib/libX11.so

apc -g maze.apc -linker "-lX11"

apcgen

Generating APC

NAME

apcgen - reads the debug information in an executable and produces APC output to probe functions defined there.

SYNOPSIS

apcgen  [-adghmv] [ -p subprogram | -f source_file [ -l line ] ]
  [-n n_probes ] [ -L | -T ] [ -q option ][ -o outfile ]
  [ -F file ] {[-x ] object_or_header_file } object_or_header_files ...

DESCRIPTION

This command reads debug information from the specified object files and uses it to generate simple entry and exit probes for all or specified subprograms (functions). apcgen writes only to standard output. Each invocation produces probes for an entire module, a single subprogram in the module, all subprograms in a file, or the subprogram at a specified line in a specified file. For each function for which debug information is available (i.e., the file was compiled with -g), a probe similar to the following is generated:

probe "sourcetran.c":"TranslateRegisterExpression()" 
{
      on_entry {
         log("[Enter TranslateRegisterExpression()");
      }
      on_exit {
         log("]Leave TranslateRegisterExpression()");
       }
}

OPTIONS

All options must precede any parameters. That is, you must put the object_files at the end unless you precede them with -x. The options are:

'-a'
generate probes for all functions, including library, compiler-generated, and no-debug functions.
'-d'
only generate probes for those functions that have debug information. This excludes library, compiler-generated, and no-debug functions.
'-f' source_file

generate probes only for subprograms in sourcefile.
'-h'
show brief help output.
'-L'
list functions names, but don't generate probes for them.
'-l line'''
generate a probe for the subprogram containing line in source_file.
'-m'
generate mangled (linker) names for probed functions.
'-n' n_probes

put n_probes number of probes into each probe thread, and emit a clear delimiter between each probe thread so that output may be easily split into separate files. n_probes must be at least 1. By default all function probes go into a single probe thread.
'-o' outfile
direct output to the specified file instead of standard_output. However, if the outfile already exists and it is an object module, then a fatal error is given; otherwise the existing outfile is renamed to outfile.bak (overwriting any previous outfile.bak).
'-p' subprogram

generate a probe only for the specified subprogram.
'-q' option
specify what output is to be generated. The option values are:
params log parameters on entry,exit
entryparams log parameters on_entry
exitparams log parameters on_exit
deref dereference pointer parameters
lines generate an on_line action for each source line
cast cast parameters to their types

By default all are disabled. -q may be specified multiple times.

'-T'
list source type names only, don't generate APC.
'-v'
verbose output. When used with -L, includes file and line on which a function is declared, if available.
'-x' object_or_header_file

specify an executable or object file containing debug information, or a C header file, from which to read information.

PARAMETERS

object_or_header_files

Same as the -x option: a list of one or more names of object, executable, or C header files from which to read information.

EXAMPLES

Generate APC for the static function TranslateRegisterExpression in file sourcetran.c compiled into sourcetran.o, and put the output in sourcetran.apc:

apcgen -p TranslateRegisterExpression -f sourcetran.c \
-o sourcetran.apc sourcetran.o

Generate APC for all functions that have debugging information in the executable a.out , into a.apc, with verbose output printed to standard error:

apcgen -v a.out > a.apc

List the functions in the given object file that match 'append':

apcgen -vL string_ops.o | grep append

Generate probes for all functions in stdio.h:

apcgen -x stdio.h

apdemand

Demand Action From Probe

NAME

apdemand - Sends a demand for action to a demand-framework-enabled probe.

SYNOPSIS

apdemand  [-h]
apdemand action-string
apdemand menu


DESCRIPTION

This command sends a demand for action to an enabled probe via the demand.ual predefined probe. apdemand awakens the demand.ual by writing a command to the configuration file in the local directory.

apdemand shares a configuration file with demand.ual. The macro ap_OfferDemand() writes a comment menu of actions to the configuration file from the demand-enabled probe. The default configuration file is ./demand.cfg in the current working directory of the application run with Aprobe. You can override the default local directory and filename by setting the environment variable AP_DEMAND_CFG to the full path of a configuration file. Be sure that AP_DEMAND_CFG is set in both the shell where Aprobe runs the application and in the shell where you run the apdemand command.

OPTIONS

-h
Show help
action-string
Send demand request to invoke all registered demand callbacks matching this string.
menu
Invoke vi editor on config file. The offered actions have ap_OfferDemand description text. You can set/remove comments in the file, then :wq to save your changes and trigger processing, or :q! to exit with no change and no processing. There is editing help text in the config file

EXAMPLES

See the current contents of the configuration file:

apdemand

Request that any registered demand callbacks matching this string xxxx by called:

apdemand xxxx

Edit the configuration file:

apdemand menu

apformat

Formatting the Aprobe Data File

NAME

apformat - Formats the data that was logged in the APD files.

SYNOPSIS

apformat  [-h][-v] [-z]
  {-u ual_name [-p "parameters_for_ual"]}
  {-u dir_name }
  {-u adi_name }
  [-n [ all | none | apd_file_number ]]
  [-x executable][-m module]
   [[-d] apd_filename]

DESCRIPTION

This command formats the data that was logged into an Aprobe Data File (APD file) by probes containing log statements.

The pathname of the executable and of each UAL file specified to aprobe is stored in the APD file, so generally the name of the APD file is the only parameter that must be specified to apformat. ADI files must be specified explicitly.

By default, apformat loads any UAL that were specified to aprobe (i.e., at run time). The location of these UALs is the same as that used at run time unless the UAL is again specified on the command line, in which case the path specified on the command-line is used.

Note that the "default" UALs read from the APD file are initialized with an empty argument list, so if you need to specify any arguments to the UAL you must list the UAL on the command-line. To use only the UALs specified on the command line, include the -z option to the command line.

Note that the "APD file" is really at least two files: the persistent APD file (e.g., foo.apd) and the one or more files that make up the APD ring (e.g., foo-1.apd, foo-2.apd). See "APD file".

Either an APD file or an executable must be specified. If no APD file is specified but an executable name is given, the default APD file will be named executable.apd.

Output from apformat is to standard output, unless the user written format subprograms in the UALs direct it elsewhere.

OPTIONS

'-d' apd_filename
The name of the persistent APD file that contains the data to be formatted, e.g., foo.apd, and the base name for other data files generated. This defaults to the basename of executable.
'-h'
Display the help text.
'-m' module
get symbol info from module rather than the one of the same name recorded in the persistent APD file.
'-n all'
Format all APD files in a ring, as recorded in the persistent APD file. This is the default.
'-n none'
Avoid formatting any APD files, e.g., for static analysis of the executable.
'-n' apd_file_number
Designates a specific APD file in the ring to be formatted, e.g., "-n 0" indicates that only foo-0.apd should be formatted, and not any other APD files in the ring.
'-u ual_name ['-p "parameters_for_ual"]
Include the designated User Action Library (UAL file). The -u option may be repeated multiple times, once for each UAL, but each must have its own -p option if that UAL needs to be given any parameters. The -p option after each -uoption specifies the parameters for only that UAL. The parameters_for_ual must be enclosed within quotation marks if more than one parameter is specified. The apformat command fails if a specified UAL is not found as described in "UAL SEARCH ORDER".
'-u' adi_name
Include the designated Aprobe Debug Information file (ADI file). The -u option may be repeated multiple times if there are multiple ADI files. See "apmkadi".
'-u' dir_name
Include all files ending in .ual or .adi in the specified directory, if any. This is equivalent to specifying -u filename each UAL or API filename found in directory dir_name.
'-v'
Verbose.
'-x' executable
The file name of the user's executable program that was being probed when the APD file was produced. Either the full path to the executable program must be given or the executable file must exist in the current working directory.
'-z'
Do not load any UALs by default. With -z, only UALs specified on the command line (using the -u option) are loaded.

EXAMPLES

Format the contents of all APD files written in the most recent execution of foo using the formats described in whatever UAL was used when aprobe was run.

apformat foo

Format the file foo-2.apd using only foo2.ual:

apformat -z -u foo2.ual -n 2 foo.apd

Format the file foo*.apd, with parameters for each ual:

apformat -u foo1.ual -p "-v -g" -u foo2.ual -p "-h" foo.apd

apinfo

Listing Information about a Program

NAME

apinfo - an interface to the info.ualpredefined probe, which lists information about a loadable program. (See "Info Probe: info.ual".)

SYNOPSIS

apinfo options executable

DESCRIPTION

This command invokes aprobe on the executable file provided, applying the info.ual predefined probe with the options specified. If no options are specified, "-s" is used, which lists all symbols in the executable which can be probed. See also: apsymbols.

OPTIONS

The options are:

'-a'
print all information; same as -sa -da -m
'-d'
print data symbols from the application module
'-da'
print all data symbols from all modules
'-h'
show brief help output
'-l'
Print instrumentable lines in each function symbol shown
'-m'
print the list of modules initially loaded by the application
'-s'
print function names from the application module (default)
'-sa'
print all function names from all initially loaded modules
'-x'
indicate functions that are not instrumentable
'-xb'
exclude functions that are not instrumentable
'-xg'
print only functions that are not instrumentable

PARAMETERS

executable
the program to print information about. This must be runnable (fully linked, with all dependent libraries available).

EXAMPLES

List all information about a.out:

apinfo -a a.out

apjava

Apply probes to a Java application.

NAME

apjava - apply probes to an application normally invoked with the java command.

SYNOPSIS

apjava aprobe_options -java[=JAVA_HOME] java_parameters

DESCRIPTION

The apjava command applies Aprobe to a Java application. The aprobe_options are those described for the aprobe command, but generally includes at least a "-u name.xmj option" which names the XML-format deployment descriptor file, which in turn names the specific Java classes that contain the probes.

The "=JAVA_HOME" part must be specified unless the JAVA_HOME environment variable is defined. The value of JAVA_HOME should be the root of the Java Runtime environment, such that the java program is found in $JAVA_HOME/bin/java.

The java_parameters should be exactly what they would be if you weren't using apjava, for example the -classpath option.

EXAMPLES

Apply the contents of MyFirstProbe.xmj, found in the current directory, to the application Pi:

apjava -u MyFirstProbe.xmj -java=/opt/j2sdk1.4.0_01 \
-classpath .:$APROBE/examples/java/Pi Pi

apmkadi

Listing Information about a Program

NAME

apmkadi - make an Aprobe Debug Information file

SYNOPSIS

apmkadi options module_names

DESCRIPTION

apmkadi is a utility for extracting from a module or modules the symbol and debug information required by Aprobe, and writing that information to a separate file. This file is called an ADI file and must have the extension .adi. Once the ADI file has been created you can strip your executable of debug information and symbol information.

Later when you want to probe the stripped module you include the ADI file with the UAL file (e.g., trace.ual) to aprobe. Aprobe will use the debug information in the ADI file to instrument the desired modules.

A single ADI file can have debug information from several modules. All the modules present on the apmkadi command line will be processed into a single ADI file.

If an ADI file is specified with -u but no other option is given, the contents are "verified" by comparing the checksum for each module as recorded in the ADI file to the checksum for the corresponding module. This is extremely useful in identifying a mismatch between the environment where a probe is developed and that in which it is executed or formatted. When verifying checksums, no output is generated. If -d is used, the contents of the ADI file are dumped to stdout. If -c is used, specify two ADI files each preceded by -u to compare their contents.

Note that an ADI file only provides debug information and symbols to aprobe and [#apfomat|apformat]] -- not to apc or apcgen. You must still have the debug information available when you generate or compile probes. Therefore you should make a copy of the executable for deployment, and strip that, leaving the unstripped version in the development environment.

OPTIONS

The options are:

'-c'
Compare two ADI files ignoring file paths and timestamps.
'-d'
Dump binary ADI file(s) as human-readable text.
'-h'
Show brief help output.
'-s'
Strip file paths and timestamps when generating an ADI file.
'-u' ADI_name

specify the name of an ADI file to compare, dump or verify.
'-v'
Verbose output.
'-o output_name'''

specify the name of the ADI file to be produced. The default is the first module name with a suffix of .adi.

PARAMETERS

module_names

the modules from which to collect symbol and debug information.

EXAMPLES

Given an executable hello, and an file myprobes.apc which references it, you would:

  • Compile myprobes.apc against the unstripped executable to produce myprobes.ual:
apc myprobes.apc -x hello
  • Generate the ADI file from the unstripped executable to produce hello.adi:
apmkadi hello
  • Save the "debug" version, then strip the executable:
cp hello hello.debug
strip hello
  • Run aprobe (and apformat) in combination with the stripped program:
aprobe -u myprobes.ual -u hello.adi hello
apformat -u hello.adi hello

Note that you must explicitly provide the ADI file name on the apformat command line. Apformat already knows about the UAL file.

  • Verify that hello.adi matches a specific instance of the hello program:
apmkadi -u hello.adi /work/test/bin/hello

aprobe

Running a Program With Aprobe

NAME

aprobe - Patches probes into an executable image and runs it.

SYNOPSIS

aprobe  [-h] [-v][-p] [-deb] [-i size] [-if][-q option ]
  [-k fileset_size] [-n ring_size] [-s apd_size]
  [-sp apd_size] [-t n_files]
  [-cp classpath]
  {-u ual_name [-p "parameters_for_ual"]}
  {-u dir_name}
  {-u adi_name}
  {-u xmj_name}
  [-d apd_name] [-dll module_name]
 executable [parameters_for_executable]

DESCRIPTION

The aprobe command performs the process known as Dynamic Action Linking, which is the insertion of a UAL into a target executable program. It loads the image of an executable program into memory, then combines it with the probes that are in User Action Libraries (UAL files) and runs the resulting executable. The UALs are those created by the Aprobe compiler (see apc) and the executable is any executable application program, produced by any means, that would run on the target machine, even if its source code is not available. The probes allow you to modify the behavior of the executable, or to monitor it by collecting and logging data while the executable is running. Any logged data will be stored in Aprobe data files (APD files).

The inputs to the aprobe command are as follows:

  • The file name of your executable program (required)
  • Any command line parameters needed by the executable program (optional)
  • The file name(s) of any User Action Libraries that are to be used for probing your executable (optional)
  • Parameters for each of the User Action Libraries (optional); and
  • The location of the Aprobe runtime (required).

All but the last of these inputs are provided via options or parameters on the aprobe command line. The location of the Aprobe runtime is provided by setting the environment variable APROBE to the installation directory of the Aprobe product.

Note that on AIX only, aprobe is a shell script which invokes $APROBE/aprobe.exe. This means that the the PID of the target program itself will be different from the one started by the aprobe command. If this is a problem, you may execute aprobe.exe directly with the same command line -- the only difference will be that Ctrl-Z will cause aprobe to hang.

UAL SEARCH ORDER

The following locations are searched for a UAL file if no path is specified as part of the ual_name:

  1. The current directory
  2. The $APROBE/ual_lib directory
  3. All directories that are listed in the $APROBE_LIBPATH environment variable. The format of this variable is similar to the PATH environment variable. That is, it is a list of directories separated by a colon character (':').

OPTIONS

-cp' classpath
add classpath to the Java classpath when running the program.
'-d' filename
Data is to be logged to an APD file with this filename. The default output filename will be executable_name.apd.
'-deb'
Pause before running the target executable, to allow attaching to it with a debugger such as dbx.
'-dll' module
Preloads the module before program execution. This allows your probes to reference entities within the dynamically loaded library module even before program begins to execute (which is when the module is normally loaded).
On Solaris and Linux, the -dll option appends module name to the LD_PRELOAD environment variable before aprobe runs the target executable. This means the usual restrictions apply, so the executable won't load unless module is found. On Solaris, use of LD_PRELOAD implies that if an executable is bound with libdal.so, then any -dll options in the APO file will be ignored because the target executable has already been loaded before the APO file is read (so you'd have to set the LD_PRELOAD environment variable directly).
'-h'
Display the help text.
'-i' ring_size
APD file size increment. This is the incremental size by which each memory mapped logged data (APD) file subsequently grows until it reaches its maximum size. The default size is 4096 bytes.
'-if'
Immediate formatting. This causes any log statements within the probes to immediately call the corresponding format functions while the probed executable program is still running, rather than default to the usual logging of data to the APD file for later formatting by apformat.
'-k' number
Number of APD file sets to keep in addition to the one currently being generated. This option provides a mechanism for backing up APD file sets, or supporting multiple concurrent processes. The number must be greater than 0. If -k is specified, aprobe will create a directory, based on the name of the APD file and the PID of the process, to store the APD files generated by the current execution of aprobe. For successive invocations of aprobe, a new directory will be created. Once number 1 directories have been created, aprobe will delete the oldest directory before creating a new one. See "APD file" for more information on the management of the APD file.
'-n' number
Number of additional APD files in the list, other than the single special persistent APD file. The number must be greater than zero; the default is 1. A zero turns off any logging to any APD files other than to the persistent APD file. Besides the persistent APD file, the specified number of APD files are created, and each will be given a numeric suffix that ranges starting at 1 and increasing as the program runs, with only the most recent number files being preserved. See "APD file" for more information on the management of the APD file.
'-p'
Do not produce a persistent (or any other) APD files. This is useful if the probe does no logging, or in conjunction with -if.
'-q heapsize=n_bytes'
Specify the initial heap (allocated memory) size to be used by Aprobe for its data. The default is 2097152 (2MB).
'-q stacksize=n_bytes'
Specify the stack size to be used by Aprobe for its data. The default is 65536 (64KB).
'-q mmap=address'
Set a target address for all Aprobe mmap requests.
'-q min_heap'
Free (and lose) symbols after Aprobe instrumentation to save run-time memory.
'-q conserve_patch_space'
Use minimal patch space per routine, at small additional time cost.
'-q enable_trap_patches'
Allow (slower) trap patches when patch space in reach is not available.
'-q enable_patch_alloc'
Allow patch areas to be allocated when needed (uses process address space).
'-q do_not_sacrifice=file'
Provide a file with a list of function name patterns not to sacrifice for patch areas. Patterns are one per line and may include wildcard.
'-q execvp'
Interpret parameters argument as the name of a text file containing application command line arguments, one per line.
'-s' apd_size
Maximum size of logged data in each APD file. The default is 256MB if the number of additional APD files in the list is 1 (see option -n 1). Otherwise, the default is 2MB.
'-sp' apd_size
Maximum size of the logged data in the persistent APD file. The default is 256MB.
'-t' n_files
The maximum total number of APD files to preserve.
n_files = 0 implies no maximum (default). This differs from
-n ring_size because the ap_LogSnapshot() operation may preserve many rings.
'-u ual_name ['-p "parameters_for_ual"]
Include the specified User Action Library (UAL file). The -u option may be repeated multiple times, once for each UAL, but each must have its own -p option if that UAL needs to be given any parameters. The -p option after each -u option specifies the parameters for only that UAL. The parameters_for_ual must be enclosed within quotation marks if there is more than one parameter. See "Parameters to a UAL" for how these parameters are accessed from your probe.
'-u' dir_name
Include all files ending in .ual or .adi in the specified directory, if any. This is equivalent to specifying -u filename each UAL or API filename found in directory dir_name.
'-u' adi_name
Include the designated Aprobe Debug Information file (ADI file). The -u option may be repeated multiple times if there are multiple ADI files. See "apmkadi".
'-u' xmj_name
Include the designated Aprobe Java Deployment Descriptor. This describes the Java probes that are to be applied. See "Writing Java Probes".
'-v'
Verbose.

PARAMETERS

executable

The file name of the user's executable program to be probed. Either the full path to the program must be given or the file must exist in the current working directory.
parameters_for_executable

Any parameters to be passed to the user executable when it is invoked.

EXAMPLES

Run the executable named hello, using the UAL named hello.ual

aprobe -u hello.ual hello

Run "maze -d sun15:0" with maze.ual, specifying the -d option for maze and indicating (with -if) that the log operation should invoke the formats directly at runtime rather than logging data for formatting by apformat:

aprobe -u maze.ual -if /usr/openwin/demo/maze -d sun15:0

apsymbols

List the symbols in a program

NAME

apsymbols
an interface to the info.ual predefined probe, which lists the symbols that can be probed in a program. (See "apinfo" and "Info Probe: info.ual").

SYNOPSIS

apsymbols [-a] executable

DESCRIPTION

This command invokes aprobe on the executable_file provided, applying the info.ual predefined to list the symbols in the executable. See also: apnfo.

OPTIONS

The options are:

'-a'
print symbols for all modules, not just the application module

PARAMETERS

executable
the program to print symbols for.

EXAMPLES

List the symbols that can be probed in a.out:

apsymbols a.out

atcmerge

Merge Test Coverage Data

NAME

atcmerge - a tool which merges one or more binary test coverage data (".tc") files and produces a report of the combined test coverage results.

SYNOPSIS

atcmerge [-h] [-b tc_file ] [-d bc_file ] 
               [-f len] tc_files

DESCRIPTION

The atcmerge tool merges results of multiple runs of coverage.ual into a single combined summary report (see "Test Coverage Probe: coverage.ual"). Such a summary report is generally needed when multiple runs with different input data or probes are used to force all paths to be executed. It is generally expected that all runs will be same executable with the same configuration file but this is not required -- apparently different instances of the same function from different runs will be listed separately.

atcmerge consumes and optionally produces TC files (with suffix .tc) and BC files (with suffix .bc) which are initally produced by the coverage.ual probe. The summary report is always written to standard output in ASCII format. Optionally, the same summary report data also may be written out to a TC file in a format that is suitable for later input to atcmerge.

OPTIONS

The options are:

'-h'
Displays brief help message.
'-b' tc_file
names the binary test coverage (".tc") data_file into which the combined test coverage data will be emitted. If the data_file already exists, then its initial contents will be merged with data from other report_files. By default, no data_file is produced.
'-d' bc_file
names the optional detail coverage file (.bc) into which the combined test coverage detail data will be emitted. By default, no detail data file is produced.
'-f len'''
Truncate function names to len (0 prevents truncation)

PARAMETERS

tc_files
The list of filenames of one or more test coverage data (".tc") files generated by apformat or previous runs of atcmerge.

EXAMPLES

The on-line example in examples/learn/test_coverage' shows the use of coverage.ual and atcmerge with multiple runs.

apbc

Annotated Source Coverage Report

NAME

apbc - a tool which produces an annotated source report from test coverage data.

SYNOPSIS

apbc ['-h] bc_files src_files

DESCRIPTION

The apbc tool produces annotates source listings from source files and test coverage data produced by "Test Coverage Probe: coverage.ual".

apbc consumes BC files (with suffix .bc) which are initally produced by the coverage.ual probe. The summary report is always written to standard output in ASCII format.

OPTIONS

The options are:

'-h'
Displays brief help message.

PARAMETERS

bc_files
The list of filenames of one or more test coverage detail data (".bc") files generated by apformat or previous runs of atcmerge.
src_files
The list of filenames of one or more source files to include in the report. By default, all files referenced in the .bc file are listed; specifying source files at the end of the apbc parameter list limits the output to those files only.

EXAMPLES

The on-line example in examples/learn/test_coverage2' shows the use of coverage.ual and atcmerge with multiple runs.

abrmerge

Merge Branch Coverage Data

NAME

abrmerge - a tool which merges one or more branch coverage data (".brc") files and produces a report of the combined branch coverage results.

SYNOPSIS

abrmerge [-hv] [-b brc_file] [-o output_file ] [-m merge_file] [-q sub-option] brc_files src_files

DESCRIPTION

The abrmerge tool produces reports and merges results of multiple runs of coverage.ualand brcov.ual into a single combined summary report (see "Test Coverage Probe: coverage.ual" and "Branch Coverage Probe: brcov.ual"). A merge is generally needed when multiple runs with different input data or probes are used to force all paths to be executed. It is generally expected that all runs will be same executable with the same configuration file but this is not required.

abrmerge consumes and optionally produces BRC files (with suffix .brc) which are initally produced by the coverage.ual and brcov.ual probes. The reports are written to standard output in ASCII format unless -o or -q html are used. Optionally, the merged data also may be written out to a BRC file in a format that is suitable for later input to abrcmerge.

If src_files are present, abrmerge produces an annotated source reports with line counts, branch information, etc.

OPTIONS

The options are:

-h
Displays brief help message.
-v
Displays progress messages.
-m brc_file
Names the branch coverage (".brc") data_file into which the combined branch coverage data will be emitted. If the data_file already exists, then its initial contents will be merged with data from other report_files. By default, no data_file is produced.
-o output_file
Names the file where reports are written.
-q sub-option
Selects a report sub-option. The html, branches, edges, overall, detail, exception, and showall options can be combined with other report options.

The -q sub-options are:

html
produce report in HTML format.
[no]branches
Include (or not) branches in report.
[no]edges
Include (or not) edges (branch targets) in report.
[no]overall
Include (or not) overall summary in report.
[no]detail
Include (or not) function details in report.
[no]exception
Include (or not) exception branches in report.
[no]showall
Include (or not) branch/edge information even if no line count.
counts
use counts report format.
dyncov
use dyncov report format.
lcov
use lcov report format (default).
percent
use percentage report format.
raw
use raw report format.

PARAMETERS

brc_files
The list of filenames of one or more branch coverage data (".brc") files generated by apformat or previous runs of abrcmerge.
src_files
The list of filenames of one or more source files to beused for an annotated source report.

EXAMPLES

Here several examples of creating a simple branch coverage report from several branch coverage data files (".brc") and the associated source files:

abrmerge -o myreport.txt *.brc *.c                   # text reoprt
abrmerge -o myreport.html -q html *.brc *.c   # HTML report

See this brcov.ual for more examples.

apdemangle

Demangle Symbols

NAME

apdemangle - a tool which demangles symbols names.

SYNOPSIS

apdemangle [-hv] [-q sub-option] names 

DESCRIPTION

The apdemngle tool takes mangled symbol names and demangles them using the appropriate demangling algorithms for the target. By default apdemangle will try the available algorithms until it finds one that works. You can override that process and specify which algorithm to use. apdemangle,/code> will output on demanlged name per line. If apdemangle cannot demangle a symbol name it will output the original symbol name.

OPTIONS

The options are:

'-h'
Displays brief help message.
'-v'
Displays progress messages.
'-q sub-option'''
Selects a sub-option.

The -q sub-options are:

pa
Use PowerAda demangling algorithm.
gnat
Use GNAT .demangling algorithm.
gcc
Use gcc demangling algorithm.
subp
Demangle as a subprogram.
data
Demangle as data.

PARAMETERS

names
The list of symbol names to demangle.

EXAMPLES

apdemangle -q pa sec_main

[Next] [Previous] [Top] [Contents] [Index]

Copyright 2006-2017 OC Systems, Inc.