# Crashpad: crashpad::internal Namespace Reference

crashpad::internal Namespace Reference

The internal namespace, not for public use. More...

## Classes

class | CaptureMemory
class | CaptureMemoryDelegateWin
class | CheckedAddressRangeGeneric
| Ensures that a range, composed of a base and a size, does not overflow the pointer type of the process it describes a range in. More...
class | ClientData
| The context data for registered threadpool waits. More...
class | ExceptionSnapshotMac
| An ExceptionSnapshot of an exception sustained by a running (or crashed) process on a macOS system. More...
class | ExceptionSnapshotWin
struct | LocalAllocTraits
class | MachOImageSymbolTableReaderInitializer
| The internal implementation for MachOImageSymbolTableReader. More...
class | MemoryMapRegionSnapshotWin
class | MemorySnapshotMac
| A MemorySnapshot of a memory region in a process on the running system, when the system runs macOS. More...
class | MemorySnapshotWin
| A MemorySnapshot of a memory region in a process on the running system, when the system runs Windows. More...
class | MinidumpModuleCodeViewRecordPDBLinkWriter
| The base class for writers of CodeView records that serve as links to `.pdb` (program database) files. More...
class | MinidumpRVAListWriter
| The writer for a MinidumpRVAList object in a minidump file, containing a list of RVA pointers. More...
class | MinidumpStreamWriter
| The base class for all second-level objects (“streams”) in a minidump file. More...
class | MinidumpStringListWriter
| The writer for a MinidumpRVAList object in a minidump file, containing a list of MinidumpStringWriterType objects. More...
class | MinidumpStringWriter
| Writes a variable-length string to a minidump file in accordance with the string type’s characteristics. More...
class | MinidumpUTF16StringWriter
| Writes a variable-length UTF-16-encoded MINIDUMP_STRING to a minidump file. More...
class | MinidumpUTF8StringWriter
| Writes a variable-length UTF-8-encoded MinidumpUTF8String to a minidump file. More...
class | MinidumpWritable
| The base class for all content that might be written to a minidump file. More...
class | MinidumpWriterUtil
| A collection of utility functions used by the MinidumpWritable family of classes. More...
class | ModuleSnapshotMac
| A ModuleSnapshot of a code module (binary image) loaded into a running (or crashed) process on a Mac OS X system. More...
class | ModuleSnapshotMinidump
| A ModuleSnapshot based on a module in a minidump file. More...
class | ModuleSnapshotWin
| A ModuleSnapshot of a code module (binary image) loaded into a running (or crashed) process on a Windows system. More...
class | PipeServiceContext
| Context information for the named pipe handler threads. More...
class | ReadExactlyInternal
| The internal implementation of ReadFileExactly() and its wrappers. More...
struct | ScopedFileHANDLECloseTraits
struct | ScopedKernelHANDLECloseTraits
struct | ScopedLockedFileHandleTraits
class | SystemSnapshotMac
| A SystemSnapshot of the running system, when the system runs Mac OS X. More...
class | SystemSnapshotWin
| A SystemSnapshot of the running system, when the system runs Windows. More...
class | ThreadSnapshotMac
| A ThreadSnapshot of a thread in a running (or crashed) process on a macOS system. More...
class | ThreadSnapshotWin
| A ThreadSnapshot of a thread in a running (or crashed) process on a Windows system. More...
class | UniversalMachExcServerImpl
struct | UserDataMinidumpStreamListEntry
| A linked list of blocks representing custom streams in the minidump, with addresses (and size) stored as uint64_t to simplify reading from the handler process. More...
class | WorkerThreadImpl
class | WriteAllInternal
| The internal implementation of WriteFile() and its wrappers. More...

## Functions

std::string | MinidumpMiscInfoDebugBuildString ()
| Returns the string to set in MINIDUMP_MISC_INFO_4::DbgBldStr. More...
void | InitializeCPUContextX86 (CPUContextX86 *context, thread_state_flavor_t flavor, ConstThreadState state, mach_msg_type_number_t state_count, const x86_thread_state32_t *x86_thread_state32, const x86_float_state32_t *x86_float_state32, const x86_debug_state32_t *x86_debug_state32)
| Initializes a CPUContextX86 structure from native context structures on macOS. More...
void | InitializeCPUContextX86_64 (CPUContextX86_64 *context, thread_state_flavor_t flavor, ConstThreadState state, mach_msg_type_number_t state_count, const x86_thread_state64_t *x86_thread_state64, const x86_float_state64_t *x86_float_state64, const x86_debug_state64_t *x86_debug_state64)
| Initializes a CPUContextX86_64 structure from native context structures on macOS. More...
bool | ReadMinidumpSimpleStringDictionary (FileReaderInterface *file_reader, const MINIDUMP_LOCATION_DESCRIPTOR &location, std::map< std::string, std::string > *dictionary)
| Reads a MinidumpSimpleStringDictionary from a minidump file location in file_reader, and returns it in dictionary. More...
bool | ReadMinidumpStringList (FileReaderInterface *file_reader, const MINIDUMP_LOCATION_DESCRIPTOR &location, std::vector< std::string > *list)
| Reads a list of MinidumpUTF8String objects in a MinidumpRVAList from a minidump file location in file_reader, and returns it in list. More...
bool | ReadMinidumpUTF8String (FileReaderInterface *file_reader, RVA rva, std::string *string)
| Reads a MinidumpUTF8String from a minidump file at offset rva in file_reader, and returns it in string. More...
FileOperationResult | NativeWriteFile (FileHandle file, const void *buffer, size_t size)
| Writes to a file, retrying when interrupted on POSIX. More...
void * | AlignedAllocate (size_t alignment, size_t size)
| Allocates memory with the specified alignment constraint. More...
void | AlignedFree (void *pointer)
| Frees memory allocated by AlignedAllocate(). More...
FARPROC | GetFunctionInternal (const wchar_t *library, const char *function, bool required)
| Returns a function pointer to a named function in a library. More...
template<typename FunctionType >
FunctionType * | GetFunction (const wchar_t *library, const char *function, bool required)
| Returns a function pointer to a named function in a library. More...

## Variables

const char | kNativeReadFunctionName [] = "read"
| The name of the native read function used by ReadFile(). More...
const char | kNativeWriteFunctionName [] = "write"
| The name of the native write function used by WriteFile(). More...

## Detailed Description

The internal namespace, not for public use.

## Function Documentation

## AlignedAllocate()

void * crashpad::internal::AlignedAllocate | ( | size_t | alignment,
|  | size_t | size
| ) |  |

Allocates memory with the specified alignment constraint.

This function wraps `posix_memalign()` or `_aligned_malloc()`. Memory allocated by this function must be released by AlignFree().

## AlignedFree()

void crashpad::internal::AlignedFree | ( | void * | pointer | ) |

Frees memory allocated by AlignedAllocate().

This function wraps `free()` or `_aligned_free()`.

## GetFunction()

template<typename FunctionType >

FunctionType* crashpad::internal::GetFunction | ( | const wchar_t * | library,
|  | const char * | function,
|  | bool | required
| ) |  |

Returns a function pointer to a named function in a library.

Do not call this directly, use the GET_FUNCTION() or GET_FUNCTION_REQUIRED() macros instead.

This accesses library by calling `LoadLibrary()` and is subject to the same restrictions as that function. Notably, it can’t be used from a `DllMain()` entry point.

Parameters

  [in] | library | The library to search in.
  [in] | function | The function to search for. If a leading `::` is present, it will be stripped.
  [in] | required | If `true`, require the function to resolve by `DCHECK`.

Returns
  A pointer to the requested function on success. If required is `true`, triggers a `DCHECK` assertion on failure, otherwise, `nullptr` on failure.

## GetFunctionInternal()

FARPROC crashpad::internal::GetFunctionInternal | ( | const wchar_t * | library,
|  | const char * | function,
|  | bool | required
| ) |  |

Returns a function pointer to a named function in a library.

Do not call this directly, use the GET_FUNCTION() or GET_FUNCTION_REQUIRED() macros instead.

This accesses library by calling `LoadLibrary()` and is subject to the same restrictions as that function. Notably, it can’t be used from a `DllMain()` entry point.

Parameters

  [in] | library | The library to search in.
  [in] | function | The function to search for. If a leading `::` is present, it will be stripped.
  [in] | required | If `true`, require the function to resolve by `DCHECK`.

Returns
  A pointer to the requested function on success. If required is `true`, triggers a `DCHECK` assertion on failure, otherwise, `nullptr` on failure.

## InitializeCPUContextX86()

void crashpad::internal::InitializeCPUContextX86 | ( | CPUContextX86 * | context,
|  | thread_state_flavor_t | flavor,
|  | ConstThreadState | state,
|  | mach_msg_type_number_t | state_count,
|  | const x86_thread_state32_t * | x86_thread_state32,
|  | const x86_float_state32_t * | x86_float_state32,
|  | const x86_debug_state32_t * | x86_debug_state32
| ) |  |

Initializes a CPUContextX86 structure from native context structures on macOS.

flavor, state, and state_count may be supplied by exception handlers in order for the context parameter to be initialized by the thread state received by the exception handler to the extent possible. In that case, whatever thread state specified by these three parameters will supersede x86_thread_state32, x86_float_state32, or x86_debug_state32. If thread state in this format is not available, flavor may be set to `THREAD_STATE_NONE`, and all of x86_thread_state32, x86_float_state32, and x86_debug_state32 will be honored.

If flavor, state, and state_count are provided but do not contain valid values, a message will be logged and their values will be ignored as though flavor were specified as `THREAD_STATE_NONE`.

Parameters

  [out] | context | The CPUContextX86 structure to initialize.
  [in] | flavor | The native thread state flavor of state. This may be `x86_THREAD_STATE32`, `x86_FLOAT_STATE32`, `x86_DEBUG_STATE32`, `x86_THREAD_STATE`, `x86_FLOAT_STATE`, or `x86_DEBUG_STATE`. It may also be `THREAD_STATE_NONE` if state is not supplied (and is `nullptr`).
  [in] | state | The native thread state, which may be a casted pointer to `x86_thread_state32_t`, `x86_float_state32_t`, `x86_debug_state32_t`, `x86_thread_state`, `x86_float_state`, or `x86_debug_state`. This parameter may be `nullptr` to not supply this data, in which case flavor must be `THREAD_STATE_NONE`. If a “universal” structure is used, it must carry 32-bit state data of the correct type.
  [in] | state_count | The number of `natural_t`-sized (`int`-sized) units in state. This may be 0 if state is `nullptr`.
  [in] | x86_thread_state32 | The state of the thread’s integer registers.
  [in] | x86_float_state32 | The state of the thread’s floating-point registers.
  [in] | x86_debug_state32 | The state of the thread’s debug registers.

## InitializeCPUContextX86_64()

void crashpad::internal::InitializeCPUContextX86_64 | ( | CPUContextX86_64 * | context,
|  | thread_state_flavor_t | flavor,
|  | ConstThreadState | state,
|  | mach_msg_type_number_t | state_count,
|  | const x86_thread_state64_t * | x86_thread_state64,
|  | const x86_float_state64_t * | x86_float_state64,
|  | const x86_debug_state64_t * | x86_debug_state64
| ) |  |

Initializes a CPUContextX86_64 structure from native context structures on macOS.

flavor, state, and state_count may be supplied by exception handlers in order for the context parameter to be initialized by the thread state received by the exception handler to the extent possible. In that case, whatever thread state specified by these three parameters will supersede x86_thread_state64, x86_float_state64, or x86_debug_state64. If thread state in this format is not available, flavor may be set to `THREAD_STATE_NONE`, and all of x86_thread_state64, x86_float_state64, and x86_debug_state64 will be honored.

If flavor, state, and state_count are provided but do not contain valid values, a message will be logged and their values will be ignored as though flavor were specified as `THREAD_STATE_NONE`.

Parameters

  [out] | context | The CPUContextX86_64 structure to initialize.
  [in] | flavor | The native thread state flavor of state. This may be `x86_THREAD_STATE64`, `x86_FLOAT_STATE64`, `x86_DEBUG_STATE64`, `x86_THREAD_STATE`, `x86_FLOAT_STATE`, or `x86_DEBUG_STATE`. It may also be `THREAD_STATE_NONE` if state is not supplied (and is `nullptr`).
  [in] | state | The native thread state, which may be a casted pointer to `x86_thread_state64_t`, `x86_float_state64_t`, `x86_debug_state64_t`, `x86_thread_state`, `x86_float_state`, or `x86_debug_state`. This parameter may be `nullptr` to not supply this data, in which case flavor must be `THREAD_STATE_NONE`. If a “universal” structure is used, it must carry 64-bit state data of the correct type.
  [in] | state_count | The number of `int`-sized units in state. This may be 0 if state is `nullptr`.
  [in] | x86_thread_state64 | The state of the thread’s integer registers.
  [in] | x86_float_state64 | The state of the thread’s floating-point registers.
  [in] | x86_debug_state64 | The state of the thread’s debug registers.

## MinidumpMiscInfoDebugBuildString()

std::string crashpad::internal::MinidumpMiscInfoDebugBuildString | ( |  | ) |

Returns the string to set in MINIDUMP_MISC_INFO_4::DbgBldStr.

dbghelp produces strings like `"dbghelp.i386,6.3.9600.16520"` and `"dbghelp.amd64,6.3.9600.16520"`. This function mimics that format, and adds the OS that wrote the minidump along with any relevant platform-specific data describing the compilation environment.

This function is an implementation detail of MinidumpMiscInfoWriter::InitializeFromSnapshot() and is only exposed for testing purposes.

## NativeWriteFile()

FileOperationResult crashpad::internal::NativeWriteFile | ( | FileHandle | file,
|  | const void * | buffer,
|  | size_t | size
| ) |  |

Writes to a file, retrying when interrupted on POSIX.

Fewer than size bytes may be written to file. This can happen if the underlying write operation returns before writing the entire buffer, or if the buffer is too large to write in a single operation, possibly due to a limitation of a data type used to express the number of bytes written.

This function adapts native write operations for uniform use by WriteFile(). This function should only be called by WriteFile(). Other code should call WriteFile() or another function that wraps WriteFile().

Parameters

  [in] | file | The file to write to.
  [in] | buffer | A buffer containing data to be written.
  [in] | size | The number of bytes from buffer to write.

Returns
  The number of bytes actually written from buffer to file on success. `-1` on error, with `errno` or `GetLastError()` set appropriately.

## ReadMinidumpSimpleStringDictionary()

bool crashpad::internal::ReadMinidumpSimpleStringDictionary | ( | FileReaderInterface * | file_reader,
|  | const MINIDUMP_LOCATION_DESCRIPTOR & | location,
|  | std::map< std::string, std::string > * | dictionary
| ) |  |

Reads a MinidumpSimpleStringDictionary from a minidump file location in file_reader, and returns it in dictionary.

Returns
  `true` on success, with dictionary set by replacing its contents. `false` on failure, with a message logged.

## ReadMinidumpStringList()

bool crashpad::internal::ReadMinidumpStringList | ( | FileReaderInterface * | file_reader,
|  | const MINIDUMP_LOCATION_DESCRIPTOR & | location,
|  | std::vector< std::string > * | list
| ) |  |

Reads a list of MinidumpUTF8String objects in a MinidumpRVAList from a minidump file location in file_reader, and returns it in list.

Returns
  `true` on success, with list set by replacing its contents. `false` on failure, with a message logged.

## ReadMinidumpUTF8String()

bool crashpad::internal::ReadMinidumpUTF8String | ( | FileReaderInterface * | file_reader,
|  | RVA | rva,
|  | std::string * | string
| ) |  |

Reads a MinidumpUTF8String from a minidump file at offset rva in file_reader, and returns it in string.

Returns
  `true` on success, with string set. `false` on failure, with a message logged.

## Variable Documentation

## kNativeReadFunctionName

const char crashpad::internal::kNativeReadFunctionName = "read"

The name of the native read function used by ReadFile().

This value may be useful for logging.

See also
  kNativeWriteFunctionName

## kNativeWriteFunctionName

const char crashpad::internal::kNativeWriteFunctionName = "write"

The name of the native write function used by WriteFile().

This value may be useful for logging.

See also
  kNativeReadFunctionName