-qfunctrace

Pragma equivalent

None.

Purpose

Calls the tracing routines to trace the entry and exit points of the specified functions in a compilation unit.

Syntax


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


Pragma syntax

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

Defaults

-qnofunctrace

Parameters

+: Instructs the compiler to trace function_name and all its internal functions.
-: Instructs the compiler not to trace function_name or any of its internal functions.
function_name: Indicates the named functions 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.

This option inserts calls to the tracing functions that you have defined. These functions must be provided at the link step. For details about the interface of tracing functions, as well as when they are called, see the Tracing functions in your code section in the XL C Optimization and Programming Guide.

Use + or - to indicate the function 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.

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.

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 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 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+std::vector traces all instantiations of std::vector.

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 Optimization and Programming Guide.