1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 /** 32 * @file android/crash_detail.h 33 * @brief Attach extra information to android crashes. 34 */ 35 36 #include <sys/cdefs.h> 37 38 #include <stddef.h> 39 40 __BEGIN_DECLS 41 42 typedef struct crash_detail_t crash_detail_t; 43 44 /** 45 * Register a new buffer to get logged into tombstones for crashes. 46 * 47 * It will be added to both the tombstone proto in the crash_detail field, and 48 * in the tombstone text format. 49 * 50 * Tombstone proto definition: 51 * https://cs.android.com/android/platform/superproject/main/+/main:system/core/debuggerd/proto/tombstone.proto 52 * 53 * An app can get hold of these for any `REASON_CRASH_NATIVE` instance of 54 * `android.app.ApplicationExitInfo`. 55 * 56 * https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream() 57 58 * The lifetime of name and data has to be valid until the program crashes, or until 59 * android_crash_detail_unregister is called. 60 * 61 * Example usage: 62 * const char* stageName = "garbage_collection"; 63 * crash_detail_t* cd = android_crash_detail_register("stage", stageName, strlen(stageName)); 64 * do_garbage_collection(); 65 * android_crash_detail_unregister(cd); 66 * 67 * If this example crashes in do_garbage_collection, a line will show up in the textual representation of the tombstone: 68 * Extra crash detail: stage: 'garbage_collection' 69 * 70 * Introduced in API 35. 71 * 72 * \param name identifying name for this extra data. 73 * this should generally be a human-readable UTF-8 string, but we are treating 74 * it as arbitrary bytes because it could be corrupted by the crash. 75 * \param name_size number of bytes of the buffer pointed to by name 76 * \param data a buffer containing the extra detail bytes, if null the crash detail 77 * is disabled until android_crash_detail_replace_data replaces it with 78 * a non-null pointer. 79 * \param data_size number of bytes of the buffer pointed to by data 80 * 81 * \return a handle to the extra crash detail. 82 */ 83 84 #if __BIONIC_AVAILABILITY_GUARD(35) 85 crash_detail_t* _Nullable android_crash_detail_register( 86 const void* _Nonnull name, size_t name_size, const void* _Nullable data, size_t data_size) __INTRODUCED_IN(35); 87 88 /** 89 * Unregister crash detail from being logged into tombstones. 90 * 91 * After this function returns, the lifetime of the objects crash_detail was 92 * constructed from no longer needs to be valid. 93 * 94 * Introduced in API 35. 95 * 96 * \param crash_detail the crash_detail that should be removed. 97 */ 98 void android_crash_detail_unregister(crash_detail_t* _Nonnull crash_detail) __INTRODUCED_IN(35); 99 100 /** 101 * Replace data of crash detail. 102 * 103 * This is more efficient than using android_crash_detail_unregister followed by 104 * android_crash_detail_register. If you very frequently need to swap out the data, 105 * you can hold onto the crash_detail. 106 * 107 * Introduced in API 35. 108 * 109 * \param data the new buffer containing the extra detail bytes, or null to disable until 110 * android_crash_detail_replace_data is called again with non-null data. 111 * \param data_size the number of bytes of the buffer pointed to by data. 112 */ 113 void android_crash_detail_replace_data(crash_detail_t* _Nonnull crash_detail, const void* _Nullable data, size_t data_size) __INTRODUCED_IN(35); 114 115 /** 116 * Replace name of crash detail. 117 * 118 * This is more efficient than using android_crash_detail_unregister followed by 119 * android_crash_detail_register. If you very frequently need to swap out the name, 120 * you can hold onto the crash_detail. 121 * 122 * Introduced in API 35. 123 * 124 * \param name identifying name for this extra data. 125 * \param name_size number of bytes of the buffer pointed to by name 126 */ 127 void android_crash_detail_replace_name(crash_detail_t* _Nonnull crash_detail, const void* _Nonnull name, size_t name_size) __INTRODUCED_IN(35); 128 #endif /* __BIONIC_AVAILABILITY_GUARD(35) */ 129 130 131 __END_DECLS 132