folly/experimental/symbolizer/Symbolizer.h

   1 /*
   2  * Copyright 2013 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef FOLLY_EXPERIMENTAL_SYMBOLIZER_SYMBOLIZER_H_
  19 #define FOLLY_EXPERIMENTAL_SYMBOLIZER_SYMBOLIZER_H_
  20
  21 #include <cstdint>
  22 #include <string>
  23 #include <unordered_map>
  24
  25 #include "folly/FBString.h"
  26 #include "folly/Range.h"
  27 #include "folly/experimental/symbolizer/Elf.h"
  28 #include "folly/experimental/symbolizer/Dwarf.h"
  29 #include "folly/experimental/symbolizer/StackTrace.h"
  30
  31 namespace folly {
  32 namespace symbolizer {
  33
  34 /**
  35  * Frame information: symbol name and location.
  36  *
  37  * Note that both name and location are references in the Symbolizer object,
  38  * which must outlive this SymbolizedFrame object.
  39  */
  40 struct SymbolizedFrame {
  41   SymbolizedFrame() : found(false) { }
  42   bool isSignalFrame;
  43   bool found;
  44   StringPiece name;
  45   Dwarf::LocationInfo location;
  46 };
  47
  48 template <size_t N>
  49 struct FrameArray {
  50   FrameArray() : frameCount(0) { }
  51
  52   size_t frameCount;
  53   uintptr_t addresses[N];
  54   SymbolizedFrame frames[N];
  55 };
  56
  57 /**
  58  * Get stack trace into a given FrameArray, return true on success (and
  59  * set frameCount to the actual frame count, which may be > N) and false
  60  * on failure.
  61  */
  62 template <size_t N>
  63 bool getStackTrace(FrameArray<N>& fa) {
  64   ssize_t n = getStackTrace(fa.addresses, N);
  65   if (n != -1) {
  66     fa.frameCount = n;
  67     for (size_t i = 0; i < fa.frameCount; ++i) {
  68       fa.frames[i].found = false;
  69     }
  70     return true;
  71   } else {
  72     fa.frameCount = 0;
  73     return false;
  74   }
  75 }
  76
  77 class Symbolizer {
  78  public:
  79   Symbolizer() : fileCount_(0) { }
  80
  81   /**
  82    * Symbolize given addresses.
  83    */
  84   void symbolize(const uintptr_t* addresses,
  85                  SymbolizedFrame* frames,
  86                  size_t frameCount);
  87
  88   template <size_t N>
  89   void symbolize(FrameArray<N>& fa) {
  90     symbolize(fa.addresses, fa.frames, fa.frameCount);
  91   }
  92
  93   /**
  94    * Shortcut to symbolize one address.
  95    */
  96   bool symbolize(uintptr_t address, SymbolizedFrame& frame) {
  97     symbolize(&address, &frame, 1);
  98     return frame.found;
  99   }
 100
 101  private:
 102   // We can't allocate memory, so we'll preallocate room.
 103   // "1023 shared libraries should be enough for everyone"
 104   static constexpr size_t kMaxFiles = 1024;
 105   size_t fileCount_;
 106   ElfFile files_[kMaxFiles];
 107 };
 108
 109 /**
 110  * Print a list of symbolized addresses. Base class.
 111  */
 112 class SymbolizePrinter {
 113  public:
 114   /**
 115    * Print one address, no ending newline.
 116    */
 117   void print(uintptr_t address, const SymbolizedFrame& frame);
 118
 119   /**
 120    * Print one address with ending newline.
 121    */
 122   void println(uintptr_t address, const SymbolizedFrame& frame);
 123
 124   /**
 125    * Print multiple addresses on separate lines.
 126    */
 127   void println(const uintptr_t* addresses,
 128                const SymbolizedFrame* frames,
 129                size_t frameCount);
 130
 131   /**
 132    * Print multiple addresses on separate lines, skipping the first
 133    * skip addresses.
 134    */
 135   template <size_t N>
 136   void println(const FrameArray<N>& fa, size_t skip=0) {
 137     if (skip < fa.frameCount) {
 138       println(fa.addresses + skip, fa.frames + skip, fa.frameCount - skip);
 139     }
 140   }
 141
 142   virtual ~SymbolizePrinter() { }
 143
 144   enum Options {
 145     // Skip file and line information
 146     NO_FILE_AND_LINE = 1 << 0,
 147
 148     // As terse as it gets: function name if found, address otherwise
 149     TERSE = 1 << 1,
 150   };
 151
 152  protected:
 153   explicit SymbolizePrinter(int options) : options_(options) { }
 154   const int options_;
 155
 156  private:
 157   void printTerse(uintptr_t address, const SymbolizedFrame& frame);
 158   virtual void doPrint(StringPiece sp) = 0;
 159 };
 160
 161 /**
 162  * Print a list of symbolized addresses to a stream.
 163  * Not reentrant. Do not use from signal handling code.
 164  */
 165 class OStreamSymbolizePrinter : public SymbolizePrinter {
 166  public:
 167   explicit OStreamSymbolizePrinter(std::ostream& out, int options=0)
 168     : SymbolizePrinter(options),
 169       out_(out) { }
 170  private:
 171   void doPrint(StringPiece sp) override;
 172   std::ostream& out_;
 173 };
 174
 175 /**
 176  * Print a list of symbolized addresses to a file descriptor.
 177  * Ignores errors. Async-signal-safe.
 178  */
 179 class FDSymbolizePrinter : public SymbolizePrinter {
 180  public:
 181   explicit FDSymbolizePrinter(int fd, int options=0)
 182     : SymbolizePrinter(options),
 183       fd_(fd) { }
 184  private:
 185   void doPrint(StringPiece sp) override;
 186   int fd_;
 187 };
 188
 189 /**
 190  * Print a list of symbolized addresses to a FILE*.
 191  * Ignores errors. Not reentrant. Do not use from signal handling code.
 192  */
 193 class FILESymbolizePrinter : public SymbolizePrinter {
 194  public:
 195   explicit FILESymbolizePrinter(FILE* file, int options=0)
 196     : SymbolizePrinter(options),
 197       file_(file) { }
 198  private:
 199   void doPrint(StringPiece sp) override;
 200   FILE* file_;
 201 };
 202
 203 /**
 204  * Print a list of symbolized addresses to a std::string.
 205  * Not reentrant. Do not use from signal handling code.
 206  */
 207 class StringSymbolizePrinter : public SymbolizePrinter {
 208  public:
 209   explicit StringSymbolizePrinter(int options=0) : SymbolizePrinter(options) { }
 210
 211   std::string str() const { return buf_.toStdString(); }
 212   const fbstring& fbstr() const { return buf_; }
 213   fbstring moveFbString() { return std::move(buf_); }
 214
 215  private:
 216   void doPrint(StringPiece sp) override;
 217   fbstring buf_;
 218 };
 219
 220 }  // namespace symbolizer
 221 }  // namespace folly
 222
 223 #endif /* FOLLY_EXPERIMENTAL_SYMBOLIZER_SYMBOLIZER_H_ */
 224