Symbol objects provide information about function symbols in the application. See Symbols for more information.
You must call PIN_InitSymbols to make symbols available.
Can be accessed at instrumentation time and analysis time.
APIs from this group are available in any thread, including any internal thread spawned by the tool.
Iteration idioms:
SYM IMG_RegsymHead(IMG img)
Returns the first regular symbol in the image.
BOOL SYM_Valid(SYM sym)
Checks if the symbol is valid.
SYM SYM_Next(SYM sym)
Returns the routine that follows this symbol, or SYM_Invalid() if it is the last.
- Availability:
- Mode: JIT & Probe
O/S: Linux & Windows
CPU: All
◆ UNDECORATION
Definitions for symbol undecoration
List of supported symbol name undecoration styles.
| Enumerator |
|---|
| UNDECORATION_COMPLETE | Undecorate to full symbol signature.
|
| UNDECORATION_NAME_ONLY | Undecorate to [scope::]name.
|
◆ PIN_UndecorateSymbolName()
| std::string PIN_UndecorateSymbolName |
( |
const std::string & |
symbolName, |
|
|
UNDECORATION |
style |
|
) |
| |
|
extern |
Undecorates symbol name.
Provides undecoration of C++ names and decorated C names. The behavior of this function
is compiler and OS specific.
The C++ mangled name is undecorated either to its full signature (UNDECORATION_COMPLETE style)
or to [scope::]name form (UNDECORATION_NAME_ONLY style).
Example of undecoration of symbol generated by Microsoft compiler in Windows:
Style Original name Undecorated name
===================== ================== ======================================
@ UNDECORATION_NAME_ONLY
Undecorate to [scope::]name.
Definition sym_undecorate.PH:19
@ UNDECORATION_COMPLETE
Undecorate to full symbol signature.
Definition sym_undecorate.PH:18
Symbol name decorated according to Windows IA32 C calling conventions is undecorated as follows:
_foo -> foo (__cdecl convention)
_foo@4 -> foo (__stdcall convention)
@foo@12 -> foo (__fastcall convention)
Example of undecoration of symbol generated by GCC compiler on Linux:
Style Original name Undecorated name
===================== ================== ======================================
UNDECORATION_COMPLETE _ZN1A7method1ERKSt6vectorIiSaIiEE A::method1(std::vector<
int, std::allocator<int> >
const&)
Undecoration of macOS* symbols is done similarly to Linux (Remove the leading '_' and undecorate like Linux)
You should be careful if using this function, since some of the undecorated names it generates for symbols generated by the compiler may not be valid C++ symbol names. For example on Linux demangling can give names like construction vtable for std::istream-in-std::iostream, or non-virtual thunk to std::strstream::~strstream(), which are not valid C++ names.
- Parameters
-
| [in] | symbolName | Decorated name
|
| [in] | style | Undecoration style, relevant only to C++ undecoration
Values:
UNDECORATION_COMPLETE undecorate to full signature
UNDECORATION_NAME_ONLY undecorate to [scope::]name
|
- Returns
- string containing undecorated symbol name.
If undecoration fails or not supported, the function returns the unmodified original name.
- Availability:
- Mode: JIT & Probe
O/S: Windows, Linux
CPU: All
◆ SYM_Address()
| ADDRINT SYM_Address |
( |
SYM |
sym | ) |
|
|
extern |
Returns the address of the symbol in memory.
- Parameters
-
- Returns
- address of the symbol in memory
◆ SYM_Dynamic()
| BOOL SYM_Dynamic |
( |
SYM |
sym | ) |
|
|
extern |
Checks if the symbol is a dynamic symbol.
- Parameters
-
- Returns
- True if sym is a dynamic symbol
◆ SYM_GeneratedByPin()
| BOOL SYM_GeneratedByPin |
( |
SYM |
sym | ) |
|
|
extern |
Checks if the symbol was generated by Pin.
- Parameters
-
- Returns
- True if sym is a symbol which did not appear in the image's original symbol table and was added by Pin (for example when resolving an ifunc). False if the symbol existed in the image's symbol table
◆ SYM_IFuncImplementation()
| BOOL SYM_IFuncImplementation |
( |
SYM |
sym | ) |
|
|
extern |
Checks if the symbol is an IFUNC implementation symbol.
- Parameters
-
- Returns
- True if sym is an IFUNC implementation symbol
◆ SYM_IFuncResolver()
| BOOL SYM_IFuncResolver |
( |
SYM |
sym | ) |
|
|
extern |
Checks if the symbol is an IFUNC resolver symbol.
- Parameters
-
- Returns
- True if sym is an IFUNC resolver symbol
◆ SYM_Index()
| UINT32 SYM_Index |
( |
SYM |
sym | ) |
|
|
extern |
Returns the section index of a symbol.
- Parameters
-
Pin keeps the symbols ordered by their address location in the image. The index represents the order in which they were found when processing the different symbol table sections and debug information.
- Note
- There is no guarantee that the index represents the order of the symbols in the image. Also, when both symbol table and debug information are available, all that can be said is that the symbol table symbols will have lower indexes than the debug information symbols.
- Returns
- section index of a symbol
◆ SYM_Invalid()
Returns a value used to indicate no symbol.
- Returns
- Used to indicate no symbol
◆ SYM_Name()
| const std::string & SYM_Name |
( |
SYM |
sym | ) |
|
|
extern |
Returns the name of the symbol.
- Parameters
-
- Returns
- Name of symbol
◆ SYM_Next()
Returns the routine that follows this symbol, or SYM_Invalid() if it is the last.
- Parameters
-
- Returns
- Routine that follows sym, or SYM_Invalid() if sym is the last in the section
◆ SYM_Prev()
Returns the routine that precedes this symbol, or SYM_Invalid() if it is the first.
- Parameters
-
- Returns
- Routine that precedes sym, or SYM_Invalid() if sym is the first in the section
◆ SYM_Valid()
| BOOL SYM_Valid |
( |
SYM |
sym | ) |
|
|
extern |
Checks if the symbol is valid.
- Parameters
-
| [in] | sym | The symbol object to check |
- Returns
- True if sym is not SYM_Invalid()
◆ SYM_Value()
| ADDRINT SYM_Value |
( |
SYM |
sym | ) |
|
|
extern |
Returns the value of the symbol, usually an address relative to beginning of image.
- Parameters
-
- Returns
- Value of symbol, usually an address relative to beginning of image
