Index for Section 5

Alphabetical listing for P

pixie(5)
NAME
  pixie - Adds profiling code to a program

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

PARAMETERS
  appl_prog
      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
  -tool pixie
      Identifies the pixie tool to the atom command.

  -env threads
      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.)

  -toolargs="arg1 arg2 ..."
      Passes arguments to the pixie tool's instrumentation routines. Use
      whitespace characters to separate arguments from their parameters (if
      any) and from other arguments.

  atom_flags
      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:

  -[no]quiet
      [Permits] or suppresses messages summarizing the binary-to-binary
      translation process. Default: -noquiet.

  -bbaddrs name
      Specify a name for the file of basic block addresses.  Default is to
      remove any leading directory names from the program and append .Addrs.

  -bbcounts name
      Specifies the full filename of the basic block counts file.  Default:
      program.Counts.

  -dirname directory
      Specifies the directory to which pixie writes the .Counts file for the
      run.  The default is the current directory.

  -[no]pids
      [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:

  -dirname directory
      Specifies the directory to which pixie writes the .Counts file for the
      run.  The default is the current directory.

  -[no]pids
      [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.

  -sigdump signame
      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