Name Mangling

Intercept Module Terminology: Understanding Name Mangling

What is Name Mangling?

Name mangling describes the automatic source transformation required for a delegate to insert itself between caller and callee. There are two options for handling name mangling, one of which must be chosen when using delegates:

1. A call to a function f() is transformed to "__im_f()” to allow the delegate to intercept the call. This is referred to as user mangling.
   
2. The implemention of f() can be transformed to "__im_f()”. This is referred to as owner mangling.
   
   

Name mangling is necessary in order for the delegate to insert itself between caller and callee. For example, to use a delegate to trace all calls to a function, f():

• If we use user mangling, all calls to f() are transformed to be calls to __im_f(). The delegate is implemented as __im_f(). The original implementation of f() remains unchanged. This allows the delegate to intercept all calls and take the appropriate action.
  
• If we use owner mangling, the implementation of f() is changed from f(){...} to __im_f(){...}. The delegate is implemented as f() in order to intercept all calls.

Name Mangling Conflicts

A mangling conflict applies only to delegates. It exists when the name of a routine requires mangling, but there also exists other references to the same name within the same source file. The other references will inadvertently be mangled by the preprocessor.

Explicit mangling is used to resolve these type of name mangling conflicts. Explicit mangling uses the explicit macro "imDELEGATE(<function_name>)", which explicitly mangles the name of "f()" to "__im_f()". The explicit macro is defined in the Intercept Module delegate mangling header file (xxxIM.h). Explicit mangling requires Group ID(s) to be defined (#define MyGroupID) in the source file of the caller/callee of the routine to protect against the inclusion of unnecessary defined types.

The following examples demonstrate situations where explicit mangling can be used to resolve mangling conflicts:

1. The owner and the user of the same routine, f(), exist in the same source file.
   
2. Two users of a routine, f(), exist in the same source file, but only one is a user delegate.
   

Mangling Conflict Example 1: The owner and the user of the same routine, f(), exist in the same source file

If the owner and the user of the same routine, f(), exist in the same source file, the use of explicit mangling is required to resolve the mangling conflict. If the conflict is not resolved, the user will bypass the delegate by using the mangled name when making the call to the routine.

Mangling Conflict Example 2: Two users of a routine, f(), exist in the same source file, but only one is a user delegate

By default, delegates are owner-focused. An owner-focused delegate is used to mangle the actual routine; thus, every user (caller) of the routine goes through the delegate. There are use cases when source code for the routines cannot be accessed (i.e., as with libraries). A user-focused delegate can be used to mangle the caller instead of the routine to be called (callee). User-focused delegates typically do not have mangling conflicts, except when multiple users exist in the same source file, but only a subset is targeted to go through the delegate. Explicit mangling is used to avoid this type of mangling conflict.

The Group ID(s) must be defined before including the Intercept Module delegate mangling header file (xxxIM.h) and after all defined types (additional header files) in the source file(s) of the caller/callee of the routine.

#include "MyHeader.h"
#define <MyGroupID>
#include "xxxIM.h" 

To enable Intercept Modules to be regenerated continuously and to allow the user the option to add and/or remove delegates, an explicit macro is generated for each routine. If a routine is not selected as a delegate, an explicit macro will be generated so that name mangling will not occur. Also, if use of the Intercept Module is turned off via the source file (e.g., #undef srIMON), the macros will not perform name mangling. This allows users to leave explicit macros in their source code, even if the Intercept Module is not being used.

See also

• Intercept Module Overview
• Using s2sinstrument.exe to generate an Intercept Module