gprof Command

Purpose

Displays call graph profile data.

Syntax

/usr/ucb/gprof [ .-b ] [ -e Name ] [ -E Name ] [ -f Name ] [ -F Name ] [ -L PathName ] [ -s ] [ -z ] [ a.out [ gmon.out ... ] ]

Description

The gprof command produces an execution profile of C, Pascal, FORTRAN, or COBOL programs. The effect of called routines is incorporated into the profile of each caller. The gprof command is useful in identifying how a program consumes CPU resource. To find out which functions (routines) in the program are using the CPU, you can profile the program with the gprof command.

The profile data is taken from the call graph profile file (gmon.out by default) created by programs compiled with the cc command using the -pg option. The -pg option also links in versions of library routines compiled for profiling, and reads the symbol table in the named object file (a.out by default), correlating it with the call graph profile file. If more than one profile file is specified, the gprof command output shows the sum of the profile information in the given profile files.

The -pg option causes the compiler to insert a call to the mcount subroutine into the object code generated for each recompiled function of your program. During program execution, each time a parent calls a child function the child calls the mcount subroutine to increment a distinct counter for that parent-child pair. Programs not recompiled with the -pg option do not have the mcount subroutine inserted, and therefore keep no record of who called them.

Note: Symbols from C++ object files have their names demangled before they are used.

The gprof command produces three items:

1. First, a flat profile is produced similar to that provided by the prof command. This listing gives total execution times and call counts for each of the functions in the program, sorted by decreasing time. The times are then propagated along the edges of the call graph. Cycles are discovered, and calls into a cycle are made to share the time of the cycle.
2. A second listing shows the functions sorted according to the time they represent, including the time of their call-graph descendents. Below each function entry are its (direct) call-graph children, with an indication of how their times are propagated to this function. A similar display above the function shows how the time of the function and the time of its descendents are propagated to its (direct) call-graph parents.
3. Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and their contributions to the time and call counts of the cycle.

Profiling with the fork and exec Subroutines

Profiling using the gprof command is problematic if your program runs the fork or exec subroutine on multiple, concurrent processes. Profiling is an attribute of the environment of each process, so if you are profiling a process that forks a new process, the child is also profiled. However, both processes write a gmon.out file in the directory from which you run the parent process, overwriting one of them. The tprof command is recommended for multiple-process profiling.

If you must use the gprof command, one way around this problem is to call the chdir subroutine to change the current directory of the child process. Then, when the child process exits, its gmon.out file is written to the new directory. The following example demonstrates this method:

cd /u/test   # current directory containing forker.c program
pg forker.c
main()
{
int i, pid;
static char path[]="/u/test2";
pid=fork();             /* fork a child process */
if(pid==0) {            /* Ok, this is the child process */
   chdir (path);        /* create new home directory so
                           gmon.out isn't clobbered! */
   for (i=0; i<30000; i++) sub2();  /* 30000 calls to sub2
                                       in child profile */
   }
else                   /* Parent process... leave gmon.out
                          in current directory */
   for (i=0;i<1000; i++) sub1(pid);   /* 1000 calls to sub1
                                         in parent profile */
}
int sub1(pid)   /* silly little function #1, called
                   by parent 1000 times */
int pid;
{
int i;
printf("I'm the parent, child pid is %i.\n",pid);
}
int sub2()     /* silly little function #2, called
                  by child 30,000 times */
{
printf("I'm the child.\n");
}
cc -pg forker.c -o forker   # compile the program
mkdir /u/test2              # create a directory for childi
                              to write gmon.out in
forker >/dev/null           # Throw away forker's many,
                              useless output lines
gprof forker   >parent.out  # Parent process's gmon.out is 
                              in current directory
gprof forker ../test2/gmon.out >child.out
                            # Child's gmon.out is in test2
                              directory

At this point, if you compare the two gprof command output listings in directory test, parent.out, and child.out, you see that the sub1 subroutine is called 1,000 times in the parent and 0 times in the child, while the sub2 subroutine is called 30,000 times in the child and 0 times in the parent.

Processes that run the exec subroutine do not inherit profiling. However, the program executed by the exec subroutine should be profiled if it was compiled with the -pg option. As with the preceding forker.c example, if both the parent and the program run by the exec subroutine program are profiled, one overwrites the other's gmon.out file unless you use the chdir subroutine in one of them.

Profiling without Source Code

If you do not have source for your program, you can profile using the gprof command without recompiling. You must, however, be able to relink your program modules with the appropriate compiler command (for example, cc for C). If you do not recompile, you do not get call frequency counts, although the flat profile is still useful without them. As an added benefit, your program runs almost as fast as it usually does. The following explains how to profile:

cc -c dhry.c         # Create dhry.o without call counting code.
cc -pg dhry.o -L/lib -L/usr/lib -o dhryfast
                     # Re-link (and avoid -pg libraries).
dhryfast             # Create gmon.out without call counts.
gprof >dhryfast.out  # You get an error message about no call counts
                     #  -- ignore it.

A result of running without call counts is that some quickly executing functions (which you know had to be called) do not appear in the listing at all. Although nonintuitive, this result is normal for the gprof command. The gprof command lists only functions that were either called at least once, or which registered at least one clock tick. Even though they ran, quickly executing functions often receive no clock ticks. Since call-counting was suspended, these small functions are not listed at all. (You can get call counts for the runtime routines by omitting the -L options on the cc -pg command line.)

Using Less Real Memory

Profiling with the gprof command can cause programs to page excessively since the -pg option dedicates pinned real-memory buffer space equal to one-half the size of your program's text. Excessive paging does not affect the data generated by profiling, since profiled programs do not generate ticks when waiting on I/O, only when using the CPU. If the time delay caused by excessive paging is unacceptable, we recommend using the tprof command.

Flags

Examples

1. To obtain profiled output, enter:

   gprof

2. To get profiling output from a command run earlier and possibly moved, enter:

   gprof -L/home/score/lib runfile runfile.gmon

   This example uses the given runfile.gmon file for sample data and the runfile file for local symbols, and checks the /u/score/lib file for loadable objects.
3. To profile the sample program dhry.c:
   1. Recompile the application program with the cc -pg command, as follows:

      cc -pg dhry.c -o dhry # Re-compile to produce gprof output.

   2. Run the recompiled program. A file named gmon.out is created in the current working directory (not the directory in which the program executable resides).

      dhry    # Execute program to generate ./gmon.out file.

   3. Run the gprof command in the directory with the gmon.out file to produce the CALL-GRAPH and FLAT PROFILE reports.

      gprof >gprof.out     # Name the report whatever you like
      vi gprof.out         # Read flat profile first.

Throughout this description of the gprof command, most of the examples use the C program dhry.c. However, the discussion and examples apply equally to FORTRAN, Pascal, or COBOL modules by substituting the appropriate compiler name in place of the C compiler, cc, and the word subroutine for the word function. For example, the following AIX commands show how to profile a FORTRAN program named matrix.f:

xlf -pg matrix.f -o matrix # FORTRAN compile of matrix.f program
matrix                    # Execute with gprof profiling,
                          #   generating gmon.out file
gprof > matrix.out        # Generate profile reports in
                          #   matrix.out from gmon.out
vi matrix.out             # Read flat profile first.

Files

Related Information

The cc command, prof command.

The exit subroutine, monitor subroutine, profil subroutine.

AIX Performance Monitoring and Tuning Commands in the AIX Versions 3.2 and 4 Performance Tuning Guide.

The Commands Overview in AIX Version 4.3 System User's Guide: Operating System and Devices.

The Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.