This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).

sample(1)                 BSD General Commands Manual                sample(1)

NAME
     sample -- Profile a process during a time interval

SYNOPSIS
     sample pid | partial-executable-name [duration [samplingInterval]] [-mayDie] [-wait] [-file filename]
            [-subst oldBinary newBinary]

DESCRIPTION
     sample is a command-line tool for gathering data about the running behavior of a process.  It stops the
     process at user-defined intervals, usually every 1-20 milliseconds.  It records the current function
     being executed by the process, and checks the stack to find how the current function was called.  It
     then lets the application continue.

     At the end of a sampling session, sample produces a report showing which functions were executing dur-ing during
     ing the sampling.  The data is condensed into a call tree, showing the functions seen on the stack and
     how they were called.  (This tree is a subset of the actual call tree for the execution, since some
     functions may not have been executing during any of the sampling events.)  The tree is displayed textu-ally, textually,
     ally, with called functions indented one level to the right of the callee.

     The user of sample specifies a target process (either by process id, or by name), the duration of the
     sampling run (in seconds), and a sampling rate (in milliseconds).  The sampling rate should usually be
     between 1 msec and 20 msec.  Faster sampling rates provide more samples and a better chance to capture
     all the functions that are executing; however extremely fast sampling rates might cause multiple sam-ples samples
     ples to be taken when the process is stopped.  Longer sampling durations ensures better data.

     If the sampling rate is not specified, a default of 1 millisecond is used, as of Mac OS X 10.5.  (On
     earlier releases the default rate was 10 milliseconds.)

     If the sampling duration is not specified, a default of 10 seconds is used.

     The [-mayDie] flag tells sample to immediately grab the location of symbols from the application, on
     the assumption that the application may crash at any point during the sampling.  This ensures that sam-ple sample
     ple can give information about the call stacks even if the process no longer exists.

     The [-wait] flag tells sample to wait for the process specified (usually as a partial name or hint) to
     exist, then start sampling that process.  This option allows you to sample from an application's
     launch.

     The [-file] flag names where the output should be written.  If this flag is not specified, results are
     written to a file in /tmp called <application name>_<processid>.<XXXXXX>.sample.txt, where each 'X' is
     replaced by a random alphanumeric character.

     [-subst] allows the caller to specify the full path to the executable.  If the application was not run
     with the full path, or sampler is not run with the -subst flag, sample cannot get symbol table informa-tion information
     tion from the executable.  This flag thus lets you tell sample where to get the information needed to
     gather symbol information.  The first argument after -subst is the name of the binary to be replaced,
     and the second is the name of the binary that will instead be searched for symbolic information.

     The analysis done by sample is called ``sampling'' because it only checks the state of the program at
     the sampling points.  The analysis may miss execution of some functions that are not executing during
     one of the samples, but sample still can provide useful data about commonly executing functions.

     sample is similar to gprof.  gprof also performs statistical sampling at 10ms intervals to identify the
     currently executing function, but instruments the program to gather a complete call graph for the pro-gram. program.
     gram.

     Like profiling, sample gathers runtime data.  However, because it only checks at intervals, it only
     sees some of the functions that are running.  Longer durations or shorter sampling times can improve
     coverage.

SEE ALSO
     gprof(1)

     The developer tools for the system also include a graphical application, /Developer/Applica-tions/Instruments.app, /Developer/Applications/Instruments.app,
     tions/Instruments.app, that provides instruments that give information similar to that provided by
     sample. The Sampler instrument graphically displays dynamic, real-time CPU sampling information.

BSD                             March 15, 2007                             BSD