NAME

mapNames − creating "glue" files for (incorrectly mangled) c++ identifiers

SYNOPSIS

mapNames sourceName1[=targetName1] sourceName2[=targetName2] ... > file.s

DESCRIPTION

mapNames invokes a tool that is intended to help create assembly language files containing minimal "glue" code for mapping a set of sourceNames referenced in object files produced by lcc, the lucid C/C++ compiler, to different targetNames defined in other object files or libraries.  This is mainly for use with existing (object or library) files that contain incorrectly mangled names produced by cfront based compilers but can be used as a more general impedence matching tool for other "name" mismatch situations, as explained bellow. 
 
NOTE: Most of the functionality described here is not needed if you use lcc in its cfront-compatible mode (-Xf) to compile for linking with the existing Sun-cfront-2.1 compiled objects and libraries.  Otherwise this tool can be helpful if you need to link files compiled with incompatible mangling in effect provided the object files are run-time compatible. 
 
cfront 2.1 contains a bug that causes it to incorrectly mangle the names of types defined inside classes in some cases.  This bug has been fixed in cfront 3.0 and does not exist in lcc’s strict c++ mode (lcc -XF), though the bug is emulated in lcc’s cfront compatible mode (lcc -Xf).
 
Due to this, if you try to link modules compiled by lcc -Xf or cfront 3.0 with modules compiled with cfront 2.1, you might get unresolved externals.
 
This bug occurs when cfront 2.1 compiles a class declaration which defines a local typedef, enum, or class name, and there is no existing global definition of the same name.  For example:
 

    struct OUTER
    {
        enum T1 { a, b};
        void gus( TD);
    };

 
cfront 2.1 will mangle the name of ’gus’ into
 
     _gus__5OUTERF2TD
 
whereas the correct mangling produced by lcc -XF and cfront 3.0 is
 
     _gus__5OUTERFQ2_5OUTER2TD
 
The ’Q2_5OUTER’ that is missing from the cfront 2.1 name identifies TD as being local to class OUTER.  Thus, the cfront 2.1 name identifies TD as a global name instead of a local name.
 
You should suspect that you have this problem if you link lcc -Xf or cfront 3.0 compiled modules with cfront 2.1 compiled modules or libraries and you get an error message such as the following from the linker:
 
    ld: Undefined symbol
       _gus__5OUTERFQ2_5OUTER2TD
 
(If this occurs, you can use the ’nm’ utility to examine the entry points in the cfront 2.1 compiled modules for the cfront 2.1 version of the unresolved name.) 
 
This problem can be solved in three ways:

1- Compile the offending modules with lcc -XF or cfront 3.0 instead of cfront 2.1. 

2- If the offending modules must be compiled with cfront 2.1,then add a dummy global declaration of the offending type name.  In this example, add:
 
    enum T1;
 
just before the struct declaration.  This will cause cfront 2.1 to treat the local T1 as a true local type and mangle it correctly.

3- If the offending modules were distributed to you in binary form only so that you cannot recompile them, contact the distributor and ask them to send you updated versions in which the problem has been fixed by application of item 1 or 2 above. 

4- As a last resort, you can use the utility program, mapNames, that is supplied with your Lucid compiler to produce an assembler source code file that will will map the correct mangled names to the incorrect mangled names. 

mapNames is included in the bin subdirectory of your Lucid compiler installation directory.  It is called with a list of the unresolved names reported by the linker and it produces an assembler source code file on stdout.  For each input name, this output file contains an entry point which simply calls the equivalent cfront 2.1 version of the name.  You should redirect the output of mapNames to a .s file and then name that .s file on your lcc command line that invokes the linker. 
 
In this example, you would do the following:
 
    mapNames _gus__5OUTERFQ2_5OUTER2TD >fixit.s
 
and then add ’fixit.s’ to your link command.
 
Note that if you have more than one such naming problem, you can give all the unresolved names to mapNames at once and it will produce all the needed mapping functions in a single .s file.
 
Instead of allowing mapNames to figure out the correct target name, you can supply it yourself by using a parameter of the form:
 
    sourceName=targetName
 
There must be no whitespace around the ’=’.  For example,
 

    mapNames _gus__5OUTERFQ2_5OUTER2TD=_gus__5OUTERF2TD  > fixit.s

 
will produce the same output as the command shown above.  This allows mapNames to be used to do general name replacement without recompiling source code.
 
The = form of parameter and the single name form of parameter can be intermixed in a single call to mapNames.  For example:
 

    mapNames sam=mary \
                     _gus__5OUTERFQ2_5OUTER2TD \
                     joe=sue  > fixit.s

 
will produce mapping functions in fixit.s for:
 

                          sam -> mary
    _gus__5OUTERFQ2_5OUTER2TD -> _gus__5OUTERF2TD
                          joe -> sue

 
Aside from the nested types shown above, cfront2.1 also contains a bug that causes it to mis-mangle the name of the following function:
 
    void gus( void ∗, const void ∗);
 
cfront2.1 and lcc -Xf mangle this name as
 
    _gus__FPvT1
 
whereas cfront 3.0 and lcc -XF correctly mangle this as:
 
    _gus__FPvPCv
 
The mapNames utility can be used to direct calls generated by lcc -XF to the correct mangled name onto the incorrect entry point name generated by cfront 2.1 or lcc -Xf :
 
    mapNames _gus__FPvPCv=_gus__FPvT1
 
 

SEE ALSO

 
Lucid C++ User’s Guide, Lucid, Inc., June 1993. 
 
demangle(1L)

Lucid C/C++ Rev. 2.2   —  Last change: 6/15/93