Macros to provide or require explicit symbols

Defines
#define	PROVIDE_SYMBOL(_sym)   char _sym[0]
	Provide a symbol within this object file.
#define	REQUIRE_SYMBOL(_sym)
	Require a symbol within this object file.
#define	REQUEST_SYMBOL(_sym)   __asm__ ( ".equ\t__need_" #_sym ", " #_sym )
	Request that a symbol be available at runtime.
#define	EXPORT_SYMBOL(_sym)   PROVIDE_SYMBOL ( __export_ ## _sym )
	Set up a symbol to be usable in another file by IMPORT_SYMBOL().
#define	IMPORT_SYMBOL(_sym, _decl)
	Make a symbol usable to this file if available at link time.

---

Define Documentation

#define PROVIDE_SYMBOL

(

_sym

)

char _sym[0]

Provide a symbol within this object file.

Definition at line 66 of file compiler.h.

#define REQUIRE_SYMBOL

(

_sym

)

Value:

extern char _sym;                               \
        static char * _C2 ( _C2 ( __require_, _sym ), _C2 ( _, __LINE__ ) ) \
                __attribute__ (( section ( ".discard" ), used )) \
                = &_sym

Require a symbol within this object file.

The symbol is referenced by a relocation in a discarded section, so if it is not available at link time the link will fail.

Definition at line 82 of file compiler.h.

#define REQUEST_SYMBOL

(

_sym

)

__asm__ ( ".equ\t__need_" #_sym ", " #_sym )

Request that a symbol be available at runtime.

The requested symbol is entered as undefined into the symbol table for this object, so the linker will pull in other object files as necessary to satisfy the reference. However, the undefined symbol is not referenced in any relocations, so the link can still succeed if no file contains it.

A symbol passed to this macro may not be referenced anywhere else in the file. If you want to do that, see IMPORT_SYMBOL().

Definition at line 104 of file compiler.h.

#define EXPORT_SYMBOL

(

_sym

)

PROVIDE_SYMBOL ( __export_ ## _sym )

Set up a symbol to be usable in another file by IMPORT_SYMBOL().

The symbol must already be marked as global.

Definition at line 112 of file compiler.h.

#define IMPORT_SYMBOL	(	_sym,
		_decl		)

Value:

REQUEST_SYMBOL ( __export_ ## _sym ) ;          \
        extern _decl __attribute__ (( weak ))

Make a symbol usable to this file if available at link time.

If no file passed to the linker contains the symbol, it will have NULL value to future uses. Keep in mind that the symbol value is really the address of a variable or function; see the code snippet below.

In C using IMPORT_SYMBOL, you must specify the declaration as the second argument, for instance

   IMPORT_SYMBOL ( my_func, int my_func ( int arg ) );
   IMPORT_SYMBOL ( my_var, int my_var );

   void use_imports ( void ) {
        if ( my_func && &my_var )
           my_var = my_func ( my_var );
   }

GCC considers a weak declaration to override a strong one no matter which comes first, so it is safe to include a header file declaring the imported symbol normally, but providing the declaration to IMPORT_SYMBOL is still required.

If no EXPORT_SYMBOL declaration exists for the imported symbol in another file, the behavior will be most likely be identical to that for an unavailable symbol.

Definition at line 148 of file compiler.h.