GPROF(1)

✨ GPROF(1) ✨ GNU 💖

🫶 NAME 🫶

okay so the name is just gprof, and it's all about displaying call graph profile data 📊✨

🌸 SYNOPSIS 🌸

okay bestie, here's the whole big list of ways you can call it 👀

gprof [ -[abcDhilLrsTvwxyz] ] [ -[ABCeEfFJnNOpPqQRStZ][name] ]
 [ -I dirs ] [ -d[num] ] [ -k from/to ]
 [ -m min-count ] [ -R map_file ] [ -t table-length ]
 [ --[no-]annotated-source[=name] ]
 [ --[no-]exec-counts[=name] ]
 [ --[no-]flat-profile[=name] ] [ --[no-]graph[=name] ]
 [ --[no-]time=name] [ --all-lines ] [ --brief ]
 [ --debug[=level] ] [ --function-ordering ]
 [ --file-ordering map_file ] [ --directory-path=dirs ]
 [ --display-unused-functions ] [ --file-format=name ]
 [ --file-info ] [ --help ] [ --line ] [ --inline-file-names ]
 [ --min-count=n ] [ --no-static ] [ --print-path ]
 [ --separate-files ] [ --static-call-graph ] [ --sum ]
 [ --table-length=len ] [ --traditional ] [ --version ]
 [ --width=n ] [ --ignore-non-functions ]
 [ --demangle[=STYLE] ] [ --no-demangle ]
 [--external-symbol-table=name]
 [ image-file ] [ profile-file ... ]

🦋 DESCRIPTION 🦋

okay so gprof is literally the tool that makes a execution profile for C, Pascal, or Fortran77 programs 💅 it's giving performance detective 🔍 every routine's cost gets folded into the profile of whoever called it, so nothing gets left out 🌈

the profile data comes from the call graph profile file (gmon.out is the default) 📁 that file gets created by programs compiled with the -pg option of cc, pc, and f77. the -pg option also links in versions of the library routines that were compiled for profiling, so the library stuff shows up too ✨

then gprof reads the given object file (the default is a.out) and matches up its symbol table with the call graph profile from gmon.out 🧩 and if you give it more than one profile file, the output shows the sum of the profile info from all of them. main character energy, collecting all the receipts 🧾💜

⚠️ bestie, real talk: if you compile your binaries with gcc 2.95.x or 3.0, you may need to add the -fprofile-arcs to the compile command line so the call graphs actually get stored properly in gmon.out. otherwise the data can be incomplete, and nobody wants that 😭

okay now the math part 🤓 gprof works out how much time gets spent in each routine. next, those times get propagated along the edges of the call graph. cycles get discovered, and any calls into a cycle end up sharing the time of that cycle. it's like the whole thing is passing the tea around 🍵

there are a few different outputs you can get from the analysis:

• the flat profile 📋 shows how much time your program spent in each function, and how many times that function got called. if you just want to know which functions are burning the most cycles, this is the one, and it says it concisely 💅
• the call graph 🕸️ shows, for each function, which functions called it, which other functions it called, and how many times. it also estimates how much time got spent in the subroutines of each function. this is where you can spot calls that use a lot of time and think about getting rid of them 👀
• the annotated source listing 📝 is a copy of your program's source code, labeled with the number of times each line was executed. so cute, you can see exactly which lines are the hot ones 🔥

🎀 OPTIONS 🎀

these options decide which of the several output formats gprof should produce 💖

a lot of these options can take an optional symspec to pick which functions get included or excluded 🎯 and you can repeat these options with different symspecs to include or exclude whole sets of symbols. it's giving customisable 💅

heads up: if you specify any of these options, it overrides the default (-p -q), which would normally print a flat profile and call graph analysis for all functions. so you're basically taking the wheel 🚗✨

• -A[symspec], --annotated-source[=symspec] — this one makes gprof print annotated source code 📝 if you give it a symspec, it only prints output for the matching symbols 🎯
• -b, --brief — with this, gprof skips the verbose blurbs that explain what all the fields in the tables mean 🙈 super useful if you're printing the output or you're just tired of seeing those blurbs
• -B — this makes gprof print the call graph analysis 🕸️
• -C[symspec], --exec-counts[=symspec] — this prints a tally of functions and how many times each one was called 🧮 if you add a symspec, the tally only shows the matching symbols 🎯

if your profile data file has basic-block count records, then pairing -l with -C makes it tally and display the basic-block execution counts too 🤓

• -i, --file-info — this shows summary info about the profile data file(s) and then exits 👋 you get the number of histogram, call graph, and basic-block count records 📊
• -I dirs, --directory-path=dirs — this gives a list of search directories where gprof can find source files 📂 you can also use the environment variable GPROF_PATH to pass that same info along 🧚 it's mostly used for annotated source output
• -J[symspec], --no-annotated-source[=symspec] — the opposite energy 🙅‍♀️ this makes gprof not print annotated source code. if you add a symspec, gprof still prints annotated source, but leaves out the matching symbols 🫠
• -L, --print-path — normally the source filenames get printed with the path part hidden 🙈 with -L, you get the full pathname instead 🗺️ it comes from the symbolic debugging info in the image file and is relative to the directory where the compiler was invoked
• -p[symspec], --flat-profile[=symspec] — this makes gprof print a flat profile 📋 with a symspec, you only get a flat profile for the matching symbols 🎯
• -P[symspec], --no-flat-profile[=symspec] — this one suppresses the flat profile 🚫 if you add a symspec, gprof prints a flat profile but excludes the matching symbols 💅
• -q[symspec], --graph[=symspec] — this makes gprof print the call graph analysis 🕸️ with a symspec, you only get the call graph for matching symbols and their children 👶
• -Q[symspec], --no-graph[=symspec] — this suppresses the call graph 🚫 with a symspec, gprof prints a call graph but excludes the matching symbols 🙃
• -t, --table-length=num — this lists the num most active source lines in each source file when source annotation is turned on 🔥 the default is 10 🔟
• -y, --separate-files — this one only affects annotated source output 📝 normally gprof prints annotated source files to standard-output. with this option, the annotated source for a file named path/filename gets generated in the file filename-ann 📁

⚠️ if the underlying file system would truncate filename-ann so it overwrites the original filename, gprof writes the annotated source to filename.ann instead. if the original file name has an extension, that extension gets replaced with .ann 😬

• -Z[symspec], --no-exec-counts[=symspec] — this stops gprof from printing the tally of functions and how many times each was called 🙅 with a symspec, the tally still prints, but the matching symbols get excluded 🫶
• -r, --function-ordering — this makes gprof print a suggested function ordering for your program, based on the profiling data 🧠 the ordering may improve paging, tlb and cache behavior, but only on systems that support arbitrary ordering of functions in an executable 🚀

the exact details of how to force the linker to place functions in a particular order are system dependent and out of scope for this manual 🙈

• -R map_file, --file-ordering map_file — this prints a suggested .o link line ordering for your program, based on profiling data 🧩 it can help paging, tlb and cache behavior on systems that don't support arbitrary ordering of functions in an executable 🌈

bestie, it's highly recommended to use the -a argument with this option 💜

the map_file is a pathname to a file that maps function names to object files 🗺️ the format is similar to the output of the program nm, kinda like this:

c-parse.o:00000000 T yyparse
c-parse.o:00000004 C yyerrflag
c-lang.o:00000000 T maybe_objc_method_name
c-lang.o:00000000 T print_lang_statistics
c-lang.o:00000000 T recognize_objc_keyword
c-decl.o:00000000 T print_lang_identifier
c-decl.o:00000000 T print_lang_type
...

to make a map_file with GNU nm, type a command like nm --extern-only --defined-only -v --print-file-name program-name 💻✨

• -T, --traditional — this makes gprof print its output in "traditional" BSD style 🎀
• -w width, --width=width — this sets the width of the output lines to width 📏 right now it's only used when printing the function index at the bottom of the call graph 🦋
• -x, --all-lines — another annotated-source-only option 📝 by default, only the lines at the beginning of a basic-block get annotated. with this one, every line in a basic-block gets annotated by repeating the annotation for the first line 🔁 it works kinda like tcov's -a 🤓
• --demangle[=style], --no-demangle — these control whether C++ symbol names get demangled when printing output 💅 the default is to demangle symbols, and --no-demangle turns that off. different compilers have different mangling styles, so the optional style argument lets you pick the one that matches your compiler 🌸

🌷 Analysis Options 🌷

• -a, --no-static — this stops gprof from printing statically declared (private) functions 🫥 these are the functions whose names aren't listed as global, and which aren't visible outside the file, function, or block where they were defined. the time spent in these functions, and the calls to and from them, all get attributed to the function that was loaded directly before it in the executable file 🧾 this option affects both the flat profile and the call graph 💖

to be continued in part 2, bestie 🌈✨

• -c, --static-call-graph — okay so this one is a sneaky little heuristic 🕵️‍♀️. It pokes around the text space of the object file and spots function calls in the binary machine code. Normal call graph records only show up when a function actually gets entered, so this option finds children that could have been called but never were. Calls to functions that weren't compiled with profiling enabled get caught too, but only if they have symbol table entries. Calls into dynamic library routines are usually invisible to it 🙈. Parents or children found this way show up in the call graph with a call count of 0 💅.
• -D, --ignore-non-functions — this one tells gprof to ignore any symbols that aren't known to be functions 🧹. On systems that support it (Solaris and HPUX, for example), you get more accurate profile data ✨.
• -k from/to — lets you delete arcs from the call graph. Any arc going from symbols matching symspec from to symbols matching symspec to gets yeeted 🗑️.
• -l, --line — turns on line-by-line profiling 📏, so histogram hits get charged to individual source lines instead of whole functions. Heads up: this only works with programs compiled by older versions of the gcc compiler. Newer gcc versions are built to work with the gcov tool instead 🙅‍♀️. If the program was compiled with basic-block counting enabled, this option also tells you how many times each line ran 🔢. It's super helpful for finding where inside a huge function the time is going, but ngl it makes gprof way slower and makes statistical inaccuracies louder 😭.
• --inline-file-names — prints the source file after each symbol in both the flat profile and the call graph 📁. If you pair it with the -L option, you get the full path to the file 🛤️.
• -m num, --min-count=num — only affects execution count output 🔢. Symbols executed fewer than num times get hidden. Bye, low-key functions 👋.
• -nsymspec, --time=symspec — the -n option makes gprof, during its call graph analysis, only propagate times for symbols matching symspec 🎯.
• -Nsymspec, --no-time=symspec — the -n option makes gprof, during its call graph analysis, not propagate times for symbols matching symspec 🚫.
• -Sfilename, --external-symbol-table=filename — tells gprof to read an external symbol table file, like /proc/kallsyms, instead of reading the symbol table from the object file (the default is a.out) 🧚. This is the move for profiling kernel modules 🔥.
• -z, --display-unused-functions — with this on, gprof lists every function in the flat profile, even ones that were never called and didn't spend any time 🦋. It pairs beautifully with the -c option if you want to find routines that never got called 🕵️‍♀️.

✨ Miscellaneous Options ✨

• -d[num], --debug[=num] — sets debugging options 🐛. If you don't give a num, you get all debugging turned on 🌈.
• -h, --help — prints the command line usage 🆘.
• -Oname, --file-format=name — picks the format of the profile data files 📂. The recognized formats are auto (the default), bsd, 4.4bsd, magic, and prof (not yet supported) 🙃.
• -s, --sum — gprof summarizes the info from all the profile data files it read and writes it into a new file called gmon.sum 🧁. That file holds everything from the input files. Fun twist: gmon.sum can be one of the input files too, which merges the data from the other inputs into it 🫶.

Later on, you can run gprof again without -s to analyze the cumulative data stored in gmon.sum 📊.

• -v, --version — prints the current version number and then exits 🔢.

🙅‍♀️ Deprecated Options 🙅‍♀️

These options have been replaced with newer versions that use symspecs. Use the newer stuff, bestie 💖.

• -e function_name — tells gprof to skip printing info about function_name (and its children...) in the call graph 👻. The function still shows up as a child of any functions that call it, but its index number displays as [not printed]. You can give more than one -e option, but each one only takes a single function_name.
• -E function_name — works like -e, but the time spent in the function (and any children who weren't called from anywhere else) won't count toward the percentages-of-time in the call graph 🧮. Again, you can use more than one -E, with one function_name each.
• -f function_name — limits the call graph to function_name and its children (and their children...) 🔍. Multiple -f options are allowed, one function_name per option.
• -F function_name — works like -f, but only the time spent in the function and its children (and their children...) gets used for total-time and percentages-of-time in the call graph ⏱️. Multiple -F options are allowed, one function_name each. The -F option overrides the -E option 👑.

---

📁 FILES 📁

• a.out — the namelist and text space 🧾.
• gmon.out — dynamic call graph and profile 📈.
• gmon.sum — summarized dynamic call graph and profile 🧁.

🐛 BUGS 🐛

The granularity of the sampling is shown, but it stays statistical at best 🎲. We assume the time for each execution of a function can be expressed as the total time for the function divided by the number of times it's called. So the time propagated along the call graph arcs to a function's parents is directly proportional to how many times that arc gets traversed 🔁.

Parents that aren't profiled themselves will have the time of their profiled children propagated to them. They'll look like they were spontaneously invoked in the call graph listing, and their time won't be propagated any further 👀. Signal catchers are similar: even when profiled, they appear spontaneous (for more obscure reasons 🌀). Any profiled children of signal catchers should still get their times propagated properly, unless the signal catcher was invoked during the execution of the profiling routine. In that case, all is lost 💀.

The profiled program must call exit(2) or return normally for the profiling information to be saved in the gmon.out file. No exit, no data, no cap 😭.

🔗 SEE ALSO 🔗

cc(1), prof(1), and the Info entry for gprof 📚.

"An Execution Profiler for Modular Programs", by S. Graham, P. Kessler, M. McKusick; Software - Practice and Experience, Vol. 13, pp. 671-685, 1983 🧐.

"gprof: A Call Graph Execution Profiler", by S. Graham, P. Kessler, M. McKusick; Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982 🍓.

⚖️ COPYRIGHT ⚖️

Copyright (c) 1988-2025 Free Software Foundation, Inc. 💜

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License" 📜.

---

That's the whole tea, bestie! 🌈 This page belongs to binutils 2.45 and was last updated on 2025-12-03, so go profile something iconic and send me the call graph 💖✨🫶