XrdOucBackTrace Class Reference

#include <XrdOucBackTrace.hh>

List of all members.

Public Types

enum  PtrType { isThis, isObject }
 

Define filter types and actions.

More...
enum  Action { addIt = 0, clrIt, delIt, repIt }

Static Public Member Functions

static void DoBT (const char *head=0, void *thisP=0, void *objP=0, const char *tail=0, bool force=false)
static bool Init (const char *reqs=0, const char *rsps=0)
static void Filter (void *ptr, PtrType pType, Action how=addIt)
static void XrdBT (const char *head=0, void *thisP=0, void *objP=0, int rspN=0, int reqN=0, const char *tail=0, bool force=false)

Detailed Description

XrdOucBackTrace provides a way to perform a back trace to assist in debugging esoteric problems. It is controlled by various envars or options can be set by methods in this class. It is fully MT_safe. However, a full back trace is only available for programs compiled using a GNU compiler.

Back tracing can be selectively controlled by filters. As filters interact, one must understand how they are applied. There are four filters: 1) this pointer matching 2) object pointer matching 3) request code matching (XrdBT only) 4) response code matching (XrdBT only, also known as the status code)

Both DoBT() and XrdBT() apply this and pointer filters while XrdBT() also applies request and response filters while DoBT() does not apply them. When DoBT() or XrdBT() is called, the following sequence occurs: 1) If the this filter is set and the this pointer matches a BT occurs. 2) if the object filter is set and the object pointer matches a BT occurs. 3) If both pointer filters are set then no BT occurs, period. 4) If only one of the pointer filters is set then DoBT() does not do a BT. 5) XrdBT() also does not do a BT if the neither code matching filters are set. If one of the code filters is set then a BT occurs if both filters succeed (note that an unset code filter always succeeds).

Two handy commands in gdb to convert a back trace to source file line: info line *addr list *addr The addr is the address that appears in the back trace in brackets. The 'info line' gives you a close approximation while list provides more context with a suggested line (optimization makes this obtuse). For example, given [0x7ffff695db36] say 'info line *0x7ffff695db36'.


Member Enumeration Documentation

Enumerator:
addIt 

Add item to the list of PtrTypes being filtered.

clrIt 

Delete all PtrType filtered items (1st arg ignored).

delIt 

Delete this item from the list of PtrTypes filtered.

repIt 

Replace all PtrTypes items filtered with this item.

Define filter types and actions.

Enumerator:
isThis 

Pointer is a this pointer.

isObject 

Pointer is an object pointer.


Member Function Documentation

static void XrdOucBackTrace::DoBT ( const char *  head = 0,
void *  thisP = 0,
void *  objP = 0,
const char *  tail = 0,
bool  force = false 
) [static]

Produce a back trace. The message header and corresponding back trace have the format below. The traceback lines may differ if an error occurs. The maximum levels displayed is controlled by the XRDBT_DEPTH envar. If not set, or is invalid, Only the last 15 levels are displayed (maximum depth is 30). This version is geared for general applications (see XrdBT() alternative).

TBT <thread_id> <thisP> [<head>] obj <objP> [<tail>] TBT <thread_id> [<addr_of_ret>] <func>(<args>)+offs

Parameters:
head Points to text to be included in back trace header. A nil pointer indicates there is no information.
thisP Is the this pointer of the caller. If there is no this pointer, pass nil. The address is included in the header. Use Filter() to filter the address.
objP Pointer to an object of interest. It's address is included in the header. Use Filter() to filter the address.
tail Pointer to text to be included at the end of the header. A nil pointer indicates there is none.
force When true, all filters are ignored.
static void XrdOucBackTrace::Filter ( void *  ptr,
PtrType  pType,
Action  how = addIt 
) [static]

Set a pointer filter. Back traces only occur when the corresponding pointer is passed to DoBT() or XrdBT(). See filtering explanation above.

Parameters:
ptr The pointer.
pType The pointer's logical type (see PtrType defined above).
how One of the action enums in Action (defined above).
static bool XrdOucBackTrace::Init ( const char *  reqs = 0,
const char *  rsps = 0 
) [static]

Do optional one time static intialization. Invoke this method at file level (e.g. bool aOK = XrdOucBackTrace::Init()) if you wish to set xrootd specific filters when calling XrdBT(). Otherwise, don't use this method.

Parameters:
reqs The kXR_ request code name(s). If the pointer is nil, the back trace filter is set using envar XRDBT_REQFILTER as the argument. If both are nil, no filter is established. Specify, one or more names, each separated by a space. Invalid names are ignored. Choose from this list:

admin auth bind chmod close dirlist endsess getfile locate login mkdir mv open ping prepare protocol putfile query read readv rm rmdir set stat statx sync truncate verifyw write

Parameters:
reqs The kXR_ response code name(s). If the pointer is nil, the back trace filter is set using envar XRDBT_RSPFILTER as the argument. If both are nil, no filter is established. Specify, one or more names, each separated by a space. Invalid names are ignored. Choose from this list:

attn authmore error ok oksofar redirect wait waitresp

Returns:
true Initialization succeeded.
false Initialization completed but one or more reqs or rsps were ignored because they were invalid.
static void XrdOucBackTrace::XrdBT ( const char *  head = 0,
void *  thisP = 0,
void *  objP = 0,
int  rspN = 0,
int  reqN = 0,
const char *  tail = 0,
bool  force = false 
) [static]

Produce an XrrotD specific back trace. The message header and corresponding back trace have the format below. The back trace lines may differ if an error occurs. This version is for for XRootD applications. See the DoBT().

TBT <thread_id> <thisP> <head> obj <objP> rsp <statN> req <reqN> <tail> TBT <thread_id> [<addr_of_ret>] <func>(<args>)+offs

Parameters:
head Points to text to be included in back trace header
thisP Is the this pointer of the caller. If there is no this pointer, pass nil. The address is included in the header. User Filter() to filter the pointer.
objP Pointer to an object of interest. It's address is included in the header. Use Filter() to filter the pointer.
rspN The kXR_ status code reflected in an XRootD response. It's corresponding name, if any, is included in the header. Use Init() to filter the code value.
reqN The kXR_ request code of an XRootD request. It's corresponding name, if any, is included in the header. Use Init() to filter the code value.
tail Pointer to text to be included at the end of the header. A nil pointer does not add any additional text.
force When true, all filters are ignored.

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 17 Dec 2019 for xrootd by  doxygen 1.6.1