michael@0: // Copyright (c) 2006, Google Inc.
michael@0: // All rights reserved.
michael@0: //
michael@0: // Redistribution and use in source and binary forms, with or without
michael@0: // modification, are permitted provided that the following conditions are
michael@0: // met:
michael@0: //
michael@0: //     * Redistributions of source code must retain the above copyright
michael@0: // notice, this list of conditions and the following disclaimer.
michael@0: //     * Redistributions in binary form must reproduce the above
michael@0: // copyright notice, this list of conditions and the following disclaimer
michael@0: // in the documentation and/or other materials provided with the
michael@0: // distribution.
michael@0: //     * Neither the name of Google Inc. nor the names of its
michael@0: // contributors may be used to endorse or promote products derived from
michael@0: // this software without specific prior written permission.
michael@0: //
michael@0: // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
michael@0: // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
michael@0: // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
michael@0: // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
michael@0: // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@0: // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@0: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
michael@0: // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
michael@0: // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
michael@0: // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
michael@0: // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
michael@0: 
michael@0: // minidump_file_writer.h:  Implements file-based minidump generation.  It's
michael@0: // intended to be used with the Google Breakpad open source crash handling
michael@0: // project.
michael@0: 
michael@0: #ifndef CLIENT_MINIDUMP_FILE_WRITER_H__
michael@0: #define CLIENT_MINIDUMP_FILE_WRITER_H__
michael@0: 
michael@0: #include <string>
michael@0: 
michael@0: #include "google_breakpad/common/minidump_format.h"
michael@0: 
michael@0: namespace google_breakpad {
michael@0: 
michael@0: class UntypedMDRVA;
michael@0: template<typename MDType> class TypedMDRVA;
michael@0: 
michael@0: // The user of this class can Open() a file and add minidump streams, data, and
michael@0: // strings using the definitions in minidump_format.h.  Since this class is
michael@0: // expected to be used in a situation where the current process may be
michael@0: // damaged, it will not allocate heap memory.
michael@0: // Sample usage:
michael@0: // MinidumpFileWriter writer;
michael@0: // writer.Open("/tmp/minidump.dmp");
michael@0: // TypedMDRVA<MDRawHeader> header(&writer_);
michael@0: // header.Allocate();
michael@0: // header->get()->signature = MD_HEADER_SIGNATURE;
michael@0: //  :
michael@0: // writer.Close();
michael@0: //
michael@0: // An alternative is to use SetFile and provide a file descriptor:
michael@0: // MinidumpFileWriter writer;
michael@0: // writer.SetFile(minidump_fd);
michael@0: // TypedMDRVA<MDRawHeader> header(&writer_);
michael@0: // header.Allocate();
michael@0: // header->get()->signature = MD_HEADER_SIGNATURE;
michael@0: //  :
michael@0: // writer.Close();
michael@0: 
michael@0: class MinidumpFileWriter {
michael@0: public:
michael@0:   // Invalid MDRVA (Minidump Relative Virtual Address)
michael@0:   // returned on failed allocation
michael@0:   static const MDRVA kInvalidMDRVA;
michael@0: 
michael@0:   MinidumpFileWriter();
michael@0:   ~MinidumpFileWriter();
michael@0: 
michael@0:   // Open |path| as the destination of the minidump data.  Any existing file
michael@0:   // will be overwritten.
michael@0:   // Return true on success, or false on failure.
michael@0:   bool Open(const char *path);
michael@0: 
michael@0:   // Sets the file descriptor |file| as the destination of the minidump data.
michael@0:   // Can be used as an alternative to Open() when a file descriptor is
michael@0:   // available.
michael@0:   // Note that |fd| is not closed when the instance of MinidumpFileWriter is
michael@0:   // destroyed.
michael@0:   void SetFile(const int file);
michael@0: 
michael@0:   // Close the current file (that was either created when Open was called, or
michael@0:   // specified with SetFile).
michael@0:   // Return true on success, or false on failure.
michael@0:   bool Close();
michael@0: 
michael@0:   // Copy the contents of |str| to a MDString and write it to the file.
michael@0:   // |str| is expected to be either UTF-16 or UTF-32 depending on the size
michael@0:   // of wchar_t.
michael@0:   // Maximum |length| of characters to copy from |str|, or specify 0 to use the
michael@0:   // entire NULL terminated string.  Copying will stop at the first NULL.
michael@0:   // |location| the allocated location
michael@0:   // Return true on success, or false on failure
michael@0:   bool WriteString(const wchar_t *str, unsigned int length,
michael@0:                    MDLocationDescriptor *location);
michael@0: 
michael@0:   // Same as above, except with |str| as a UTF-8 string
michael@0:   bool WriteString(const char *str, unsigned int length,
michael@0:                    MDLocationDescriptor *location);
michael@0: 
michael@0:   // Write |size| bytes starting at |src| into the current position.
michael@0:   // Return true on success and set |output| to position, or false on failure
michael@0:   bool WriteMemory(const void *src, size_t size, MDMemoryDescriptor *output);
michael@0: 
michael@0:   // Copies |size| bytes from |src| to |position|
michael@0:   // Return true on success, or false on failure
michael@0:   bool Copy(MDRVA position, const void *src, ssize_t size);
michael@0: 
michael@0:   // Return the current position for writing to the minidump
michael@0:   inline MDRVA position() const { return position_; }
michael@0: 
michael@0:  private:
michael@0:   friend class UntypedMDRVA;
michael@0: 
michael@0:   // Allocates an area of |size| bytes.
michael@0:   // Returns the position of the allocation, or kInvalidMDRVA if it was
michael@0:   // unable to allocate the bytes.
michael@0:   MDRVA Allocate(size_t size);
michael@0: 
michael@0:   // The file descriptor for the output file.
michael@0:   int file_;
michael@0: 
michael@0:   // Whether |file_| should be closed when the instance is destroyed.
michael@0:   bool close_file_when_destroyed_;
michael@0: 
michael@0:   // Current position in buffer
michael@0:   MDRVA position_;
michael@0: 
michael@0:   // Current allocated size
michael@0:   size_t size_;
michael@0: 
michael@0:   // Copy |length| characters from |str| to |mdstring|.  These are distinct
michael@0:   // because the underlying MDString is a UTF-16 based string.  The wchar_t
michael@0:   // variant may need to create a MDString that has more characters than the
michael@0:   // source |str|, whereas the UTF-8 variant may coalesce characters to form
michael@0:   // a single UTF-16 character.
michael@0:   bool CopyStringToMDString(const wchar_t *str, unsigned int length,
michael@0:                             TypedMDRVA<MDString> *mdstring);
michael@0:   bool CopyStringToMDString(const char *str, unsigned int length,
michael@0:                             TypedMDRVA<MDString> *mdstring);
michael@0: 
michael@0:   // The common templated code for writing a string
michael@0:   template <typename CharType>
michael@0:   bool WriteStringCore(const CharType *str, unsigned int length,
michael@0:                        MDLocationDescriptor *location);
michael@0: };
michael@0: 
michael@0: // Represents an untyped allocated chunk
michael@0: class UntypedMDRVA {
michael@0:  public:
michael@0:   explicit UntypedMDRVA(MinidumpFileWriter *writer)
michael@0:       : writer_(writer),
michael@0:         position_(writer->position()),
michael@0:         size_(0) {}
michael@0: 
michael@0:   // Allocates |size| bytes.  Must not call more than once.
michael@0:   // Return true on success, or false on failure
michael@0:   bool Allocate(size_t size);
michael@0: 
michael@0:   // Returns the current position or kInvalidMDRVA if allocation failed
michael@0:   inline MDRVA position() const { return position_; }
michael@0: 
michael@0:   // Number of bytes allocated
michael@0:   inline size_t size() const { return size_; }
michael@0: 
michael@0:   // Return size and position
michael@0:   inline MDLocationDescriptor location() const {
michael@0:     MDLocationDescriptor location = { static_cast<uint32_t>(size_),
michael@0:                                       position_ };
michael@0:     return location;
michael@0:   }
michael@0: 
michael@0:   // Copy |size| bytes starting at |src| into the minidump at |position|
michael@0:   // Return true on success, or false on failure
michael@0:   bool Copy(MDRVA position, const void *src, size_t size);
michael@0: 
michael@0:   // Copy |size| bytes from |src| to the current position
michael@0:   inline bool Copy(const void *src, size_t size) {
michael@0:     return Copy(position_, src, size);
michael@0:   }
michael@0: 
michael@0:  protected:
michael@0:   // Writer we associate with
michael@0:   MinidumpFileWriter *writer_;
michael@0: 
michael@0:   // Position of the start of the data
michael@0:   MDRVA position_;
michael@0: 
michael@0:   // Allocated size
michael@0:   size_t size_;
michael@0: };
michael@0: 
michael@0: // Represents a Minidump object chunk.  Additional memory can be allocated at
michael@0: // the end of the object as a:
michael@0: // - single allocation
michael@0: // - Array of MDType objects
michael@0: // - A MDType object followed by an array
michael@0: template<typename MDType>
michael@0: class TypedMDRVA : public UntypedMDRVA {
michael@0:  public:
michael@0:   // Constructs an unallocated MDRVA
michael@0:   explicit TypedMDRVA(MinidumpFileWriter *writer)
michael@0:       : UntypedMDRVA(writer),
michael@0:         data_(),
michael@0:         allocation_state_(UNALLOCATED) {}
michael@0: 
michael@0:   inline ~TypedMDRVA() {
michael@0:     // Ensure that the data_ object is written out
michael@0:     if (allocation_state_ != ARRAY)
michael@0:       Flush();
michael@0:   }
michael@0: 
michael@0:   // Address of object data_ of MDType.  This is not declared const as the
michael@0:   // typical usage will be to access the underlying |data_| object as to
michael@0:   // alter its contents.
michael@0:   MDType *get() { return &data_; }
michael@0: 
michael@0:   // Allocates minidump_size<MDType>::size() bytes.
michael@0:   // Must not call more than once.
michael@0:   // Return true on success, or false on failure
michael@0:   bool Allocate();
michael@0: 
michael@0:   // Allocates minidump_size<MDType>::size() + |additional| bytes.
michael@0:   // Must not call more than once.
michael@0:   // Return true on success, or false on failure
michael@0:   bool Allocate(size_t additional);
michael@0: 
michael@0:   // Allocate an array of |count| elements of MDType.
michael@0:   // Must not call more than once.
michael@0:   // Return true on success, or false on failure
michael@0:   bool AllocateArray(size_t count);
michael@0: 
michael@0:   // Allocate an array of |count| elements of |size| after object of MDType
michael@0:   // Must not call more than once.
michael@0:   // Return true on success, or false on failure
michael@0:   bool AllocateObjectAndArray(size_t count, size_t size);
michael@0: 
michael@0:   // Copy |item| to |index|
michael@0:   // Must have been allocated using AllocateArray().
michael@0:   // Return true on success, or false on failure
michael@0:   bool CopyIndex(unsigned int index, MDType *item);
michael@0: 
michael@0:   // Copy |size| bytes starting at |str| to |index|
michael@0:   // Must have been allocated using AllocateObjectAndArray().
michael@0:   // Return true on success, or false on failure
michael@0:   bool CopyIndexAfterObject(unsigned int index, const void *src, size_t size);
michael@0: 
michael@0:   // Write data_
michael@0:   bool Flush();
michael@0: 
michael@0:  private:
michael@0:   enum AllocationState {
michael@0:     UNALLOCATED = 0,
michael@0:     SINGLE_OBJECT,
michael@0:     ARRAY,
michael@0:     SINGLE_OBJECT_WITH_ARRAY
michael@0:   };
michael@0: 
michael@0:   MDType data_;
michael@0:   AllocationState allocation_state_;
michael@0: };
michael@0: 
michael@0: }  // namespace google_breakpad
michael@0: 
michael@0: #endif  // CLIENT_MINIDUMP_FILE_WRITER_H__