gcore

Use dbghelp to write a Windows minidump (core) file 

Command

SYNOPSIS

gcore [-o path_to_minidump_file] [-v] [-p] pid

DESCRIPTION

Windows ships with a minimalistic dbghelp.dll which allows an application to write a minidump (core) file. gcore finds a dbghelp.dll, either the windows minimal version or (if installed) the windows 10 debugging tools dbghelp.dll. Once loaded, a call is made to MiniDumpWriteDump() and given a file to use to write the process current state.

Before writing all threads' suspend counts are incremented and after writing decremented (usually), leaving the suspend count as it was before the dump is taken.

On 64 bit Windows, a 64 bit version of gcore is installed and should be used to capture minidump files for both 32 and 64 bit processes.

Note:
The NuTCRACKER Platform is also capable of generating minidump files using the NUT_DUMP_CORE environment variable. gcore is an alternative when an application is not triggering a dump through an exception (SIGSEGV) but is misbehaving in other ways. However gcore is not limited to operating on NuTCRACKER Platform executables.

Options

-o path_to_minidump_file 

MiniDumpWriteFile() will use path_to_minidump_file as an absolute path to write minidump. If the file exists it is overwritten without asking. The calling process must have permission to (over)write this file. WriteMiniDumpFile() is called with these options MiniDumpWithFullMemory | MiniDumpWithHandleData | MiniDumpWithUnloadedModules | MiniDumpWithIndirectlyReferencedMemory | MiniDumpWithProcessThreadData | MiniDumpWithPrivateReadWriteMemory | MiniDumpWithFullMemoryInfo | MiniDumpWithThreadInfo | MiniDumpWithPrivateWriteCopyMemory | MiniDumpWithTokenInformation | MiniDumpWithCodeSegs | MiniDumpWithModuleHeaders.

-v 

Write some diagnostics along the way.

-p pid 

The pid is used in a call to OpenProcess() to obtain a process handle to pass to MiniDumpWriteFile(). The calling process must have permission to open the target process (specifically: PROCESS_QUERY_INFORMATION | PROCESS_DUP_HANDLE | PROCESS_SUSPEND_RESUME | PROCESS_VM_READ), and this process must exist. As such, gcore has been given a manifest which requires highestAvailable UAC permissions and an attempt will be made to assert SeDebugPrivilege (if available on the process token). It might be necessary to run this as an administrator (using a password) depending upon UAC permissions of the calling process.

The -p is optional if pid is the last argument.

DIAGNOSTICS

Possible exit status values are:

0 

Success, the minidump file was written to the specified location.

1 

Failure due to any of the following:

— process id not found
— No permission to open process
— No permission to write files
— Unable to find any dbghelp.dll to use
— Any MiniDumpWriteFile failure

Failure to adjust token privileges to add SeDebugPrivilege is not a fatal error, but the inability to assert the privilege may result in OpenProcess() failures.

Failure to suspend threads within the target process is not a failure, but is reported with option -v.

BUGS

gcore is the Unix way to drop a core file using Win32 APIs, such that the result is a Windows Crash Dump compatible with Visual Studio and WinDbg. Not all semantics of the Solaris version are implemented, but it ought to feel normal and friendly.

The Linux version of gcore has a -a option. This option is not implemented, but mapped memory will all be dumped.

PORTABILITY

Available on some UNIX systems, specifically UNIX System V. and Linux.

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

NOTE

A copy of the redistributable version of dbghelp.dll can be installed from the PTC MKS Toolkit ISO image thus: 

msiexec /i "D:\Redist\X64 Debuggers And Tools-x64_en-us.msi" ADDLOCAL="fe1559e6e1022144a8b5b0ae14281475a3"
or
msiexec /i "D:\Redist\X86 Debuggers And Tools-x86_en-us.msi" ADDLOCAL="fe38ed01ff1436410fb3e03ada25cc9a6d"

All that is really needed is a feature with title "Redistributable Debugger Core Binaries". There is no harm in installing the whole debugging tools for Windows package. Perhaps you have it installed already from installing the Debugging Tools for Windows with Visual Studio or the Windows SDK (https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk). And there is really no harm in using the limited version installed with Windows - except that the Debugger Core Binaries have more option bits and so create more useful information for post-mortem debugging.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
PTC Windchill Requirements and Validation

PTC MKS Toolkit 10.4 Documentation Build 39.