1 // Copyright 2018 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // This file contains internal parts of the Abseil symbolizer. 16 // Do not depend on the anything in this file, it may change at anytime. 17 18 #ifndef ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_ 19 #define ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_ 20 21 #include <cstddef> 22 #include <cstdint> 23 24 #include "absl/base/config.h" 25 26 #ifdef ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE 27 #error ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE cannot be directly set 28 #elif defined(__ELF__) && defined(__GLIBC__) && !defined(__native_client__) && \ 29 !defined(__asmjs__) && !defined(__wasm__) 30 #define ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE 1 31 32 #include <elf.h> 33 #include <link.h> // For ElfW() macro. 34 #include <functional> 35 #include <string> 36 37 namespace absl { 38 ABSL_NAMESPACE_BEGIN 39 namespace debugging_internal { 40 41 // Iterates over all sections, invoking callback on each with the section name 42 // and the section header. 43 // 44 // Returns true on success; otherwise returns false in case of errors. 45 // 46 // This is not async-signal-safe. 47 bool ForEachSection(int fd, 48 const std::function<bool(const std::string& name, 49 const ElfW(Shdr) &)>& callback); 50 51 // Gets the section header for the given name, if it exists. Returns true on 52 // success. Otherwise, returns false. 53 bool GetSectionHeaderByName(int fd, const char *name, size_t name_len, 54 ElfW(Shdr) *out); 55 56 } // namespace debugging_internal 57 ABSL_NAMESPACE_END 58 } // namespace absl 59 60 #endif // ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE 61 62 namespace absl { 63 ABSL_NAMESPACE_BEGIN 64 namespace debugging_internal { 65 66 struct SymbolDecoratorArgs { 67 // The program counter we are getting symbolic name for. 68 const void *pc; 69 // 0 for main executable, load address for shared libraries. 70 ptrdiff_t relocation; 71 // Read-only file descriptor for ELF image covering "pc", 72 // or -1 if no such ELF image exists in /proc/self/maps. 73 int fd; 74 // Output buffer, size. 75 // Note: the buffer may not be empty -- default symbolizer may have already 76 // produced some output, and earlier decorators may have adorned it in 77 // some way. You are free to replace or augment the contents (within the 78 // symbol_buf_size limit). 79 char *const symbol_buf; 80 size_t symbol_buf_size; 81 // Temporary scratch space, size. 82 // Use that space in preference to allocating your own stack buffer to 83 // conserve stack. 84 char *const tmp_buf; 85 size_t tmp_buf_size; 86 // User-provided argument 87 void* arg; 88 }; 89 using SymbolDecorator = void (*)(const SymbolDecoratorArgs *); 90 91 // Installs a function-pointer as a decorator. Returns a value less than zero 92 // if the system cannot install the decorator. Otherwise, returns a unique 93 // identifier corresponding to the decorator. This identifier can be used to 94 // uninstall the decorator - See RemoveSymbolDecorator() below. 95 int InstallSymbolDecorator(SymbolDecorator decorator, void* arg); 96 97 // Removes a previously installed function-pointer decorator. Parameter "ticket" 98 // is the return-value from calling InstallSymbolDecorator(). 99 bool RemoveSymbolDecorator(int ticket); 100 101 // Remove all installed decorators. Returns true if successful, false if 102 // symbolization is currently in progress. 103 bool RemoveAllSymbolDecorators(void); 104 105 // Registers an address range to a file mapping. 106 // 107 // Preconditions: 108 // start <= end 109 // filename != nullptr 110 // 111 // Returns true if the file was successfully registered. 112 bool RegisterFileMappingHint( 113 const void* start, const void* end, uint64_t offset, const char* filename); 114 115 // Looks up the file mapping registered by RegisterFileMappingHint for an 116 // address range. If there is one, the file name is stored in *filename and 117 // *start and *end are modified to reflect the registered mapping. Returns 118 // whether any hint was found. 119 bool GetFileMappingHint(const void** start, 120 const void** end, 121 uint64_t * offset, 122 const char** filename); 123 124 } // namespace debugging_internal 125 ABSL_NAMESPACE_END 126 } // namespace absl 127 128 #endif // ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_ 129