*** UNIX MANUAL PAGE BROWSER ***

pixie(5) File Formats Manual pixie(5) 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 pro- filed. 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 proce- dure 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 sup- ported. 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 op- tion.) 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, spec- ify the names of instrumented objects, and request debugging in- formation. The pixie tool accepts the following flags as arguments to the -toolargs flag: [Permits] or suppresses messages summarizing the bi- nary-to-binary translation process. Default: -noquiet. Specify a name for the file of basic block addresses. Default is to remove any lead- ing directory names from the program and append Specifies the full filename of the basic block counts file. Default: program.Counts. Specifies the directory to which pixie writes the file for the run. The default is the current directory. [Disables] or enables the addi- tion of the process-id number to the filename of the basic block counts file. This is useful for collecting information for multiple invoca- tions of the pixie output file. Default: -nopids. You can define the PIXIE_ARGS environment variable to supply the fol- lowing run-time flags to the instrumented program generated by pixie: Specifies the directory to which pixie writes the file for the run. The default is the current directory. [Disables] or enables the addi- tion of the process-id number to the filename of the basic block counts file. This is useful for collecting information for multiple invoca- tions 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 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 multi- ple instances of the specified signal) to be merged into a single pro- file that reflects the whole test run. When multiple instances of the signal occur, you must rename each of the individual files to, for ex- ample, foo.Counts.n. Renaming the files in this fashion allows you to examine all of the 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 ba- sic blocks, and writes an equivalent program containing additional code that counts the execution of each basic block. (A basic block is a re- gion of the program that can be entered only at the beginning and ex- ited only at the end.) The pixie utility also generates a file contain- ing the address of each of the basic blocks. When you run the pixie-generated program, it will - provided it termi- nates 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 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(1) is available only if the Developer's Tool Kit and associated reference pages are installed on your system.) Programmer's Guide pixie(5)