INFO: C++ Name Decoration--Why Used, Getting Decorated Names

• Microsoft Visual C++ for Windows, versions 1.5, 1.51, 1.52
• Microsoft Visual C++, 32-bit Edition, versions 2.0, 2.1, 4.0, 4.1, 5.0

SUMMARY

The Microsoft C++ compilers encode the names of symbols in C++ programs to include type information in the name. This is called "name decoration," or "name mangling." The purpose of this is to ensure type-safe linking. The C++ language allows function overloading where functions with the same name are only distinguished from one another by the data types of the arguments to the functions. Name decoration enables the linker to distinguish between different versions of overloaded functions because the names of the functions are encoded or decorated differently.

MORE INFORMATION

Different compiler vendors have their own methods or algorithms for decorating names. Microsoft does not publish the algorithm its compilers use for name decoration because it may change in the future. However, it is sometimes necessary to get the decorated version of a function name. For example, you may need to export a C++ function from a Windows DLL by listing it in the EXPORTS section of a .DEF file used to build the DLL. (Although declaring the function with __declspec( dllexport ) is the preferred method to export a C++ function using Visual C++, 32-bit Edition, it is still valid to use a .DEF file with these products.) To export the function successfully, you need to list its decorated name, not the name in the source code.

For all of the products listed above, Microsoft makes browser toolkits available. These toolkits provide functions that can interpret decorated names.

For information about __declspec( dllexport )or browser toolkits, please see the respective articles in the Microsoft Knowledge Base:

   ARTICLE-ID: Q132044
   TITLE     : How to Use _declspec(dllimport) & _declspec(dllexport) and
               Why

   ARTICLE-ID: Q153393
   TITLE     : Browser Toolkit for Microsoft Visual C++

Sample Code

   /* Compile options needed: cl /AL getname.cpp bthunkl.obj /link bsc.lib
          (for 16-bit, where getname.cpp is the source file name)
                              cl getname.cpp /link bsc.lib
          (for 32-bit version 4.x and earlier, where getname.cpp is the

           file name)
   */

   #include <iostream.h>
   #include <strstrea.h>

   extern "C"
   {
   #include "hungary.h"
   #include "bsc.h"
   #include "bscsup.h"
   }

   void main( int argc, char *argv[] )
   {
       if ( argc < 2 )
       {
           cout << "Usage: GETNAME decorated-name" << endl;
           return;
       }

       strstream name;

       // Call browser library function to get undecorated name
       name << FormatDname ( argv[1] ) << '\0';

       cout << "Undecorated name: " << name.str() << endl;
       name.rdbuf()->freeze( 0 );
   }

   /* Compile options needed: cl /GX getname.cpp /link msbsc50.lib
          (where getname.cpp is the source file name)
   */

   #include <iostream>
   #include <strstream>
   #include <windows.h>
   #include "bsc.h"

   using namespace std;

   int main( int argc, char *argv[] )
   {
       Bsc* pbsc;

       if ( argc < 3 )
       {
           cout << "Usage: GETNAME bscfile-name decorated-name" << endl;
           return 1;
       }

       strstream name;

       // Open the browser file
       Bsc::open( argv[1], &pbsc );

       // Call browser library function to get undecorated name
       name << pbsc->formatDname( argv[2] ) << '\0';

       cout << "Undecorated name: " << name.str() << endl;
       name.rdbuf()->freeze( 0 );

       pbsc->close();
       return 0;
   }

Keywords          : CPPIss kbcode
Version           : Windows: 1.5,1.51,1.52;Winnt:2.0,2.1,4.0,4.1,5.0
Platform          : winnt
Issue type        : kbinfo