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.