======== CHECKSYM ======== OVERVIEW -------- Checksym is a symbol checking facility that allows an individual to verify that they have correct symbols (DBG, DBG/PDB, and PDB files) for processes and files on their system, and to assist them in location of files that don't match. This can be useful in anticipation of having to debug a local or remote process. In addition, Checksym offers support for situations where a person (PSS engineer) will need to perform a debug of a customer's environment, or analyze a user.dmp file produced in a customer environment. In this situation, you need symbols that will match those that would be necessary for the remote environment. Checksym was written to aid both of these situations. FEATURES -------- * Runs on Windows 98, Windows NT 4.0, Windows 2000 * Interogates running process(es) for all modules loaded * Interogates files on a specified path * Interogates files in a DMP file (Only User.dmp files currently) * Can obtain version info for all files interogated * Can obtain symbol information necessary for symbol verification * Can output to a CSV file (which can later be read in - useful for remote debug scenarios) ------------------------------------------------------------------------------- CHECKSYM V1.8.0 - Symbol Verification Program - gregwi@microsoft.com ------------------------------------------------------------------------------- This version is supported for Windows 98, Windows NT 4.0 and Windows 2000 DESCRIPTION: This program can be used to verify that you have proper symbol files (*.DBG and/or *.PDB) on your system for the processes you have running, and for symbol files on your filesystem. This program can also be used to collect information regarding these modules and output this to a file. The output file can then be given to another party (Microsoft Product Support Services) where they can use the file to verify that they have proper symbols for debugging your environment. Obtaining online help: CHECKSYM -? : Simple help usage CHECKSYM -??? : Complete help usage (this screen) Usage: CHECKSYM [COLLECTION OPTIONS] [INFORMATION CHECKING OPTIONS] [OUTPUT OPTIONS] ***** COLLECTION OPTIONS ***** At least one collection option must be specified. The following options are currently supported. -P : Collect Information From Running Processes When used in conjunction with -O the output file will contain information about your running system. This operation should not interfere with the operation of running processes. = [ * | Process ID (pid) | Process Name ] To query all running processes, specify the wildcard character '*'. To specify a specific process, you can provide the Process ID (as a decimal value), or the Process Name (eg. notepad.exe). If you use the Process Name as the argument, and multiple instances of that process are running they will all be inspected. -F :Collect Information From File(s) Specified by the User This option will allow you to obtain module information for modules on the specified path. Multiple paths may be provided, separated by semicolons. If the path provided is a directory, then a recursive scan of files from that directory will be used to obtain module information. This input method is useful for situations where the module(s) is not loaded by an active process. (Eg. Perhaps a process is unable to start.) -I : Collect Information from a Saved Checksym Generated CSV File This input method is useful when you want to evaluate whether you have proper symbols for modules on a different system. Most commonly this is useful for preparing to do a remote debug of a remote system. The use of -I prohibits the use of other collection options. -Z : Collect Information from a DMP File This input method is useful when you have a DMP file and to ensure that you have matching symbols for it. Checksym tries to determine as much information as possible to in finding good symbols. If a module name can not be determined (mostly with modules that only use PDB files), the module will be listed as "IMAGE". ***** INFORMATION CHECKING OPTIONS ***** -S : Collect Symbol Information From Modules. This option is used to indicate that symbol information should be collected from every module analyzed. In order to verify proper symbols, symbol information must be gathered. For this reason, the use of -V (verify symbols) automatically implies -S. It is, however, possible to collect this information without verifying symbols. This case is usually used with the -O option to produce a saved CheckSym generated CSV file. Omitting -S and -V could direct CheckSym to collect only version information (if -R is specified), or no information (if no information checking options are specified. -R : Collect Version and File-System Information From Modules. This option requests checksym to collect the following information from the file-system and version information structure (if any): File Version Company Name File Description File Size (bytes) File Date/Time -V[|1|2] : Verify Symbols for Modules This option uses the symbol information gathered (-S option) to verify that proper symbols exist (as found along the symbol path. Use of -V implies -S when module collection is initiated. There are different levels of symbol verification: -V or -V1 : (Default) This treats symbol files that match the module's time/date stamp, but have an wrong checksum as valid symbols. This is the default behavior and these symbols are typically valid. -V2 : Only if both checksum and time/date stamp match is the symbol considered valid. -Y : Verify Symbols Using This Symbol Path This is a semi-colon separated search path for looking for symbols. This path is searched with the -V option. The default value is %systemroot%\symbols ***** OUTPUT OPTIONS ***** -B : Build a Symbol Tree of Matching Symbols This option will create a new symbol tree for ALL matching symbols that are found through the verification process (-v option). This option is particularly useful when used with the -Y option when many symbol paths are specified and you want to build a single tree for a debug. -Q[|2] : Quiet modes (no screen output, or minimal screen output) The default behavior is to print out the data to the console window (stdout). If the process terminates with an error, it will print out these (overriding -Q). -Q2 : This option prints out a module ONLY if a symbol problem exists. (Not completely quiet mode!) -O[|1|2] : Output Collected Module Information To a CSV File For this file to to be used as input (-I) to verify good symbols for this system, the -S option should also be used. -O or -O1 : (Default) This output mode requires that the file does not exist. -O2 : Specifying a -O2 will allow the output file to be OVERWRITTEN if it exists. -T : Task List Output Prints out a task list on the local machine (similar to the TLIST utility). This option implies the use of -P (querying the local system for active processes. You can provide the -P command explicitly (if you want to provide an argument, for instance). If -P is not specified explicitly, then it defaults to -P *. Also, -T overrides -Q since TLIST behavior is to print to the console window. ***** TYPICAL USAGE EXAMPLES ***** You want to verify the symbols for files in a directory (%SYSTEMROOT%\SYSTEM32) in the default symbol directory (%SYSTEMROOT%\SYMBOLS) CHECKSYM -F %SYSTEMROOT%\SYSTEM32 -V You want to do the same search, but for only executables... CHECKSYM -F %SYSTEMROOT%\SYSTEM32\*.EXE -V You want to search a directory using multiple symbol paths... CHECKSYM -F %SYSTEMROOT%\SYSTEM32\ -V -Y V:\nt40sp4;V:\nt40rtm You want to know what modules are loaded for a process (and the path to each) Start NOTEPAD.EXE, and then type: CHECKSYM -P NOTEPAD.EXE You want to know if you have good symbols for a process (notepad.exe). CHECKSYM -P NOTEPAD.EXE -V You want to know the file version for every module loaded by a process. CHECKSYM -P NOTEPAD.EXE -R You want to know if you have good symbols for ALL processes on your machine. CHECKSYM -P * -V ***** ADVANCED USAGE EXAMPLES ***** You are going to prepare to debug a remote system, and you want to ensure that you have good symbols locally for debugging the remote system. You want to verify this prior to initiating the debug session. Use checksym twice, once on the remote system to gather information and create an output file, and then once on your system using the output file created as an input argument. For example, run this on the remote system CHECKSYM -P * -S -R -O C:\TEMP\PROCESSES.CSV The C:\TEMP\PROCESSES.CSV file will contain a wealth of information about the processes that were running, and the modules loaded by every process. Now, get the output file from the remote system, and copy it locally. Then run CHECKSYM again, using the file as an input argument... CHECKSYM -I C:\TEMP\PROCESSES.CSV -V Another useful option is -B (build a symbol tree). It allows you to update or create a symbol tree that contains matching symbols. If you have to use many symbol paths in order to have correct symbols available to a debugger, can use the -B option to build a single symbol tree to simplify debugging. CHECKSYM -P * -B C:\MySymbols -V -Y V:\Nt4;V:\Nt4Sp4;V:\NtHotfixes ***** DEFAULT BEHAVIOR ***** The default behavior of CHECKSYM when no arguments are provided is: CHECKSYM -P * -R -V -Y %SYSTEMROOT%\SYMBOLS ========================== INSTALLATION INSTRUCTIONS ========================== Quick method: - Copy all files to a single directory, and run from there... Alternate method (using rules for the redistributable DLLs) - Create an installation directory - Copy CHECKSYM.EXE into the installation directory - Copy DBGHELP.DLL and MSDBI60.DLL into your installation directory - For Windows NT 4.0 ONLY - Copy PSAPI.DLL into the installation directory - Copy MSVCRT.DLL into your %windir%\system (or system32 directory) if this version is greater than the version in that directory (alternatively, you could copy this into your installation directory) ====================== RELEASE HISTORY ====================== Version 1.8 - COMMAND LINE CHANGE!!! (This version has changed the command-line option for symbols from -Z to -Y). It was always my intention to use the SAME command-line options as WinDbg and i386kd/ntsd where possible. For some reason, my choice of -Z for symbols (which was wrong) was not noticed until just recently. To achieve better consistency, this program was changed. - The ability to load a user.dmp file was added as option -Z (the same value used by i386kd and windbg Version 1.7.5 - CSV output file is not produced unless "some" data is collected - CSV output file now contains "DBG Pointer" (pointer to DBG file found in the MISC section of the Debug Directories entry), and "Product Version". - Fixed problem where directories were provided with a trailing '\' character - Prints out info for DBG and PDB files it fails to find (so you know what is being searched for. - Added support for the use of "pseudo-environment" variables. These act just like environment variables (you use them in provided paths), but they cause Checksym to query the registry to translate the string (this is product specific and very likely version specific. Supported strings include: %EXCHSRVR% Obtained from: KEY - "SOFTWARE\Microsoft\Exchange\Setup" VALUE - "Services" %SNASERVER% Obtained from: KEY - "SOFTWARE\Microsoft\Sna Server\CurrentVersion" VALUE - "PathName" %SQLSERVER% Obtained from: KEY - "SOFTWARE\Microsoft\MSSQLServer\Setup" VALUE - "SQLPath" %SMSSERVER" Obtained from: KEY - "SOFTWARE\Microsoft\SMS\Identification" VALUE - "Installation Directory" %INETSRV% Obtained from: KEY - "SOFTWARE\Microsoft\INetStp" VALUE - "InstallPath" This should make it easier to gather info for backoffice products... CHECKSYM -F %EXCHSRVR%\BIN -S -R -O OUTPUT.CSV -Q Version 1.7 - An X86 and an Alpha Build are built... - Help has been worked again. Bad arguments are reported, and a suggestion follows on how to obtain more help (it used to immediately dump the help which is now pages long -- which obscures the source of the problem as you watch it sailing off the top of your screen.) - "-O2" was created to allow the output file to overwrite an existing file (default behavior is to fail if output file exists already). - "-E" option added (this is used only by IIS Exception Monitor and will remain undocumented. It influences the data in any output file generated). - Improvements made to file version collection. Some modules don't carry the file version info where they should (in the FIXEDFILEINFO section) - Files discovered with "-F" option are now returned with their FULL path, not a potentially relative path... - Checks were added to ensure that paths provided aren't too long - Correct help to indicate that CHECKSYM supports semi-colon delimited paths (not colons) - Added progress dots during verify mode - Added the ability to search for a specific process name or process ID when reading in an input file... in other words, you could produce a monster big output.csv file from a customer machine... then take the file locally and issue the command (checksym -i output.csv -p myapp.exe -v) and checksym would only return information for matching process(es) of the name myapp.exe. Version 1.6 - This version uses MSVCRT.DLL, and the redistributable MSDBI60.DLL - Fixes crash when attempting to import a CSV file - Improved Help screens (more read-able)... I have a simple help -? and an expanded help -??? option. Version 1.5 - First major public release (added support for building symbol tree -B) Version 1.4 - Further improved support for Windows 95/98, added support for -SQL Version 1.3 - Added Support for scanning the Filesystem (-F option) Version 1.2 - Support for Windows 95/98 added Version 1.1 - Create module cache (improved performance dramatically) Version 1.0 - First version (queries local processes only)