ssrun(1)

NAME
     ssrun - set up and run a process to collect SpeedShop performance data

SYNOPSIS
     ssrun [options] command [args]

DESCRIPTION
     ssrun is used by the SpeedShop performance tools to establish the
     environment to capture performance data for an executable, and create a
     process from the executable (or an instrumented version), and then run
     it.  When performance data is collected, it is written to a file whose
     name is of the form <command>.<exptype>.<code><pid> where <code> can be
     'm' for the master process created by ssrun, 'p' for a process created by
     a call to sproc(), 'f' for a process created by a call to fork(), 'e' for
     a process created by a call to exec(), 's' for a system call process and
     'fe' for a process created by a call to fork() and exec() with
     environment variable _SPEEDSHOP_TRACE_FORK_TO_EXEC being set to False.
     Data may be examined using prof(1).

     The following options may be given:

     - <exptype> | -exp <exptype>
          Specifies the type of SpeedShop experiment to run.  The value of
          <exptype> specifies the particular performance data that will be
          recorded during the run.  See the speedshop(1) man page for the list
          of supported experiments.  Some experiments require that the target
          process be instrumented to collect data; if necessary,
          instrumentation (by pixie(1)) will be performed, and the resultant
          instrumented executable run.  The experiment type may also be set by
          setting the environment variable _SPEEDSHOP_EXPERIMENT_TYPE.  If
          both are set, and they are different, a warning message will be
          printed, and the command line argument will prevail.
          Each experiment type corresponds to a set of "marching orders" that
          the runtime will use.  This facility is provided to allow users to
          specify customized experiments, and will be more fully documented in
          subsequent releases.  Marching orders may also be set by setting the
          environment variable _SPEEDSHOP_MARCHING_ORDERS, or by providing a
          mo argument to ssrun.  If a known experiment is specified, and the
          marching orders are also specified, and they are different, a
          warning will be printed, and the marching orders will prevail.  If
          the experiment is not known, its name will be used and no warning
          issued; if no experiment name was specified, the experiment name
          will be set to "marching-orders".

     -mo marching-orders
          Specifies marching orders; if this option is used, the environment
          variable _SPEEDSHOP_MARCHING_ORDERS will not be examined.

     -purify
          Specifies (if the independent Purify product is installed), that
          purify should be run on the target, and the resulting purify'd
          executable run.  Note that -purify and SpeedShop performance
          experiments can not be combined.

     -v | -verbose
          Specifies that a log of the operation of ssrun should be printed to
          stderr.  The same behavior occurs if the environment variable
          _SPEEDSHOP_VERBOSE is set a to a zero-length string.

     -V   Specifies that a detailed log of the operation of ssrun should be
          printed to stderr.  The same behavior occurs if the environment
          variable _SPEEDSHOP_VERBOSE is set a to a non-zero-length string.
          In this case, a non-zero-length _SPEEDSHOP_VERBOSE environment
          variable will be set, so that the target and any descendant
          processes will see it.

     -workshop
          Forces special instrumentation so that the experiment files can be
          read by WorkShop's cvperf analyzer unless one of the capture modules
          of the experiment also requires instrumentation.

     -quiet
          Suppresses all output other than error messages.  If set,
          _SPEEDSHOP_SILENT will be set, so that the target and any descendant
          processes will see it.

     -hang
          Specifies that the process should be left waiting just before
          executing its first instruction.

     -port hostname portno
          Specifies that the process is to be left waiting, and, in addition,
          notifications of status be sent to the socket on the host given by
          hostname and port given by portno from the command line.  When the
          process is ready, a message of the form "running <pid> <host>" will
          be sent to inform the requestor of the target process' PID, and
          (possibly remote) host.  A debugger may then attach to it and take
          control of its execution.

     -x   Specifies that the process is to be left waiting, and, in addition,
          that the window of the WorkShop Debugger requesting the creation (as
          given by the display-id and window-id on the command line) be
          informed of the target process' PID.  A debugger may then attach to
          it and take control of its execution.

     -name target-name
          Specifies that the target, instrumented or not, should be run with
          argv[0] set to target-name.  Normally, both instrumented and
          uninstrumented executables are run with argv[0] set to the original
          name.

SEE ALSO
     speedshop(1), ssdump(1), prof(1), pixie(1), malloc_ss(3), fpe_ss(3),
     io_ss(3), cvperf(1)