NAME

find_dup_syms.pl

SYNOPSIS

Checks for multiply defined symbols. Helps developer determine if he/she *might* accidentally be picking up the wrong version of a function.

For example, suppose there is a user-defined version of clock() in an application that also includes an off-the-shelf library that defines the same function. If the wrong version gets linked in, host time might be read and real-time behavior could be messed up.

USAGE

    find_dup_syms.pl <options> <XML-file> <NM-cmd>

NM-cmd is the utility that prints the name list of an object file. Examples: nm6x for C6000 or nm55 for C5500. See "HOW TO CREATE THE XML FILE" (below) for details on generating the XML file.

OPTIONS

    --help                      : Print usage message
    --quiet                     : Quiet mode (suppress warnings)
    --other_symbols_too         : Check for duplicates of bss, data, and
                                  weak symbols
    --short                     : Short output format - faster run time
                                  mutually excl. with --ignore_pulled_from
    --ignore_pulled_from=<file> : Suppress printing of duplicates which are
                                  pulled from <file>
                                  mutually exclusive with --short
    --basedir=<dir>             : Link command was run from directory <dir>
    --cg_xml_version            : Print out the version of the cg_xml package

EXAMPLES

If the final link command was performed in the directory C:\MyProjectDir\release, use

    find_dup_syms.pl --basedir=C:\MyProjectDir\release xmlfile.xml nm6x

Suppose you do not care about duplicate symbol definitions as long as the symbol was pulled in from file a.lib. Use

    find_dup_syms.pl --ignore_pulled_from=a.lib xmlfile.xml nm6x

In this case, if the script can determine conclusively that a symbol was pulled in from a.lib, it will silently ignore duplicate definitions of that symbol. However, if the script can only narrow down the source of the pulled in symbol to the set consisting of a.lib and b.lib then it will still print out the information for that symbol.

DETAILS

Script reads in an XML file representation of a linker map file and, with the aid of nmXX, reports global symbols which are defined in multiple XML files. Script also reports which version of a symbol was actually selected by the linker.

The script must be able to locate each object file or archive. Hence, the script must be run from the same directory from which the final link was performed or the --basedir=<dir> option must be used to specify the directory where the final link was performed.

Normally, the XML file must be specified as an absolute path or relative to the current directory. As a convenience, if the --base_dir=<dir> option is present, the XML file can also be specified relative to <dir>.

Other Perl scripts that work with utilities typically allow you to directly pipe the output of the utility directly into the script. This script does not work that way; it requires the NM output from multiple files, not just one.

By default, the script checks for duplicate definitions of text (code), data and bss symbols. Absolute symbol definitions are ignored. The reason is that on some targets, the compiler generates duplicate absolute symbol definitions by default. Handling this case would either generate a lot of false positives on some targets or yield a highly compiler-version dependent script). Duplicate weak definitions (Elf only feature) are considered by request only (--weak option). Weak definitions provide a method for a library developer to define library symbols that a user might want to override.

Also by default, when duplicate symbols are discovered, the script prints out which definition was linked in (i.e, the name of the archive/object file which contains the definition that was linked in). This computation takes about 30% of the total run time. If this information is not needed, run the script with --short to get faster turnaround time.

HOW TO CREATE THE XML FILE

Generate the XML version of the map file with the linker option

    --xml_link_info=<file>

You must use a relatively recent linker which supports the --xml_link_info option. However, there is NO requirement as to which version of the tools were used to create the libraries being linked in. In other words, this script will work even if some of the libraries were built with old compiler tools.

REQUIREMENTS

XML version of map file.
nm command
All libraries and object files must exist under the same name and in the same location as when the application was linked and must be readable.

LIMITATIONS

Script must either be run from same directory in which final link was performed or the --basedir option must be used to specify directory from which final link was performed.
If there are 0 calls to a lib, that lib will not show up in the .xml file and hence, will not be checked for duplicate symbol definitions.
Libraries that are linked into a partial .out and then relinked will generally not be checked for duplicate symbol definitions. For example, after the following series of link steps, the files p1.lib and p2.lib will not show up in full.xml and hence will not be checked. Only references to members that needed to be resolved to build the partial .out will get checked.
```
    cl6x -z -r [-a] p1.lib p2.lib partial.out
    cl6x -z --xml_link_info=full.xml partial.out ... -o full.out
```
An attempt is made to track down the archive/object file from which the linked-in definition of a (multiply-defined) symbol originated. Usually, the script can precisely identify the file from which the definition was pulled. In a few cases it cannot (e.g., when the output section containing the symbol is part of a union). If the script cannot identify a unique file, it will print out a list of all candidates instead.

CONFIGURE FOR YOUR SYSTEM

This script was written using Perl version 5.8.3. It may not work with earlier revisions of Perl.

Documentation for find_dup_syms.pl