Index for Section 5

Alphabetical listing for P

Bottom of page

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

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

  This interface will be retired in a future major release. See pixie(1) for
  the replacement interface.

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
      option 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 option if the application
      does not create threads; in this case the instrumented executable is
      named appl_prog.pixie.

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

  atom_options
      Specifies options to the atom command.  See the atom(1) reference page
      for descriptions of other options accepted by the atom command, such as
      those that enable instrumentation of shared libraries, specify the
      names of instrumented objects, and request debugging information.

      After you have instrumented an application that uses libc.so,
      libpthread.so, or other shared libraries, you must set the
      LD_LIBRARY_PATH environment variable to point to the directory
      containing the instrumented shared libraries. Typically, this would be
      the current directory or the directory specified by the -shlibdir
      option. (You may leave LD_LIBRARY_PATH pointing to this directory while
      running other, uninstrumented applications.)

  The pixie tool accepts the following options as arguments to the -toolargs
  option:

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

  -bbaddrs name
      Specifies the filename of the basic block addresses file.	 Default is
      appl_prog.Addrs.

  -bbcounts name
      Specifies the filename of the basic block counts file. Default is
      appl_prog.Counts.

  -bb procname
      Profiles the procedure procname as if it has only one basic block. The
      effect is that only the entry point is instrumented, so the procedure
      body can contain code that cannot be safely instrumented (for example,
      assembly language computed jumps to unlabeled locations).	 The reported
      instruction count will be accurate if the procedure has no branches, it
      will be a little high if there are forward branches, and it may be much
      too low if there are backward branches (eg loops).

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

  -fork
      Indicates that a call-shared program forks. You must specify the -fork
      option if libc.so is not being fully instrumented and the call-shared
      program being instrumented makes a fork or vfork system call. When the
      -fork option is specified, each child process produces a separate
      profiling data file (or possibly several if the -threads option is also
      specified) unless it makes an exec system call.  A profile generated
      from all of the profiling data files represents the behavior of the
      parent process and its children; a profile generated from any single
      profiling data file represents the single process or thread associated
      with that file.

  -[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.

  -[no]threads
      When used with the atom option -env threads, -threads causes pixie to
      generate a separate profile for each thread in the program. The profile
      data files are named program.Counts.sequence (or
      program.Counts.pid.sequence for a forked subprocess), where sequence is
      the thread sequence number. This switch can be disabled by a -nothreads
      switch later in the -toolargs list.

  You can define the PIXIE_ARGS environment variable to supply the following
  run-time options 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 option. The -sigdump option is useful for programs that
      never terminate.

  -[no]threads
      If the program was instrumented with the -env threads and the
      -toolargs=-threads options, the -threads and -nothreads options can be
      specified in PIXIE_ARGS to confirm or override the per-thread profiling
      option, respectively.

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.

  If you are instrumenting a shared-library program, you will probably need
  to set the LD_LIBRARY_PATH environment variable (see atom(1) for more
  information).

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

  Programmer's Guide

Index for Section 5

Alphabetical listing for P

Top of page