@@ -933,6 +933,92 @@ the file doesn't match the executable (differing number of basic block
counts) it will ignore the contents of the file. It then adds in the
new execution counts and finally writes the data to the file.
+You can report on a subset of functions by using @option{--include}
+and @option{--exclude}. This is very useful when combined with
+@option{--stdout} trying to understand behavior and coverage for a
+particular function by running a test, looking at @command{gcov}
+output, testing another input, and running @command{gcov} again.
+
+@smallexample
+$ gcov -m --stdout --include inc tmp
+ -: 0:Source:tmp.cpp
+ -: 0:Graph:tmp.gcno
+ -: 0:Data:tmp.gcda
+ -: 0:Runs:1
+ 2*: 8: void inc () @{ b++; @}
+------------------
+Foo<char>::inc():
+ #####: 8: void inc () @{ b++; @}
+------------------
+Foo<int>::inc():
+ 2: 8: void inc () @{ b++; @}
+------------------
+@end smallexample
+
+@command{gcov} will match on mangled names by default, which you can
+control with the @option{-M} flag. Note that matching and reporting
+are independent, so you can match on mangled names while printing
+demangled names, and vice versa. To report on the @code{int}
+instantiation of @code{Foo} matching on mangled and demangled names:
+
+@smallexample
+$ gcov -t -m -M tmp --include 'Foo<int>'
+ -: 0:Source:tmp.cpp
+ -: 0:Graph:tmp.gcno
+ -: 0:Data:tmp.gcda
+ -: 0:Runs:1
+ 1: 7: Foo(): b (1000) @{@}
+ 2: 8: void inc () @{ b++; @}
+@end smallexample
+
+@smallexample
+$ gcov -t -m tmp --include 'FooIi'
+ -: 0:Source:tmp.cpp
+ -: 0:Graph:tmp.gcno
+ -: 0:Data:tmp.gcda
+ -: 0:Runs:1
+ 1: 7: Foo(): b (1000) @{@}
+ 2: 8: void inc () @{ b++; @}
+@end smallexample
+
+The arguments to @option{--include} and @option{--exclude} are
+extended regular expressions (like @command{grep -E}), so the pattern
+@code{in.?} matches both @code{inc} and @code{main}. If used with
+@option{-M} then all @code{int} instantiations of @code{Foo} would
+match too. @option{--include} and @option{--exclude} can be used
+multiple times, and if a name matches multiple filters it is the last
+one to match which takes preference. For example, to match
+@code{main} and the @code{int} instatiation of @code{inc}, while
+omitting the @code{Foo} constructor:
+
+@smallexample
+$ gcov -t -m -M --include in --exclude Foo --include '<int>::inc' tmp
+ -: 0:Source:tmp.cpp
+ -: 0:Graph:tmp.gcno
+ -: 0:Data:tmp.gcda
+ -: 0:Runs:1
+ 2: 8: void inc () @{ b++; @}
+ 1: 18:main (void)
+ -: 19:@{
+ -: 20: int i, total;
+ 1: 21: Foo<int> counter;
+ -: 22:
+ 1: 23: counter.inc();
+ 1: 24: counter.inc();
+ 1: 25: total = 0;
+ -: 26:
+ 11: 27: for (i = 0; i < 10; i++)
+ 10: 28: total += i;
+ -: 29:
+ 1*: 30: int v = total > 100 ? 1 : 2;
+ -: 31:
+ 1: 32: if (total != 45)
+ #####: 33: printf ("Failure\n");
+ -: 34: else
+ 1: 35: printf ("Success\n");
+ 1: 36: return 0;
+@end smallexample
+
@node Gcov and Optimization
@section Using @command{gcov} with GCC Optimization