1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/crashreporter/google-breakpad/src/client/minidump_file_writer.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,272 @@
1.4 +// Copyright (c) 2006, Google Inc.
1.5 +// All rights reserved.
1.6 +//
1.7 +// Redistribution and use in source and binary forms, with or without
1.8 +// modification, are permitted provided that the following conditions are
1.9 +// met:
1.10 +//
1.11 +// * Redistributions of source code must retain the above copyright
1.12 +// notice, this list of conditions and the following disclaimer.
1.13 +// * Redistributions in binary form must reproduce the above
1.14 +// copyright notice, this list of conditions and the following disclaimer
1.15 +// in the documentation and/or other materials provided with the
1.16 +// distribution.
1.17 +// * Neither the name of Google Inc. nor the names of its
1.18 +// contributors may be used to endorse or promote products derived from
1.19 +// this software without specific prior written permission.
1.20 +//
1.21 +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.22 +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.23 +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.24 +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
1.25 +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.26 +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.27 +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
1.28 +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1.29 +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1.30 +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1.31 +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.32 +
1.33 +// minidump_file_writer.h: Implements file-based minidump generation. It's
1.34 +// intended to be used with the Google Breakpad open source crash handling
1.35 +// project.
1.36 +
1.37 +#ifndef CLIENT_MINIDUMP_FILE_WRITER_H__
1.38 +#define CLIENT_MINIDUMP_FILE_WRITER_H__
1.39 +
1.40 +#include <string>
1.41 +
1.42 +#include "google_breakpad/common/minidump_format.h"
1.43 +
1.44 +namespace google_breakpad {
1.45 +
1.46 +class UntypedMDRVA;
1.47 +template<typename MDType> class TypedMDRVA;
1.48 +
1.49 +// The user of this class can Open() a file and add minidump streams, data, and
1.50 +// strings using the definitions in minidump_format.h. Since this class is
1.51 +// expected to be used in a situation where the current process may be
1.52 +// damaged, it will not allocate heap memory.
1.53 +// Sample usage:
1.54 +// MinidumpFileWriter writer;
1.55 +// writer.Open("/tmp/minidump.dmp");
1.56 +// TypedMDRVA<MDRawHeader> header(&writer_);
1.57 +// header.Allocate();
1.58 +// header->get()->signature = MD_HEADER_SIGNATURE;
1.59 +// :
1.60 +// writer.Close();
1.61 +//
1.62 +// An alternative is to use SetFile and provide a file descriptor:
1.63 +// MinidumpFileWriter writer;
1.64 +// writer.SetFile(minidump_fd);
1.65 +// TypedMDRVA<MDRawHeader> header(&writer_);
1.66 +// header.Allocate();
1.67 +// header->get()->signature = MD_HEADER_SIGNATURE;
1.68 +// :
1.69 +// writer.Close();
1.70 +
1.71 +class MinidumpFileWriter {
1.72 +public:
1.73 + // Invalid MDRVA (Minidump Relative Virtual Address)
1.74 + // returned on failed allocation
1.75 + static const MDRVA kInvalidMDRVA;
1.76 +
1.77 + MinidumpFileWriter();
1.78 + ~MinidumpFileWriter();
1.79 +
1.80 + // Open |path| as the destination of the minidump data. Any existing file
1.81 + // will be overwritten.
1.82 + // Return true on success, or false on failure.
1.83 + bool Open(const char *path);
1.84 +
1.85 + // Sets the file descriptor |file| as the destination of the minidump data.
1.86 + // Can be used as an alternative to Open() when a file descriptor is
1.87 + // available.
1.88 + // Note that |fd| is not closed when the instance of MinidumpFileWriter is
1.89 + // destroyed.
1.90 + void SetFile(const int file);
1.91 +
1.92 + // Close the current file (that was either created when Open was called, or
1.93 + // specified with SetFile).
1.94 + // Return true on success, or false on failure.
1.95 + bool Close();
1.96 +
1.97 + // Copy the contents of |str| to a MDString and write it to the file.
1.98 + // |str| is expected to be either UTF-16 or UTF-32 depending on the size
1.99 + // of wchar_t.
1.100 + // Maximum |length| of characters to copy from |str|, or specify 0 to use the
1.101 + // entire NULL terminated string. Copying will stop at the first NULL.
1.102 + // |location| the allocated location
1.103 + // Return true on success, or false on failure
1.104 + bool WriteString(const wchar_t *str, unsigned int length,
1.105 + MDLocationDescriptor *location);
1.106 +
1.107 + // Same as above, except with |str| as a UTF-8 string
1.108 + bool WriteString(const char *str, unsigned int length,
1.109 + MDLocationDescriptor *location);
1.110 +
1.111 + // Write |size| bytes starting at |src| into the current position.
1.112 + // Return true on success and set |output| to position, or false on failure
1.113 + bool WriteMemory(const void *src, size_t size, MDMemoryDescriptor *output);
1.114 +
1.115 + // Copies |size| bytes from |src| to |position|
1.116 + // Return true on success, or false on failure
1.117 + bool Copy(MDRVA position, const void *src, ssize_t size);
1.118 +
1.119 + // Return the current position for writing to the minidump
1.120 + inline MDRVA position() const { return position_; }
1.121 +
1.122 + private:
1.123 + friend class UntypedMDRVA;
1.124 +
1.125 + // Allocates an area of |size| bytes.
1.126 + // Returns the position of the allocation, or kInvalidMDRVA if it was
1.127 + // unable to allocate the bytes.
1.128 + MDRVA Allocate(size_t size);
1.129 +
1.130 + // The file descriptor for the output file.
1.131 + int file_;
1.132 +
1.133 + // Whether |file_| should be closed when the instance is destroyed.
1.134 + bool close_file_when_destroyed_;
1.135 +
1.136 + // Current position in buffer
1.137 + MDRVA position_;
1.138 +
1.139 + // Current allocated size
1.140 + size_t size_;
1.141 +
1.142 + // Copy |length| characters from |str| to |mdstring|. These are distinct
1.143 + // because the underlying MDString is a UTF-16 based string. The wchar_t
1.144 + // variant may need to create a MDString that has more characters than the
1.145 + // source |str|, whereas the UTF-8 variant may coalesce characters to form
1.146 + // a single UTF-16 character.
1.147 + bool CopyStringToMDString(const wchar_t *str, unsigned int length,
1.148 + TypedMDRVA<MDString> *mdstring);
1.149 + bool CopyStringToMDString(const char *str, unsigned int length,
1.150 + TypedMDRVA<MDString> *mdstring);
1.151 +
1.152 + // The common templated code for writing a string
1.153 + template <typename CharType>
1.154 + bool WriteStringCore(const CharType *str, unsigned int length,
1.155 + MDLocationDescriptor *location);
1.156 +};
1.157 +
1.158 +// Represents an untyped allocated chunk
1.159 +class UntypedMDRVA {
1.160 + public:
1.161 + explicit UntypedMDRVA(MinidumpFileWriter *writer)
1.162 + : writer_(writer),
1.163 + position_(writer->position()),
1.164 + size_(0) {}
1.165 +
1.166 + // Allocates |size| bytes. Must not call more than once.
1.167 + // Return true on success, or false on failure
1.168 + bool Allocate(size_t size);
1.169 +
1.170 + // Returns the current position or kInvalidMDRVA if allocation failed
1.171 + inline MDRVA position() const { return position_; }
1.172 +
1.173 + // Number of bytes allocated
1.174 + inline size_t size() const { return size_; }
1.175 +
1.176 + // Return size and position
1.177 + inline MDLocationDescriptor location() const {
1.178 + MDLocationDescriptor location = { static_cast<uint32_t>(size_),
1.179 + position_ };
1.180 + return location;
1.181 + }
1.182 +
1.183 + // Copy |size| bytes starting at |src| into the minidump at |position|
1.184 + // Return true on success, or false on failure
1.185 + bool Copy(MDRVA position, const void *src, size_t size);
1.186 +
1.187 + // Copy |size| bytes from |src| to the current position
1.188 + inline bool Copy(const void *src, size_t size) {
1.189 + return Copy(position_, src, size);
1.190 + }
1.191 +
1.192 + protected:
1.193 + // Writer we associate with
1.194 + MinidumpFileWriter *writer_;
1.195 +
1.196 + // Position of the start of the data
1.197 + MDRVA position_;
1.198 +
1.199 + // Allocated size
1.200 + size_t size_;
1.201 +};
1.202 +
1.203 +// Represents a Minidump object chunk. Additional memory can be allocated at
1.204 +// the end of the object as a:
1.205 +// - single allocation
1.206 +// - Array of MDType objects
1.207 +// - A MDType object followed by an array
1.208 +template<typename MDType>
1.209 +class TypedMDRVA : public UntypedMDRVA {
1.210 + public:
1.211 + // Constructs an unallocated MDRVA
1.212 + explicit TypedMDRVA(MinidumpFileWriter *writer)
1.213 + : UntypedMDRVA(writer),
1.214 + data_(),
1.215 + allocation_state_(UNALLOCATED) {}
1.216 +
1.217 + inline ~TypedMDRVA() {
1.218 + // Ensure that the data_ object is written out
1.219 + if (allocation_state_ != ARRAY)
1.220 + Flush();
1.221 + }
1.222 +
1.223 + // Address of object data_ of MDType. This is not declared const as the
1.224 + // typical usage will be to access the underlying |data_| object as to
1.225 + // alter its contents.
1.226 + MDType *get() { return &data_; }
1.227 +
1.228 + // Allocates minidump_size<MDType>::size() bytes.
1.229 + // Must not call more than once.
1.230 + // Return true on success, or false on failure
1.231 + bool Allocate();
1.232 +
1.233 + // Allocates minidump_size<MDType>::size() + |additional| bytes.
1.234 + // Must not call more than once.
1.235 + // Return true on success, or false on failure
1.236 + bool Allocate(size_t additional);
1.237 +
1.238 + // Allocate an array of |count| elements of MDType.
1.239 + // Must not call more than once.
1.240 + // Return true on success, or false on failure
1.241 + bool AllocateArray(size_t count);
1.242 +
1.243 + // Allocate an array of |count| elements of |size| after object of MDType
1.244 + // Must not call more than once.
1.245 + // Return true on success, or false on failure
1.246 + bool AllocateObjectAndArray(size_t count, size_t size);
1.247 +
1.248 + // Copy |item| to |index|
1.249 + // Must have been allocated using AllocateArray().
1.250 + // Return true on success, or false on failure
1.251 + bool CopyIndex(unsigned int index, MDType *item);
1.252 +
1.253 + // Copy |size| bytes starting at |str| to |index|
1.254 + // Must have been allocated using AllocateObjectAndArray().
1.255 + // Return true on success, or false on failure
1.256 + bool CopyIndexAfterObject(unsigned int index, const void *src, size_t size);
1.257 +
1.258 + // Write data_
1.259 + bool Flush();
1.260 +
1.261 + private:
1.262 + enum AllocationState {
1.263 + UNALLOCATED = 0,
1.264 + SINGLE_OBJECT,
1.265 + ARRAY,
1.266 + SINGLE_OBJECT_WITH_ARRAY
1.267 + };
1.268 +
1.269 + MDType data_;
1.270 + AllocationState allocation_state_;
1.271 +};
1.272 +
1.273 +} // namespace google_breakpad
1.274 +
1.275 +#endif // CLIENT_MINIDUMP_FILE_WRITER_H__
