bsls_stackaddressutil.h

Go to the documentation of this file.

/// @file bsls_stackaddressutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsls_stackaddressutil.h                                            -*-C++-*-
#ifndef INCLUDED_BSLS_STACKADDRESSUTIL
#define INCLUDED_BSLS_STACKADDRESSUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsls_stackaddressutil bsls_stackaddressutil
/// @brief  Provide a utility for obtaining return addresses from the stack.
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// @{
/// @addtogroup bsls_stackaddressutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsls_stackaddressutil-purpose"> Purpose</a>
/// * <a href="#bsls_stackaddressutil-classes"> Classes </a>
/// * <a href="#bsls_stackaddressutil-description"> Description </a>
///   * <a href="#bsls_stackaddressutil-usage"> Usage </a>
///     * <a href="#bsls_stackaddressutil-example-1-obtaining-return-addresses-and-verifying-their-validity"> Example 1: Obtaining Return Addresses and Verifying Their Validity </a>
///     * <a href="#bsls_stackaddressutil-example-2-obtaining-a-cheapstack"> Example 2: Obtaining a "Cheapstack" </a>
///
/// # Purpose {#bsls_stackaddressutil-purpose}
/// Provide a utility for obtaining return addresses from the stack.
///
/// # Classes {#bsls_stackaddressutil-classes}
///
/// -   bsls::StackAddressUtil: utilities for obtaining addresses from the stack
///
/// @see  balst_stacktraceutil
///
/// # Description {#bsls_stackaddressutil-description}
/// This component defines a `struct`, `bsls::StackAddressUtil`,
/// that provides a namespace for a function, `getStackAddresses`, that
/// populates an array with an ordered sequence of return addresses from the
/// current thread's function call stack.  Each return address points to the
/// (text) memory location of the first instruction to be executed upon
/// returning from a called routine.
///
/// This component also provides a function, `formatCheapStack`, that builds a
/// current stack trace and formats it with instructions on how to use
/// `showfunc.tsk` to print out a stack trace matching where this function was
/// called.  This is a Bloomberg standard "cheapstack" output.
///
/// ## Usage {#bsls_stackaddressutil-usage}
///
///
/// In this section we show the intended usage of this component.
///
/// ### Example 1: Obtaining Return Addresses and Verifying Their Validity {#bsls_stackaddressutil-example-1-obtaining-return-addresses-and-verifying-their-validity}
///
///
/// In the following example we demonstrate how to obtain the sequence of
/// function return addresses from the stack using `getStackAddresses`.
///
/// First, we define `AddressEntry`, which will contain a pointer to the
/// beginning of a function and an index corresponding to the function.  The `<`
/// operator is defined so that a vector of address entries can be sorted in the
/// order of the function addresses.  The address entries will be populated so
/// that the entry containing `&funcN` when `N` is an integer will have an index
/// of `N`.
/// @code
/// struct AddressEntry {
///     void *d_funcAddress;
///     int   d_index;
///
///     // CREATORS
///     AddressEntry(void *funcAddress, int index)
///     : d_funcAddress(funcAddress)
///     , d_index(index)
///         // Create an 'AddressEntry' object and initialize it with the
///         // specified 'funcAddress' and 'index'.
///     {}
///
///     bool operator<(const AddressEntry& rhs) const
///         // Return 'true' if the address stored in the object is lower than
///         // the address stored in 'rhs' and 'false' otherwise.  Note that
///         // this is a member function for brevity, it only exists to
///         // facilitate sorting 'AddressEntry' objects in a vector.
///     {
///         return d_funcAddress < rhs.d_funcAddress;
///     }
/// };
/// @endcode
/// Then, we define `entries`, a vector of address entries.  This will be
/// populated such that a given entry will contain function address `&funcN` and
/// index `N`.  The elements will be sorted according to function address.
/// @code
/// bsl::vector<AddressEntry> entries;
/// @endcode
/// Next, we define `findIndex`:
/// @code
/// static int findIndex(const void *retAddress)
///     // Return the index of the address entry whose function uses an
///     // instruction located at specified 'retAddress'.  The behavior is
///     // undefined unless 'retAddress' is the address of an instruction in
///     // use by a function referred to by an address entry in 'entries'.
/// {
///     unsigned int u = 0;
///     while (u < entries.size()-1 &&
///                                 retAddress >= entries[u+1].d_funcAddress) {
///         ++u;
///     }
///     assert(u < entries.size());
///     assert(retAddress >= entries[u].d_funcAddress);
///
///     int ret = entries[u].d_index;
///
///     if (veryVerbose) {
///         P_(retAddress) P_(entries[u].d_funcAddress) P(ret);
///     }
///
///     return ret;
/// }
/// @endcode
/// Then, we define a volatile global variable that we will use in calculation
/// to discourage compiler optimizers from inlining:
/// @code
/// volatile unsigned int volatileGlobal = 1;
/// @endcode
/// Next, we define a set of functions that will be called in a nested fashion
/// -- `func5` calls `func4` who calls `fun3` and so on.  In each function, we
/// will perform some inconsequential instructions to prevent the compiler from
/// inlining the functions.
///
/// Note that we know the `if` conditions in these 5 subroutines never evaluate
/// to `true`, however, the optimizer cannot figure that out, and that will
/// prevent it from inlining here.
/// @code
/// static unsigned int func1();
/// static unsigned int func2()
/// {
///     if (volatileGlobal > 10) {
///         return (volatileGlobal -= 100) * 2 * func2();             // RETURN
///     }
///     else {
///         return volatileGlobal * 2 * func1();                      // RETURN
///     }
/// }
/// static unsigned int func3()
/// {
///     if (volatileGlobal > 10) {
///         return (volatileGlobal -= 100) * 2 * func3();             // RETURN
///     }
///     else {
///         return volatileGlobal * 3 * func2();                      // RETURN
///     }
/// }
/// static unsigned int func4()
/// {
///     if (volatileGlobal > 10) {
///         return (volatileGlobal -= 100) * 2 * func4();             // RETURN
///     }
///     else {
///         return volatileGlobal * 4 * func3();                      // RETURN
///     }
/// }
/// static unsigned int func5()
/// {
///     if (volatileGlobal > 10) {
///         return (volatileGlobal -= 100) * 2 * func5();             // RETURN
///     }
///     else {
///         return volatileGlobal * 5 * func4();                      // RETURN
///     }
/// }
/// static unsigned int func6()
/// {
///     if (volatileGlobal > 10) {
///         return (volatileGlobal -= 100) * 2 * func6();             // RETURN
///     }
///     else {
///         return volatileGlobal * 6 * func5();                      // RETURN
///     }
/// }
/// @endcode
/// Next, we define the macro FUNC_ADDRESS, which will take a parameter of
/// `&<function name>` and return a pointer to the actual beginning of the
/// function's code, which is a non-trivial and platform-dependent exercise.
/// Note: this doesn't work on Windows for global routines.
/// @code
/// #if defined(BSLS_PLATFORM_OS_AIX)
/// # define FUNC_ADDRESS(p) (((void **) (void *) (p))[0])
/// #else
/// # define FUNC_ADDRESS(p) ((void *) (p))
/// #endif
/// @endcode
/// Then, we define `func1`, the last function to be called in the chain of
/// nested function calls.  `func1` uses
/// `bsls::StackAddressUtil::getStackAddresses` to get an ordered sequence of
/// return addresses from the current thread's function call stack and uses the
/// previously defined `findIndex` function to verify those address are correct.
/// @code
/// unsigned int func1()
///     // Call 'getAddresses' and verify that the returned set of addresses
///     // matches our expectations.
/// {
/// @endcode
/// Next, we populate and sort the `entries` table, a sorted array of
/// `AddressEntry` objects that will allow `findIndex` to look up within which
/// function a given return address can be found.
/// @code
///     entries.clear();
///     entries.push_back(AddressEntry(0, 0));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func1), 1));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func2), 2));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func3), 3));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func4), 4));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func5), 5));
///     entries.push_back(AddressEntry(FUNC_ADDRESS(&func6), 6));
///     bsl::sort(entries.begin(), entries.end());
/// @endcode
/// Then, we obtain the stack addresses with `getStackAddresses`.
/// @code
///     enum { BUFFER_LENGTH = 100 };
///     void *buffer[BUFFER_LENGTH];
///     bsl::memset(buffer, 0, sizeof(buffer));
///     int numAddresses = bsls::StackAddressUtil::getStackAddresses(
///                                                             buffer,
///                                                             BUFFER_LENGTH);
///     assert(numAddresses >= (int) entries.size());
///     assert(numAddresses < BUFFER_LENGTH);
///     assert(0 != buffer[numAddresses-1]);
///     assert(0 == buffer[numAddresses]);
/// @endcode
/// Finally, we go through several of the first addresses returned in `buffer`
/// and verify that each address corresponds to the routine we expect it to.
///
/// Note that on some, but not all, platforms there is an extra "narcissistic"
/// frame describing `getStackAddresses` itself at the beginning of `buffer`.
/// By starting our iteration through `buffer` at `k_IGNORE_FRAMES`, we
/// guarantee that the first address we examine will be in `func1` on all
/// platforms.
/// @code
///     int funcIdx  = 1;
///     int stackIdx = bsls::StackAddressUtil::k_IGNORE_FRAMES;
///     for (; funcIdx < (int) entries.size(); ++funcIdx, ++stackIdx) {
///         assert(stackIdx < numAddresses);
///         assert(funcIdx == findIndex(buffer[stackIdx]));
///     }
///
///     if (testStatus || veryVerbose) {
///         Q(Entries:);
///         for (unsigned int u = 0; u < entries.size(); ++u) {
///             P_(u); P_((void *) entries[u].d_funcAddress);
///             P(entries[u].d_index);
///         }
///
///         Q(Stack:);
///         for (int i = 0; i < numAddresses; ++i) {
///             P_(i); P(buffer[i]);
///         }
///     }
///
///     return volatileGlobal;
/// }
/// @endcode
///
/// ### Example 2: Obtaining a "Cheapstack" {#bsls_stackaddressutil-example-2-obtaining-a-cheapstack}
///
///
/// In this example we demonstrate how to use `formatCheapStack` to generate a
/// string containing the current stack trace and instructions on how to print
/// it out from `showfunc.tsk`.  Note that `showfunc.tsk` is a Bloomberg tool
/// that, when given an executable along with a series of function addresses
/// from a process that was running that executable, will print out a
/// human-readable stack trace with the names of the functions being called in
/// that stack trace.
///
/// First, we define our function where we want to format the stack:
/// @code
/// struct MyTest {
///     static void printCheapStack()
///     {
///         char str[128];
///         bsls::StackAddressUtil::formatCheapStack(str, 128);
///         printf("%s", str);
///     }
/// };
/// @endcode
/// Calling this function will then result in something like this being printed
/// to standard output:
/// @code
/// Please run "/bb/bin/showfunc.tsk <binary_name_here> 403308 402641 ...
///                              ... 3710C1ED1D 400F49" to see the stack trace.
/// @endcode
/// Then, if you had encountered this output running the binary "mybinary.tsk",
/// you could see your stack trace by running this command:
/// @code
/// /bb/bin/showfunc.tsk mybinary.tsk 403308 402641 3710C1ED1D 400F49
/// @endcode
/// This will produce output like this:
/// @code
/// 0x403308 _ZN6MyTest15printCheapStackEv + 30
/// 0x402641 main + 265
/// 0x3710c1ed1d ???
/// 0x400f49 ???
/// @endcode
/// telling you that `MyTest::printCheapStack` was called directly from `main`.
/// Note that if you had access to the binary name that was invoked, then that
/// could be provided as the optional last argument to `printCheapStack` to get
/// a `showfunc.tsk` command that can be more easily invoked, like this:
/// @code
/// struct MyTest2 {
///     static void printCheapStack()
///     {
///         char str[128];
///         bsls::StackAddressUtil::formatCheapStack(str, 128, "mybinary.tsk");
///         printf("%s", str);
///     }
/// };
/// @endcode
/// resulting in output that looks like this:
/// @code
/// Please run "/bb/bin/showfunc.tsk mybinary.tsk 403308 402641 3710C1ED1D ...
///                                         ... 400F49" to see the stack trace.
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsls
 * @{
 */
/** @addtogroup bsls_stackaddressutil
 * @{
 */
 
#include <bsls_platform.h>
 
                      // ============================
                      // class bsls::StackAddressUtil
                      // ============================
 
 
namespace bsls {
 
/// This struct provides a namespace for the function to obtain return
/// addresses from the stack.
struct StackAddressUtil {
 
    // On some platforms, 'getStackAddresses' finds a frame representing
    // 'getStackAddresses' itself.  This frame is usually unwanted.
    // 'k_IGNORE_FRAMES' instructs the caller as to whether the first frame is
    // such an unwanted frame.
 
#if   defined(BSLS_PLATFORM_OS_LINUX) || defined(BSLS_PLATFORM_OS_DARWIN)
    enum { k_IGNORE_FRAMES = 1 };
#else
    enum { k_IGNORE_FRAMES = 0 };
#endif
 
    // CLASS METHODS
 
    /// Get an sequence of return addresses from the current thread's
    /// function call stack, ordered from most recent call to least recent,
    /// and load them into the specified array `*buffer`, which is at least
    /// the specified `maxFrames` in length.  A return address is an address
    /// stored on the stack that points to the first instruction that will
    /// be executed after the called subroutine returns.  If there are more
    /// than `maxFrames` frames on the stack, only the return addresses for
    /// the `maxFrames` most recent routine calls are stored.  When this
    /// routine completes, `buffer` will contain an ordered sequence of
    /// return addresses, sorted such that recent calls occur in the array
    /// before calls that took place before them.  Return the number of
    /// stack frames stored into `buffer` on success, and a negative value
    /// otherwise.  The behavior is undefined unless `maxFrames >= 0` and
    /// `buffer` has room for at least `maxFrames` addresses.  Note that
    /// this routine may fill `buffer` with garbage if the stack is corrupt,
    /// or on Windows if some stack frames represent optimized routines.
    static
    int getStackAddresses(void   **buffer,
                          int      maxFrames);
 
    /// Load the specified `output` buffer having the specified `length`
    /// with the Bloomberg standard "cheapstack" contents as a
    /// null-terminated string.  On successfully obtaining the current call
    /// stack, this will be instructions on how to run the Bloomberg tool
    /// `showfunc.tsk` (with the optionally specified `taskname`, otherwise
    /// with an attempt to obtain the system-specific process name) to get
    /// details of the current call stack where `formatCheapStack` was
    /// called.  On failure, text indicating that the call stack was not
    /// obtainable will be written to `output`.  If `length` is not long
    /// enough for the entire output it will be truncated.  The behavior is
    /// undefined unless `0 <= length` and `output` has the capacity for at
    /// least `length` bytes.
    static
    void formatCheapStack(char *output, int length, const char *taskname = 0);
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2018 Bloomberg Finance L.P.
//
// 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.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */