Content-type: text/html Man page of pixie

pixie

Section: File Formats (5)
Index Return to Main Contents
 

NAME

pixie - Adds profiling code to a program  

SYNOPSIS

atom appl_prog -tool pixie [-env threads] [-toolargs="arg1 arg2..."] [atom_flags...]


 

PARAMETERS

File name of a fully linked shared or nonshared executable to be profiled. This program should be compiled with the -g1, -g2, or -g3 flag to obtain more complete profiling information. If the default symbol table level (-g0) has been used, line number information, static procedure names, and file names are unavailable to the profiling code.
 

OPTIONS

Identifies the pixie tool to the atom command. Specifies that the pixie tool is being invoked on an application that runs in a threaded environment. To make run-time analysis of an application that creates threads threadsafe, you must specify -env threads in the pixie command. Only POSIX threads created using the pthread_create function are supported.

The threadsafe instrumented executable is named appl_prog.pixie.threads by default. You may omit the -env threads flag if the application does not create threads; in this case the instrumented executable is named appl_prog.pixie.
When using this option, do not instrument system libraries. (Do not specify system libraries with the -incobj option; also, if you specify -all, specify system libraries with the -excobj option.) Passes arguments to the pixie tool's instrumentation routines. Use whitespace characters to separate arguments from their parameters (if any) and from other arguments. Specifies flags to the atom command. See the atom(1) reference page for descriptions of other flags accepted by the atom command, such as those that enable instrumentation of shared libraries, specify the names of instrumented objects, and request debugging information.

The pixie tool accepts the following flags as arguments to the -toolargs flag: [Permits] or suppresses messages summarizing the binary-to-binary translation process. Default: -noquiet. Specify a name for the file of basic block addresses. Default is to remove any leading directory names from the program and append .Addrs. Specifies the full filename of the basic block counts file. Default: program.Counts. Specifies the directory to which pixie writes the .Counts file for the run. The default is the current directory. [Disables] or enables the addition of the process-id number to the filename of the basic block counts file. This is useful for collecting information for multiple invocations of the pixie output file. Default: -nopids.

You can define the PIXIE_ARGS environment variable to supply the following run-time flags to the instrumented program generated by pixie: Specifies the directory to which pixie writes the .Counts file for the run. The default is the current directory. [Disables] or enables the addition of the process-id number to the filename of the basic block counts file. This is useful for collecting information for multiple invocations of the pixie output file. Default: -nopids. Specifies a signal name that the instrumented program will catch. When the program catches this signal, it writes the basic block counts to the .Counts file and resets all of the basic block counts to zero. Setting the basic block counts to zero allows multiple profiling data files (which result from multiple instances of the specified signal) to be merged into a single profile that reflects the whole test run. When multiple instances of the signal occur, you must rename each of the individual .Counts files to, for example, foo.Counts.n. Renaming the files in this fashion allows you to examine all of the .Counts files by issuing a prof command with a wildcard (*) for the increment field in the file names.

Your program must not reset the signal handler for the signal specified by the -sigdump flag. The -sigdump flag is useful for programs that never terminate.
 

DESCRIPTION

The pixie Atom tool reads an executable program, partitions it into basic blocks, and writes an equivalent program containing additional code that counts the execution of each basic block. (A basic block is a region of the program that can be entered only at the beginning and exited only at the end.) The pixie utility also generates a file containing the address of each of the basic blocks.

When you run the pixie-generated program, it will - provided it terminates normally or as a result of a call to exit(2) - generate a file containing the basic block counts. The name of the file is that of the original program with any leading directory names removed and .Counts appended. Programs that call fork() generate multiple basic block counts files, each with the process-id number appended to the name. The prof(1) and pixstats(1) utilities can analyze these files and produce a listing of profiling data.
 

SEE ALSO

atom(1), prof(1), pixstats(1), pdtostd(1), dxprof(1). (dxprof is available as an option.)

Programmer's Guide


 

Index

NAME
SYNOPSIS
PARAMETERS
OPTIONS
DESCRIPTION
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:43:14 GMT, October 02, 2010