Setting Up
Defines | |
#define | AOP_I_AM_GPL_COMPATIBLE() __attribute__((visibility("default"))) int plugin_is_GPL_compatible; |
Client plug-in must use this macro to indicate that it is GPLv3 compatible. | |
#define | AOP_MAIN_PROTO __attribute__((visibility("hidden"))) void |
A macro for easily declaring a plug-in's main function. | |
#define | aop_assert(EXPR) ((void)(!(EXPR) ? aop_abort (__FILE__, __LINE__, __FUNCTION__), 0 : 0)) |
A convenient interface to GCC's assertion facility. | |
Typedefs | |
typedef unsigned int(* | pass_callback )() |
Type for plug-in pass functions. | |
Functions | |
const char * | aop_get_arg_value (const char *key) |
void | aop_register_pass (const char *pass_name, pass_callback callback) |
void | aop_main () |
void | aop_finish () |
Define Documentation
#define aop_assert | ( | EXPR | ) | ((void)(!(EXPR) ? aop_abort (__FILE__, __LINE__, __FUNCTION__), 0 : 0)) |
A convenient interface to GCC's assertion facility.
If EXPR evaluates to false, GCC will abort compilation and show an error with the file and line number of the failed assertion.
- Examples:
- fclose_tracecut.c.
#define AOP_I_AM_GPL_COMPATIBLE | ( | ) | __attribute__((visibility("default"))) int plugin_is_GPL_compatible; |
Client plug-in must use this macro to indicate that it is GPLv3 compatible.
GCC will refuse to execute plug-ins that do not declare themselves as GPL compatible. Call this macro at the top level of any one source file in a plug-in to declare the plug-in as GPL compatible.
By using this macro, you state that, if you distribute your plug-in, you will not distribute it under any terms that are incompatible with the GPL. This is a requirement of the GCC license. Contact the Free Software Foundation for more information. (The InterAspect team is not affiliated with the Free Software Foundation.)
- Examples:
- advice_header.c, duplicate.c, fclose_tracecut.c, and hello.c.
#define AOP_MAIN_PROTO __attribute__((visibility("hidden"))) void |
A macro for easily declaring a plug-in's main function.
Define aop_main using the AOP_MAIN_PROTO macro to ensure that its linker visibility is set correctly. Absolutely do not just declare it as a void function!
For example:
AOP_PROTO_MAIN aop_main(void)
- Examples:
- advice_header.c, duplicate.c, fclose_tracecut.c, and hello.c.
Typedef Documentation
typedef unsigned int(* pass_callback)() |
Type for plug-in pass functions.
The function type for pass functions to be registered with aop_register_pass().
Function Documentation
void aop_finish | ( | ) |
InterAspect calls this function after all compilation is finished and before GCC and InterAspect data structures are destroyed. It is provided so that InterAspect plug-ins can override it (by providing their own version), giving them a last chance to clean up data structures or free up other resources.
The best place to output an automatic header (using aop_write_c_header()) is in aop_finish().
- Examples:
- advice_header.c, and fclose_tracecut.c.
const char* aop_get_arg_value | ( | const char * | key | ) |
Find the value for a command-line argument passed to the plug-in. You can pass a key/value argument to your plug-in on the GCC command line like this:
-fplugin-arg-${BASENAME}-${KEY}=${VALUE}
where ${BASENAME} is the base name of your plug-in, which GCC determines from the plug-in's file name. If your plug-in is named libfoo.so
, its basename will be libfoo
.
If you want to be able to pass arguments to your plug-in, the plug-in's file name must not have any hyphens. This is a restriction of GCC.
- Parameters:
-
key The argument key.
- Returns:
- If the user passed an argument with the specified key to this plug-in, aop_get_arg_value() returns the associated value. Otherwise, it returns NULL. If the user passed multiple arguments with the specified key, aop_get_arg_value() returns the value that was last on the command line.
void aop_main | ( | ) |
The aop_main() function is the only function that a client plug-in must define in order to link with InterAspect. InterAspect will call aop_main() right at the beginning of compilation, giving it the opportunity to register a pass using aop_register_pass().
Make sure to define your aop_main() using the AOP_MAIN_PROTO() macro.
- Examples:
- advice_header.c, duplicate.c, fclose_tracecut.c, and hello.c.
void aop_register_pass | ( | const char * | pass_name, | |
pass_callback | callback | |||
) |
Register an instrumentation pass with GCC. Most InterAspect-based plug-ins will call this function once (from aop_main()) to register the a pass that will do all the instrumentation work.
In GCC, a pass is a function that gets called once for each compiled function in the target program. Each time the pass function executes, it directly modifies the current function.
Passes added with aop_register_pass() will be executed in the order they are added.
- Parameters:
-
pass_name A name for the pass. callback The pass function to register.
- Examples:
- advice_header.c, duplicate.c, and hello.c.
