// Copyright 2021 The Crashpad Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef CRASHPAD_UTIL_IOS_IOS_INTERMEDIATE_DUMP_WRITER_H_
#define CRASHPAD_UTIL_IOS_IOS_INTERMEDIATE_DUMP_WRITER_H_
#include <sys/types.h>
#include "base/files/file_path.h"
#include "util/ios/ios_intermediate_dump_format.h"
namespace crashpad {
namespace internal {
//! \brief Wrapper class for writing intermediate dump file.
//!
//! Due to the limitations of in-process handling, an intermediate dump file is
//! written during exceptions. The data is streamed to a file using only
//! in-process safe methods.
//!
//! The file format is similar to binary JSON, supporting keyed properties, maps
//! and arrays.
//! - Property [key:int, length:int, value:intarray]
//! - StartMap [key:int], followed by repeating Properties until EndMap
//! - StartArray [key:int], followed by repeating Maps until EndArray
//! - EndMap, EndArray, EndDocument
//!
//! Similar to JSON, maps can contain other maps, arrays and properties.
//!
//! Note: All methods are `RUNS-DURING-CRASH`.
class IOSIntermediateDumpWriter final {
public:
IOSIntermediateDumpWriter() : buffer_occupied_(0), fd_(-1) {}
IOSIntermediateDumpWriter(const IOSIntermediateDumpWriter&) = delete;
IOSIntermediateDumpWriter& operator=(const IOSIntermediateDumpWriter&) =
delete;
~IOSIntermediateDumpWriter();
//! \brief Command instructions for the intermediate dump reader.
enum class CommandType : uint8_t {
//! \brief Indicates a new map, followed by associated key.
kMapStart = 0x01,
//! \brief Indicates map is complete.
kMapEnd = 0x02,
//! \brief Indicates a new array, followed by associated key.
kArrayStart = 0x03,
//! \brief Indicates array is complete.
kArrayEnd = 0x04,
//! \brief Indicates a new property, followed by a key, length and value.
kProperty = 0x05,
//! \brief Indicates the start of the root map.
kRootMapStart = 0x06,
//! \brief Indicates the end of the root map, and that there is nothing left
//! to parse.
kRootMapEnd = 0x07,
};
//! \brief Open and lock an intermediate dump file. This is the only method
//! in the writer class that is generally run outside of a crash.
//!
//! The client must invoke `Close()` before this object is destroyed.
//!
//! \param[in] path The path to the intermediate dump.
//!
//! \return On success, returns `true`, otherwise returns `false`.
bool Open(const base::FilePath& path);
//! \brief Completes writing the intermediate dump file and releases the
//! file handle.
//!
//! \return On success, returns `true`, otherwise returns `false`.
bool Close();
//! \brief A scoped wrapper for calls to RootMapStart and RootMapEnd.
class ScopedRootMap {
public:
explicit ScopedRootMap(IOSIntermediateDumpWriter* writer)
: writer_(writer) {
writer->RootMapStart();
}
ScopedRootMap(const ScopedRootMap&) = delete;
ScopedRootMap& operator=(const ScopedRootMap&) = delete;
~ScopedRootMap() { writer_->RootMapEnd(); }
private:
IOSIntermediateDumpWriter* writer_;
};
//! \brief A scoped wrapper for calls to MapStart and MapEnd.
class ScopedMap {
public:
explicit ScopedMap(IOSIntermediateDumpWriter* writer,
IntermediateDumpKey key)
: writer_(writer) {
writer->MapStart(key);
}
ScopedMap(const ScopedMap&) = delete;
ScopedMap& operator=(const ScopedMap&) = delete;
~ScopedMap() { writer_->MapEnd(); }
private:
IOSIntermediateDumpWriter* writer_;
};
//! \brief A scoped wrapper for calls to ArrayMapStart and MapEnd.
class ScopedArrayMap {
public:
explicit ScopedArrayMap(IOSIntermediateDumpWriter* writer)
: writer_(writer) {
writer->ArrayMapStart();
}
ScopedArrayMap(const ScopedArrayMap&) = delete;
ScopedArrayMap& operator=(const ScopedArrayMap&) = delete;
~ScopedArrayMap() { writer_->MapEnd(); }
private:
IOSIntermediateDumpWriter* writer_;
};
//! \brief A scoped wrapper for calls to ArrayStart and ArrayEnd.
class ScopedArray {
public:
explicit ScopedArray(IOSIntermediateDumpWriter* writer,
IntermediateDumpKey key)
: writer_(writer) {
writer->ArrayStart(key);
}
ScopedArray(const ScopedArray&) = delete;
ScopedArray& operator=(const ScopedArray&) = delete;
~ScopedArray() { writer_->ArrayEnd(); }
private:
IOSIntermediateDumpWriter* writer_;
};
//! \return The `true` if able to AddPropertyInternal the \a key \a value
//! \a count tuple.
template <typename T>
bool AddProperty(IntermediateDumpKey key, const T* value, size_t count = 1) {
return AddPropertyInternal(
key, reinterpret_cast<const char*>(value), count * sizeof(T));
}
//! \return The `true` if able to AddPropertyInternal the \a key \a value
//! \a count tuple.
bool AddPropertyBytes(IntermediateDumpKey key,
const void* value,
size_t value_length) {
return AddPropertyInternal(
key, reinterpret_cast<const char*>(value), value_length);
}
//! \return `true` if able to vm_read a string of \a value and write a
//! kProperty command with the \a key \a value up to a NUL byte.
//! The string cannot be longer than \a max_length with a maximum string
//! length of 1024.
bool AddPropertyCString(IntermediateDumpKey key,
size_t max_length,
const char* value);
private:
//! \return `true` if able to vm_read_overwrite \a value into
//! \a buffer while only reading one page at a time up to a NUL byte.
//! Sets the final length of \a buffer to \a string_length.
//! Returns `false` if unable to vm_read \a value or when no NUL byte can
//! be found within /a max_length (unterminated).
bool ReadCStringInternal(const char* value,
char* buffer,
size_t max_length,
size_t* string_length);
//! \return `true` if able to vm_read \a value \a count and write a
//! kProperty command with the \a key \a value \a count tuple.
bool AddPropertyInternal(IntermediateDumpKey key,
const char* value,
size_t value_length);
//! \return `true` if able to write a kArrayStart command with the \a key.
bool ArrayStart(IntermediateDumpKey key);
//! \return `true` if able to write a kMapStart command with the \a key.
bool MapStart(IntermediateDumpKey key);
//! \return `true` if able to write a kMapStart command.
bool ArrayMapStart();
//! \return `true` if able to write a kArrayEnd command.
bool ArrayEnd();
//! \return `true` if able to write a kMapEnd command.
bool MapEnd();
//! \return `true` if able to write a kRootMapStart command.
bool RootMapStart();
//! \return `true` if able to write a kRootMapEnd command.
bool RootMapEnd();
//! \return `true` if able to write a kProperty command with the \a key
//! \a value \a value_length tuple.
bool Property(IntermediateDumpKey key,
const void* value,
size_t value_length);
//! \return `true` if able to write \a data up to \a size. The \a data might
//! not be written to fd_ until `buffer_` is full or the writer is
//! closed. All writes will be 4096 bytes (the size of your kBufferSize)
//! except for the final flush, which might be partial.
bool BufferedWrite(const void* data, size_t size);
//! \return `true` if able to write `buffer_` up to `buffer_occupied_`.
bool FlushWriteBuffer();
//! \brief The maximum size of the write buffer.
static constexpr size_t kBufferSize = 4096;
//! \brief The write data buffer and amount of that buffer occupied with data
//! to be written.
char buffer_[kBufferSize];
size_t buffer_occupied_;
int fd_;
};
} // namespace internal
} // namespace crashpad
#endif // CRASHPAD_UTIL_IOS_IOS_INTERMEDIATE_DUMP_WRITER_H_
Codebase Browser
chromium