-qfunctrace

Pragma equivalent

None.

Purpose

Calls to the tracing routine that traces the entry and exit points of functions in a compilation unit, or only a specific list of functions.

Syntax


   .--- -qnofunctrace-------------------------------------.   
>>-+--- -qfunctrace----+--------------------------------+-+----><
                       |          .-:-----------------. |     
                       |          V                   | |     
                       '-+- + -+----+-function_name-+-+-'     
                         '- - -'    +-classname-----+         
                                    '-namespace-----'


Pragma syntax

                              .-,-----------------.      
                              V                   |      
>>-#--pragma--nofunctrace--(------function_name---+--)---------><

Defaults

-qnofunctrace

-qfunctrace-std

Parameters

+: Instructs the compiler to trace function_name, classes, or namespace, and all its internal functions.
-: Instructs the compiler not to trace function_name, classes, or namespace, or any of its internal functions.
function_name: Indicates the named functions to be traced.
classname: Indicates the named class to be traced.
namespace: Indicates the namespace to be traced.

Usage

-qfunctrace enables tracing for all functions in your program. -qnofunctrace disables tracing that was enabled by -qfunctrace.

The -qfunctrace+ and -qfunctrace- suboptions enable tracing for a specific list of functions and are not affected by -qnofunctrace. The list of functions is cumulative.

Use + or - to indicate the function , classname, or namespace to be traced by the compiler. For example, if you want to trace function x, use -qfunctrace+x. To trace a list of functions, you must use a colon : to separate them.

Two colons in a row :: is a scope qualifier, you can use it to indicate C++ qualified names. For example, use -qfunctrace+A::B:C traces functions that begin with qualifiers A::B or C.

If you want to trace functions in your code, you can write tracing functions in your code by using the following C function prototypes:

Use void __func_trace_enter(const char *const function_name, const char *const file_name, int line_number, void **const user_data); to define the entry point tracing routine.
Use void __func_trace_exit(const char *const function_name, const char *const file_name, int line_number, void **const user_data); to define the exit point tracing routine.
Use void __func_trace_catch(const char *const function_name, const char *const file_name, int line_number, void **const user_data); to define the catch tracing routine.

You must define your functions when you write the preceding function prototypes in your code.

For details about the these function prototypes as well as when they are called, see the Tracing functions in your code section in the XL C/C++ Optimization and Programming Guide.

Note:

You can only use + and - one at a time. Do not use both of them together in the same -qfunctrace invocation.
Definition of an inline function is traced. It is only the calls that have been inlined are not traced.

Predefined macros

None.

Examples

To trace functions x, y, and z, use -qfunctrace+x:y:z.

To trace all functions, except for x, use -qfunctrace -qfunctrace-x.

The -qfunctrace+ and -qfunctrace- suboptions only enable or disable tracing on the given list of cumulative functions. When functions, classes, and namespaces are used, the most completely specified option is in effect. The following is a list of examples:

-qfunctrace+x -qfunctrace+y or -qfunctrace+x -qnofunctrace -qfunctrace+y enables tracing for only x and y.
-qfunctrace-x -qfunctrace or -qfunctrace -qfunctrace-x traces all functions in the compilation unit except for x.
-qfunctrace -qfunctrace+x traces all functions.
-qfunctrace+y -qnofunctrace traces y only.
-qfunctrace-functionX -qfunctrace+classX or -qfunctrace+classX -qfunctrace-functionX (functionX is a member function of classX) traces all member functions of classX but not functionX. This is because in this example the most completely specified option wins regardless of the order you specify the option.
-qfunctrace+MyClass traces all member functions in MyClass.
-qfunctrace+std::vector traces all instantiations of std::vector.
-qfunctrace+ABC -qfunctrace-ABC::foo traces all functions defined in namespace ABC except for foo.

Related information

For details about #pragma nofunctrace, see #pragma nofunctrace.
For detailed information about how to implement function tracing routines in your code, as well as detailed examples and a list of rules for using them, see Tracing functions in your code in the XL C/C++ Optimization and Programming Guide.