--------------------------------------------------------------------------------
Symbol Files
------------
A symbol file contains the same debugging information that an executable file
would contain. However, the information is stored in a file with a .DBG
extension, rather than the executable file. Therefore, you can install only the
symbol files you will need during debugging. This reduces the file size of the
executable, saving load time and disk storage. 
To create a .DBG file, build your executable file with debug information, then
use the SplitSymbols function or the Rebase tool. 
The operating system dynamic-link libraries (DLL) have associated symbol files.
These files are not installed during installation. To install the system symbol
files, create a directory on your hard disk, and copy the files from your system
installation compact disc (CD). The symbol files are located in the
SUPPORT\DEBUG\I386\SYMBOLS directory tree. 
--------------------------------------------------------------------------------
SplitSymbols
------------
The SplitSymbols function strips symbols from the specified image.

BOOL SplitSymbols(
  IN LPSTR ImageName,    
  IN LPSTR SymbolsPath,  
  OUT LPSTR SymbolFilePath,  
  IN DWORD Flags         
);

Parameters

ImageName 
Pointer to a null-terminated string that specifies the name of the image from
which to split symbols. 

SymbolsPath 
Pointer to a null-terminated string that specifies a subdirectory for storing
symbols. This parameter is optional. 

SymbolFilePath 
Pointer to a null-terminated string that specifies the name of the generated
symbol file. This file typically has a .DBG extension. 

Flags 
Specifies the information to be split from the image. This parameter can be zero
or a combination of the following values: 
Value                       Meaning
SPLITSYM_EXTRACT_ALL        Usually, an image with the symbols split off will
                            still contain a MISC debug directory with the name
                            of the symbol file. Therefore, the debugger can
                            still find the symbols. Using this flag removes this
                            link. The end result is similar to using the
                            -debug:none switch on the Microsoft linker.

SPLITSYM_REMOVE_PRIVATE     This strips off the private CodeView symbolic
                            information when generating the symbol file. It does
                            this by making a call to the
                            RemovePrivateCvSymbolic function.

Return Values
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To retrieve extended error
information, call GetLastError.

Remarks
The SplitSymbols function should be used when stripping symbols from an image.
It will create a symbol file that all Win32-compatible debuggers understand.
The format is defined in WINNT.H and consists of an image header
(IMAGE_SEPARATE_DEBUG_HEADER), followed by the array of section headers,
the exception information (on RISC only) or FPO information (on X86 only),
and all debug symbolic information from the image.

If the SymbolsPath parameter is NULL, the symbol file is stored in the directory
where the image exists. Otherwise, it is stored in the subdirectory below
SymbolsPath that matches the extension of the image. Using this method reduces
the chances of symbol file collision. For example, the symbols for myapp.exe
will be in the SymbolsPath\exe directory and the symbols for myapp.dll will be
in the SymbolsPath\dll directory.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for
           Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions,
RemovePrivateCvSymbolic 
--------------------------------------------------------------------------------
Rebase
------
Rebase is a command-line tool that you can use to specify the base addresses for
the DLLs that your application uses. The base address of a DLL is the location
in virtual memory where the loader attempts to place the DLL. It is generally
specified at link time. If a DLL cannot load at its base address because the
memory is already occupied, the loader places the DLL elsewhere in virtual
memory, then updates all calls into the DLL to reflect the new base address.
Making these changes can be time consuming, because the image must be copied to
the pagefile and modified for the new address. If you have a large application
that uses many DLLs, it is important for each DLL to have a different base
address to minimize load time. You will receive the following warning from the
loader if a DLL is relocated: 

LDR: Automatic DLL Relocation in ProcessName.
LDR: DLL ImageName base ImageBase relocated due to collision with ExistingImage.

When you pass all the DLLs for your application to Rebase, it bases each DLL at
a unique address. You should not pass your .EXE file to Rebase. It is the first
thing to be loaded, so there is no chance that something else can already be
loaded at its default load address. 

The system DLLs are currently based in memory from 0x70000000 to 0x78000000
(0x68000000 to 0x78000000 on MIPS). Therefore, you should base your DLLs from
0x60000000 to 0x68000000. One possible scheme is to choose a base address based
on the first letter of the DLL name:

First Letter      Base Address
A - C             0x60000000
D - F             0x61000000
G - I             0x62000000
J - L             0x63000000
M - O             0x64000000
P - R             0x65000000
S - U             0x66000000
V - X             0x67000000
Y - Z             0x68000000

It is best to base DLLs from the top of the address range down, instead of from
the bottom up. Dynamic memory is allocated from the bottom up and if a DLL tries
to load where dynamic memory has been allocated, it will be relocated, just as
if a DLL was loaded at that address. 

To use Rebase to base your DLLs, use the following syntax:

rebase [options] image-names

Rebase has the following command-line options: 

-b initial_base 
   Specify initial base address. It is mandatory that you use either
   the -b or -i option. 

-i coffbase_filename 
   Read base addresses from the file coffbase_filename. It is mandatory that
   you use either the -b or -i option. 

-c coffbase_filename 
   Write the list of base addresses to the file coffbase_filename. The filename
   extension is not included. Use -C to include filename extensions. 

-d 
   Perform a top-down rebase. 

-l logFilePath 
   Write image bases to log file. 

-z 
   Allow rebasing the system file. 

-R image_root 
   Set a root directory for use by the -G, -O, -N options. 

-G filename 
   Group specified images together in address space. May be used multiple times.
   Specify a root directory with the -R option. 

-N filename 
   Leave specified images at their original addresses. May be used multiple
   times. Specify a root directory with the -R option. 

-O filename 
   Overlay images in address space. May be used multiple times. Specify a root
   directory with the -R option. 

-x symbol_dir 
   Extract debug information into separate .DBG file before rebasing. Use
   symbol_dir to place the .DBG files are placed in the directories
   symbol_dir\EXE or symbol_dir\DLL, depending on whether the source is an .EXE
   file or a .DLL file. To specify the current directory for the symbol
   directory, use a period (.). 

-p 
   Used with the -x option. Remove private debug information when creating .DBG
   files. 

-a 
   Used with the -x option. Extract all debug information into the .DBG files. 


-f 
   Strip relocations after rebasing the image. Causes failure to load. 

-s 
   Just sum image range. 

-q 
   Minimal output. 

-v 
   Verbose output. 

-? 
   Display command-line syntax. 



Alternatively, you can use the ReBaseImage function.

NoteIf you shared a section in your DLL, the loader will fail to load the
      image if it needs to be relocated and the shared section contains any
      relocations. This is a good reason to use named shared memory instead of
      using shared sections.
--------------------------------------------------------------------------------
RemovePrivateCvSymbolic
-----------------------
The RemovePrivateCvSymbolic function removes all but public information from the
CodeView debug information.

BOOL RemovePrivateCvSymbolic(
  IN PCHAR DebugData,       
  OUT PCHAR *NewDebugData,  
  OUT LPDWORD NewDebugSize  
);
 

Parameters

DebugData 
Pointer to the CodeView debug data. This data can be found by mapping the image
and searching the debug directories for debug type IMAGE_DEBUG_TYPE_CODEVIEW. 

NewDebugData 
Pointer to a buffer that receives the public CodeView debug information. 

NewDebugSize 
Pointer to a variable that receives the size of the public CodeView debug
information. 


Return Values
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The RemovePrivateCvSymbolic function removes all but public information from
the CodeView debug information. Therefore, you can ship the debug symbols for
an image without disclosing your data structures or other source information.
The user can only get a stack trace, place breakpoints on functions, and dump
memory. All but the following CodeView sections are discarded: 
sstSegMap
sstSegName
sstOffsetMap16
sstOffsetMap32
sstModule
sstPublic
sstPublicSym
sstGlobalPub 

It is the responsibility of the caller to free the memory pointed to by the
NewDebugData parameter when he is finished.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for
           Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions 
--------------------------------------------------------------------------------
FindDebugInfoFile
-----------------
The FindDebugInfoFile function locates a symbol file.

HANDLE FindDebugInfoFile(
  IN LPSTR FileName,    
  IN LPSTR SymbolPath,  
  OUT LPSTR DebugFilePath  
);
 

Parameters


FileName 
Pointer to a null-terminated string that specifies the name of the symbol file
that is desired. You can use a partial path. 

SymbolPath 
Pointer to a null-terminated string that specifies the path where symbol files
are located. This can be multiple paths, with each separated by a semicolon (;). 

DebugFilePath 
The full path of the symbol file that is found. 


Return Values
If the function succeeds, the return value is an open handle to the debug file.
If the function fails, the return value is NULL. To retrieve extended error
information, call GetLastError.

Remarks
The FindDebugInfoFile function is used to locate a symbol file. This function is
provided so symbol files can be located in several different directories through
a single function call. The SymbolPath parameter can contain multiple paths,
with each separated by a semicolon (;). When multiple paths are specified, each
directory tree is searched for the symbol file. When the file is located, the
search stops. Thus, be sure to specify SymbolPath with the paths in the correct
order.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for
           Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions 
--------------------------------------------------------------------------------