text: /*
   * Copyright (c) 2017 Cisco and/or its affiliates.
   * 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.
   */
  
  /**
   * @file longBow_Backtrace.h
   * @ingroup internals
   * @brief Support for Stack Traces
   *
   */
  #ifndef LongBow_longBow_Backtrace_h
  #define LongBow_longBow_Backtrace_h
  #include <stdint.h>
  
  struct longbow_backtrace;
  /**
   * @typedef LongBowBacktrace
   * @brief A Backtrace representation.
   */
  typedef struct longbow_backtrace LongBowBacktrace;
  
  /**
   * Create a `LongBowBacktrace`.
   *
   * The backtrace includes depth number of elements from the stack.
   *
   * @param [in] depth  The number of elements from the stack to include.
   * @param [in] offset The offset of the stack to start the Backtrace.
   * @return A pointer to an allocated LongBowBacktrace instance.
   */
  LongBowBacktrace *longBowBacktrace_Create(uint32_t depth, uint32_t offset);
  
  /**
   * Get the array of symbols from the given `LongBowBacktrace instance`.
   *
   * @param [in] backtrace A pointer to a valid LongBowBacktrace instance.
   *
   * @return An array of nul-terminated, C strings each containing a symbolic representatino of the corresponding stack frame.
   *
   * Example:
   * @code
   * {
   *     <#example#>
   * }
   * @endcode
   */
  char **longBowBacktrace_Symbols(const LongBowBacktrace *backtrace);
  /**
   * Get the number of frames in the given LongBowBacktrace instance.
   *
   * @param [in] backtrace A pointer to a valid LongBowBacktrace instance.
   *
   * @return The number of frames in the LongBowBacktrace.
   */
  unsigned int longBowBacktrace_GetFrameCount(const LongBowBacktrace *backtrace);
  
  /**
   *
   * @param [in,out] backtracePtr A pointer to a pointer to a valid LongBowBacktrace instance.
   */
  void longBowBacktrace_Destroy(LongBowBacktrace **backtracePtr);
  
  /**
   *
   * @param [in] backtrace A pointer to a valid LongBowBacktrace instance.
   * @return An allocated C string that must be deallocated via longBowMemory_Deallocate().
   */
  char *longBowBacktrace_ToString(const LongBowBacktrace *backtrace);
  #endif
  