00001 // -*- C++ -*- 00002 //============================================================================= 00003 /** 00004 * @file Stack_Trace.h 00005 * 00006 * $Id: Stack_Trace.h 81926 2008-06-12 14:43:09Z mitza $ 00007 * 00008 * @author Chris Cleeland (cleeland.ociweb.com) 00009 */ 00010 //============================================================================= 00011 00012 #ifndef ACE_STACK_TRACE_H 00013 #define ACE_STACK_TRACE_H 00014 00015 #include /**/ "ace/pre.h" 00016 00017 #include "ace/ACE_export.h" 00018 #include "ace/Basic_Types.h" 00019 00020 # if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 # endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 # ifndef ACE_STACK_TRACE_SYMBUFSIZ 00025 # define ACE_STACK_TRACE_SYMBUFSIZ 4096 00026 # endif 00027 00028 /** 00029 * @class ACE_Stack_Trace 00030 * 00031 * @brief Encapsulate a string representation of a stack trace on supported platforms. 00032 * Stack traces for code built with optimize=1 (or "Release" configs on Visual 00033 * Studio) may be misleading (missng frames) due to inlining performed by the 00034 * compiler, which is indepenent of the inline=0 / inline=1 build option and 00035 * the __ACE_INLINE__ / ACE_NO_INLINE macros. 00036 * 00037 * A new conversion character, the question mark, was added to ACE_Log_Msg for stack 00038 * trace logging. The %? conversion character was added as a convenience so that users 00039 * need not instantiate an ACE_Stack_Trace instance solely for the purpose of printing 00040 * it in an ACE logging message. The following are functionally equivalent: 00041 * 00042 * \code 00043 * ACE_DEBUG((LM_DEBUG, "%?")); 00044 * 00045 * ACE_Stack_Trace st; 00046 * ACE_DEBUG ((LM_DEBUG, "%s", st.c_str() )); 00047 * \endcode 00048 * 00049 * These usage examples were shown in $ACE_ROOT/tests/Stack_Trace_Test.cpp. 00050 * 00051 * @note The stack trace functionality was currently supported on platforms: 00052 * - Any platform using glibc as its runtime library, or where ACE_HAS_EXECINFO_H is defined 00053 * (this covers Linux and Mac) and gcc version >= 3.3. 00054 * - VxWorks, both kernel and RTP 00055 * - Solaris 00056 * - Windows 32 and 64 bit (Visual C++, excluding WinCE/mobile) 00057 * 00058 * @note Since stack trace buffer size has limitation(@c ACE_STACK_TRACE_SYMBUFSIZ), you will not 00059 * get a complete stack trace if @c ACE_STACK_TRACE_SYMBUFSIZ value is less than actual stack 00060 * trace data length. To get a complete stack trace, you need set @c ACE_STACK_TRACE_SYMBUFSIZ 00061 * with a larger value that is enough for the stack trace data in your @c config.h file 00062 * and rebuild ACE. 00063 * 00064 * @note Using ACE logging mechanism (%?) to log the stack trace also has ACE_MAXLOGMSGLEN size limitation. 00065 * To get a complete stack trace, you could use different output method. Following is an example. 00066 * 00067 * \code 00068 * ACE_Stack_Trace st; 00069 * ACE_OS::printf("at [%s]\n", st.c_str()); 00070 * \endcode 00071 */ 00072 class ACE_Export ACE_Stack_Trace 00073 { 00074 public: 00075 /** 00076 * @brief Grab a snapshot of the current stack trace and hold it for later use. 00077 * 00078 * @param starting_frame_offset offset into the array of frames to start printing; 0 is the 00079 * platform-specific offset for the first frame, positive numbers give less frames, negative give 00080 * more frames 00081 * @param num_frames the number of stack frames to include (0 indicates platform-specific maximum) 00082 * 00083 */ 00084 explicit ACE_Stack_Trace (ssize_t starting_frame_offset = 0, size_t num_frames = 0); 00085 00086 /** 00087 * @brief Return buffer as a C-style string. 00088 * @return C-style string with string representation of stack trace. 00089 * @note Lifecycle of string follows lifecycle of ACE_Stack_Trace instance. 00090 */ 00091 const char* c_str() const; 00092 00093 static const size_t SYMBUFSIZ = ACE_STACK_TRACE_SYMBUFSIZ; 00094 00095 private: 00096 char buf_[SYMBUFSIZ]; 00097 size_t buflen_; 00098 00099 static const char UNSUPPORTED[]; 00100 static const char UNABLE_TO_GET_TRACE[]; 00101 00102 void generate_trace (ssize_t starting_frame_offset, size_t num_frames); 00103 }; 00104 00105 #include /**/ "ace/post.h" 00106 #endif /* ACE_STACK_TRACE_H */ 00107