debugging/internal/symbolize.h

0001 // Copyright 2018 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014
0015 // This file contains internal parts of the Abseil symbolizer.
0016 // Do not depend on the anything in this file, it may change at anytime.
0017
0018 #ifndef ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_
0019 #define ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_
0020
0021 #ifdef __cplusplus
0022
0023 #include <cstddef>
0024 #include <cstdint>
0025
0026 #include "absl/base/config.h"
0027 #include "absl/strings/string_view.h"
0028
0029 #ifdef ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE
0030 #error ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE cannot be directly set
0031 #elif defined(__ELF__) && defined(__GLIBC__) && !defined(__native_client__) \
0032       && !defined(__asmjs__) && !defined(__wasm__)
0033 #define ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE 1
0034
0035 #include <elf.h>
0036 #include <link.h>  // For ElfW() macro.
0037 #include <functional>
0038 #include <string>
0039
0040 namespace absl {
0041 ABSL_NAMESPACE_BEGIN
0042 namespace debugging_internal {
0043
0044 // Iterates over all sections, invoking callback on each with the section name
0045 // and the section header.
0046 //
0047 // Returns true on success; otherwise returns false in case of errors.
0048 //
0049 // This is not async-signal-safe.
0050 bool ForEachSection(int fd,
0051                     const std::function<bool(absl::string_view name,
0052                                              const ElfW(Shdr) &)>& callback);
0053
0054 // Gets the section header for the given name, if it exists. Returns true on
0055 // success. Otherwise, returns false.
0056 bool GetSectionHeaderByName(int fd, const char *name, size_t name_len,
0057                             ElfW(Shdr) *out);
0058
0059 }  // namespace debugging_internal
0060 ABSL_NAMESPACE_END
0061 }  // namespace absl
0062
0063 #endif  // ABSL_INTERNAL_HAVE_ELF_SYMBOLIZE
0064
0065 #ifdef ABSL_INTERNAL_HAVE_DARWIN_SYMBOLIZE
0066 #error ABSL_INTERNAL_HAVE_DARWIN_SYMBOLIZE cannot be directly set
0067 #elif defined(__APPLE__)
0068 #define ABSL_INTERNAL_HAVE_DARWIN_SYMBOLIZE 1
0069 #endif
0070
0071 #ifdef ABSL_INTERNAL_HAVE_EMSCRIPTEN_SYMBOLIZE
0072 #error ABSL_INTERNAL_HAVE_EMSCRIPTEN_SYMBOLIZE cannot be directly set
0073 #elif defined(__EMSCRIPTEN__)
0074 #define ABSL_INTERNAL_HAVE_EMSCRIPTEN_SYMBOLIZE 1
0075 #endif
0076
0077 namespace absl {
0078 ABSL_NAMESPACE_BEGIN
0079 namespace debugging_internal {
0080
0081 struct SymbolDecoratorArgs {
0082   // The program counter we are getting symbolic name for.
0083   const void *pc;
0084   // 0 for main executable, load address for shared libraries.
0085   ptrdiff_t relocation;
0086   // Read-only file descriptor for ELF image covering "pc",
0087   // or -1 if no such ELF image exists in /proc/self/maps.
0088   int fd;
0089   // Output buffer, size.
0090   // Note: the buffer may not be empty -- default symbolizer may have already
0091   // produced some output, and earlier decorators may have adorned it in
0092   // some way. You are free to replace or augment the contents (within the
0093   // symbol_buf_size limit).
0094   char *const symbol_buf;
0095   size_t symbol_buf_size;
0096   // Temporary scratch space, size.
0097   // Use that space in preference to allocating your own stack buffer to
0098   // conserve stack.
0099   char *const tmp_buf;
0100   size_t tmp_buf_size;
0101   // User-provided argument
0102   void* arg;
0103 };
0104 using SymbolDecorator = void (*)(const SymbolDecoratorArgs *);
0105
0106 // Installs a function-pointer as a decorator. Returns a value less than zero
0107 // if the system cannot install the decorator. Otherwise, returns a unique
0108 // identifier corresponding to the decorator. This identifier can be used to
0109 // uninstall the decorator - See RemoveSymbolDecorator() below.
0110 int InstallSymbolDecorator(SymbolDecorator decorator, void* arg);
0111
0112 // Removes a previously installed function-pointer decorator. Parameter "ticket"
0113 // is the return-value from calling InstallSymbolDecorator().
0114 bool RemoveSymbolDecorator(int ticket);
0115
0116 // Remove all installed decorators.  Returns true if successful, false if
0117 // symbolization is currently in progress.
0118 bool RemoveAllSymbolDecorators();
0119
0120 // Registers an address range to a file mapping.
0121 //
0122 // Preconditions:
0123 //   start <= end
0124 //   filename != nullptr
0125 //
0126 // Returns true if the file was successfully registered.
0127 bool RegisterFileMappingHint(const void* start, const void* end,
0128                              uint64_t offset, const char* filename);
0129
0130 // Looks up the file mapping registered by RegisterFileMappingHint for an
0131 // address range. If there is one, the file name is stored in *filename and
0132 // *start and *end are modified to reflect the registered mapping. Returns
0133 // whether any hint was found.
0134 bool GetFileMappingHint(const void** start, const void** end, uint64_t* offset,
0135                         const char** filename);
0136
0137 }  // namespace debugging_internal
0138 ABSL_NAMESPACE_END
0139 }  // namespace absl
0140
0141 #endif  // __cplusplus
0142
0143 #include <stdbool.h>
0144
0145 #ifdef __cplusplus
0146 extern "C"
0147 #endif  // __cplusplus
0148
0149     bool
0150     AbslInternalGetFileMappingHint(const void** start, const void** end,
0151                                    uint64_t* offset, const char** filename);
0152
0153 #endif  // ABSL_DEBUGGING_INTERNAL_SYMBOLIZE_H_