unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



gprof(1)							     gprof(1)



NAME

  gprof	- Displays call-graph profile data

SYNOPSIS

  gprof	[options] prog_name [profile_file...]

OPERANDS

  prog_name
      Name of the program executable whose profile is to be displayed. For a
      program compiled for PC-sampling with the	-pg option or instrumented
      for PC-sampling with hiprof, specify the name of the executable that
      was run to produce the profile file specified. For other kinds of
      hiprof profiling,	specify	the uninstrumented executable that was the
      input to hiprof. The program should also 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 informa-
      tion, static procedure names, and	file names are unavailable to the
      profiling	code.

  profile_file
      Name of the call graph profile file.  This is either a PC	sampling pro-
      file file	or an instrumented event-counting profile file.	By default,
      gprof looks for the profile file named gmon.out (see the description of
      the PROFDIR environment variable). If more than one profile_file is
      specified, gprof output shows the	sum of the profile information in the
      specified	profile	files.

OPTIONS

  For each gprof option, you need type only enough of the name to distinguish
  it from the other options.

  -a  Suppresses the printing of statically declared functions.	If this
      option is	given, all relevant information	about the static function
      (for example, time samples, calls	to other functions, calls from other
      functions) belongs to the	function loaded	just before the	static func-
      tion in the a.out	file.

  -all
      Causes the profiles for all shared libraries (if any) described in the
      data file(s) to be displayed, in addition	to the profile for the exe-
      cutable.

  -asm
      Profiles each instruction	within selected	procedures. (Use this option
      only with	hiprof's PC-sampling profile data, and note that the first
      few instructions of each instrumented procedure includes the code	that
      counted calls to that procedure.)

  -b  Suppresses the printing of a description of each field in	the profile.

  -bounded
      Limits those functions for which a call-graph entry is printed to	those
      functions	specified in the -f or -F options.  By default,	call graphs
      are printed for all procedures in	the tree of procedures called by the
      selected procedures.

  -e routine
      Suppresses the printing of the graph profile entry for routine and all
      its descendants (unless they have	other ancestors	that are not
      suppressed). More	than one -e option may be given.  Only one routine
      may be given with	each -e	option.

  -E routine
      Suppresses the printing of the graph profile entry for routine and its
      descendants (same	as -e),	and also excludes the time spent in routine
      and its descendants from the total and percentage	time computations.
      The library routines used	to collect the profile data are	excluded by
      default (except for certain common libpthread routines).

  -excobj object_file_name
      Causes the profile for the named executable or shared library not	to be
      printed. You can use this	option multiple	times in a single gprof	com-
      mand.

  -f routine
      Prints the graph profile entry of	only the specified routine and its
      descendants.  More than one -f option may	be given. Only one routine
      may be given with	each -f	option.	 The -f	option overrides the -e
      option.

  -F routine
      Prints the graph profile entry of	only routine and its descendants
      (same as -f), and	also uses only the times of the	printed	routines in
      total time and percentage	computations.  More than one -F	option may be
      given.  Only one routine may be given with each -F option.  The -F
      option overrides the -E option.

  -graph
      Profiles procedures as an	indexed	call graph (default).

  -heavy
      Profiles source lines, listing the most heavily used first. (Use this
      option only with hiprof's	PC-sampling profile data.)

  -incobj object_file_name
      Causes the profile for the named shared library to be printed, in	addi-
      tion to the profile for the executable. You can use this option multi-
      ple times	in a single gprof command.

  -Ldir
      Changes the library directory search order for shared object libraries
      so that gprof looks for them in dir before the library recorded in
      profile_file and the default library directories.	 You can specify mul-
      tiple -Ldir switches to specify several directory	names.

  -L  Change the library directory search order	for shared object libraries
      so that gprof never looks	for them in the	default	library	directories.
      Use this option when the default library directories should not be
      searched and only	the directories	specified by -Ldir are to be
      searched.

  -lines
      Profiles source lines, in	order within selected procedures. (Use this
      option only with hiprof's	PC-sampling profile data.)

  -merge filename
      Produces a profile file with the specified file name, which represents
      the sum of the profile information contained in all the specified	pro-
      file files. Same as -s, except that -merge lets you specify the name of
      the resulting profile file (rather than using the	default	file name,
      gmon.sum). Also lets you use gmon.sum as an input	file. Regular profile
      reports are not printed when -merge is specified.

  -numbers
      Prints each procedure's object file name,	source file name, and start-
      ing line number if source	file information is available from the object
      file.  Use this switch when the profiled program contains	multiple
      static procedures	with the same name.  In	such cases, the	source and
      object file names	uniquely identify each procedure.

  -procedures
      Profiles procedures, listing the most heavily used first (default).

  -s  Produces a profile file, gmon.sum, which represents the sum of the pro-
      file information in all the specified profile files. This	summary	pro-
      file file	may be given to	subsequent executions of gprof (probably also
      with a -s) to accumulate profile data across several runs	of an a.out
      file.

  -scaled
      Scales all results into scientific notation so that numbers that are
      either very small	or very	large can be printed within the	column boun-
      daries. Larger numbers lose very little precision	to rounding off,
      whereas smaller numbers gain precision.

  -totals
      Prints cumulative	statistics for the entire object file instead of for
      each procedure in	the object.

  -version
      Prints the tool's	version	number.

  -z  Displays routines	that have zero usage, as indicated by call counts and
      accumulated time.

DESCRIPTION

  The gprof command produces an	execution profile of programs. The effect of
  called routines is incorporated into the profile of each caller. Profile
  data of three	kinds is accepted by gprof:

    +  PC-sampling profiles of CPU time	produced by programs compiled with
       the -pg option of the cc	command

    +  PC-sampling profiles of CPU time	produced by programs instrumented by
       hiprof.

    +  Event-counting profiles of CPU time or page faults produced by pro-
       grams modified by hiprof.

  PC-Sampling with cc -pg


  The profile data is taken from one or	more specified call graph
  profile_files	(gmon.out by default), created by programs compiled with the
  -pg option with the cc driver	command. The -pg option	also links in ver-
  sions	of the libc and	libm library routines compiled for profiling when
  your program is linked by using the -non_shared option with the cc command.

  The gprof command fully profiles only	the non-shared or call-shared execut-
  able.

  To produce call graph	data, follow these steps:

   1.  Compile your program with the -pg option	to the cc command.

   2.  Execute the program to produce a	data file.

   3.  Run gprof on the	data file.

  The default "-graph" listing shows the functions sorted according to the
  time they represent, including the time of their call	graph descendants.
  Below	each function entry is shown its (direct) call graph children, and
  how their times are propagated to this function. A similar display above
  the function estimates how this function's time and the time of its descen-
  dants	may be propagated to its (direct) call graph parents, assuming that
  each call has	the same cost.	     Note that some procedures occur both as
  children of other procedures and as spontaneous procedures. A	procedure
  with one or more parents is never listed separately in the call graph
  display, even	if sometimes it	is spontaneously generated.  An	index of the
  procedures is	also printed.

  The default "-procedures" listing shows a flat profile similar to that pro-
  vided	by prof. This listing gives the	total execution	times and call counts
  for each of the functions in the program, sorted by decreasing time.

  To obtain call graph data on libraries, link your program by using the
  -non_shared option with the cc command. To disable profiling of a particu-
  lar library, use the -no_pg option when linking. For example,	to enable
  call graph profiling of your executable program, including library rou-
  tines, and then disable call graph profiling for a library called mylib,
  link your program by using the following command:

       % cc -non_shared	-pg myprog -no_pg -lmylib

  You can use environment variables to change the default profiling behavior.
  The variables	are PROFDIR and	PROFFLAGS. The general form for	setting	these
  variables is:

    +  For C shell: setenv varname "value"

    +  For Bourne shell: varname = "value"; export varname

    +  For Korn	shell: export varname =	value

  In the preceding example, varname can	be one of the following:

  PROFDIR
      This environment variable	causes PC-sampling data	files to be generated
      with unique names	in the directory you specify.

      You specify a directory path as the value	and your prof results are
      placed in	the file path/pid.progname where path is the pathname, pid is
      the process ID of	the executing program, and progname is the program
      name.

  PROFFLAGS
      This environment variable	can take any of	the following values:

	+  -threads causes a separate data file	to be generated	for each
	   thread. The name of the data	file takes the following form:

	   pid.sid.prog_name

	   The form of the filename resolves to	pid as the process ID of the
	   program, sid	as the sequence	number of the thread and prog_name as
	   the name of the program being profiled.

	+  -sigdump signal-name	automatically establishes monitor_signal(3)
	   as the signal handler for the named signal, and it causes
	   monitor_signal(3) to	zero the profile after it is written to	a
	   file. This allows a signal to be sent several times without the
	   successive profiles overlapping, if the file	is renamed. The
	   asynchronous	nature of a signal may cause small variations in the
	   profile. Unrecognized signal-names are ignored. The -threads
	   option is ignored if	combined with -sigdump.

	+  -dirname directory specifies	the directory path in which the	pro-
	   filing data file or files are created.

	+  -[no]pids [disables]	or enables the addition	of the process-id
	   number to the name of the profiling data file or files.

  You can use the PROFDIR and PROFFLAGS	environment variables together.	For
  more information, see	the Programmer's Guide.

  PC-Sampling Profiles with hiprof


  The profile data is taken from the specified call-graph profile_file,
  created by a program that has	been instrumented in the default manner	for
  the hiprof command. The profile can cover all	the libraries used by the
  threaded or non-threaded program, and	it can be displayed as the time	used
  by procedures, source	lines, or instructions.

  To produce and display PC-sampling data, see hiprof(1) for one-step profil-
  ing, or follow these steps:

   1.  Compile your program using the required -O and -g levels.

   2.  Use the hiprof command to instrument the	executable and any shared
       libraries the program uses:

       hiprof prog_name

       For a multi-threaded program, specify the -pthread option, or specify
       the -threads option to profile each thread separately (but note that
       many megabytes of memory	and disk space may be used as a	result).  The
       instrumented program is named prog_name.hiprof by default.

   3.  Run the instrumented program to produce the profile data	file(s),
       named prog_name.hiout by	default.

   4.  Run gprof on the	instrumented executable	(not the original):
	    % gprof -all -b -scaled prog_name.hiprof prog_name.hiout

       The default -graph and -procedures profile displays are the same	as
       for PC-Sampling with cc -pg, described previously.

       To display profiles of the CPU time used	by the most expensive source
       lines, use the -heavy option:
	    % gprof -all -b -scaled -heavy prog_name.hiprof prog_name.hiout

       To display profiles of the lines	or instructions	in particular pro-
       cedures,	specify	-lines or -asm and the procedures:
	    % gprof -all -lines	-asm -f	main prog_name.hiprof prog_name.hiout








  Event-Counting Profiles with hiprof


  The profile data is taken from the specified call-graph profile_file,
  created by programs that have	been instrumented with the -cycles or -faults
  option of the	hiprof command.

  To produce and display event-counting	data, see hiprof(1) for	one step pro-
  filing, or follow these steps:

   1.  Compile your program using the required -O and -g levels. For multi-
       threaded	programs you must use a	different profiling technique.

   2.  Use the hiprof command to instrument the	executable and any shared
       libraries the program uses:

       hiprof [-cycles|-faults]	prog_name

       Specify the -cycles option to count the number of machine cycles	used
       by each procedure. If instead you want the number of page faults	suf-
       fered by	each procedure,	specify	the -faults option. The	instrumented
       program is named	prog_name.hiprof, by default.

   3.  Run the instrumented program to produce the profile data	file, named
       prog_name.hiout,	by default:

       prog_name.hiprof	[arg...]

   4.  Run gprof on the	original executable and	one or more profile data
       files, specifying any required options other than -E and	-F, which are
       not meaningful with hiprof's event-counting call	data:

       gprof [options] program program*.hiout

  The gprof command produces a report with the following sections:

    +  A call-graph profile, showing the procedures that call each procedure
       and the procedures it calls, including the number of calls and
       instructions, seconds, or page-faults involved in them.	The costs of
       the calls printed in this report	are individually measured, rather
       than being statistically	estimated like in reports based	on PC-
       sampling	data.

    +  A flat profile showing the instructions,	seconds, or page-faults	asso-
       ciated with each	procedure.

    +  An index	of procedures sorted by	name, including	object,	source file,
       and line	number if -numbers is specified.

  The hiprof data files	profile	the executable and all the shared libraries
  used by a call-shared	program. By default, gprof prints call-graph and flat
  profile entries only for the procedures in the executable, though the
  number and cost of calls to shared library procedures	are printed in the
  call-graph. Specify the -incobj or -all options to see entries for pro-
  cedures in some or all of the	shared libraries.

NOTES

   1.  Be aware	of possible quantization errors	when using gprof with PC-
       sampling	profile	data files. The	granularity of the sampling is shown,
       but remains statistical at best.	The time for each execution of a
       function	can be expressed by the	total time for the function divided
       by the number of	times the function is called; thus, the	time pro-
       pagated along the call graph arcs to parents of that function is
       directly	proportional to	the number of times that arc is	traversed.

   2.  Parents that are	not themselves profiled	have the time of their pro-
       filed children propagated to them, but appear to	be spontaneously
       invoked in the call graph listing; they do not have their time pro-
       pagated further.

   3.  Similarly, signal catchers, even	though profiled, appear	to be spon-
       taneous.	 Any profiled children of signal catchers should have their
       times propagated	properly, unless the signal catcher was	invoked	dur-
       ing the execution of the	profiling routine, in which case propagation
       cannot occur.

   4.  The profiled program must call exit or return normally for the profil-
       ing information to be saved in the gmon.out file, unless	-sigdump and
       kill are	used to	save the profile early.

   5.  A threaded program that is linked -non_shared will appear to spend a
       large proportion	of its time in pthread_mutex_unlock,
       pthread_mutex_lock, pthread_getspecific,	and other threads-related
       procedures that have no calls recorded, when using PC-sampling data.
       While the application code may be using these routines, much or all of
       the reported time is actually used by the profile data collection
       library's use of	them, so it can	usually	be ignored.

ERRORS

  If a PC-sampling program makes more procedure	calls than can be recorded,
  the error "Arc limit exceeded" will occur.  The program will continue	to
  execute to completion, but some call-arc information will be lost. A possi-
  ble work-around for this problem is to reduce	the portion of the program
  that is profiled using the monstartup() routine. See monitor(3) for more
  information.

FILES

  a.out
      Default object file

  gmon.out
      Default (PC-sampling) call graph and profile

  gmon.sum
      Default summarized dynamic call graph and	profile

  program[.pid][.thread].hiout
      Profiling	data file produced by hiprof-generated program

SEE ALSO

  Introduction:	prof_intro(1)

  Commands:  prof(1), hiprof(1), dxprof(1).  (dxprof(1)	is available as	an
  option.)

  Functions:  profil(2), monitor(3)

  Programmer's Guide

  gprof: A Call	Graph Execution	Profiler, by Graham, S.L., Kessler, P.B.,
  McKusick, M.K.

  Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN
  Notices, Vol.	17, No.	6, pp. 120-126,	June 1982.