tracer.h

Go to the documentation of this file.

/* Copyright (c) 2017, Daniel Mensinger
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the Daniel Mensinger nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Daniel Mensinger BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#pragma once

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#if UINTPTR_MAX == 0xffffffff // 32-bit
typedef uint32_t Address;
#elif UINTPTR_MAX == 0xffffffffffffffff // 64-bit
typedef uint64_t Address;
#else                                   // wtf
#error "Could not detect address legth"
#endif

struct tr_TracerHandler;    
struct tr_Tracer;           
struct tr_PrinterContainer; 

enum TR_BOOL { TR_FALSE, TR_TRUE };

enum TR_TraceerEngines { TR_E_END = 0, TR_LIBUNWIND, TR_GLIBC, TR_WIN32_TRACER, TR_DUMMY_T };

enum TR_DebuggerEngines { TR_D_END = 0, TR_LIBDWFL, TR_LIBBFD, TR_WIN32_INFO, TR_EXTERNAL_FALLBACK, TR_DUMMY_D };

typedef enum TR_BOOL            TR_BOOL_t;            
typedef enum TR_TraceerEngines  TR_TraceerEngines_t;  
typedef enum TR_DebuggerEngines TR_DebuggerEngines_t; 

typedef void (*tr_callBackPTR)(void *tracer, void *printer, void *userData);

struct tr_TracerHandler_Config {
  TR_TraceerEngines_t  tracer[8];    
  TR_DebuggerEngines_t debuggers[8]; 
  TR_BOOL_t            autoPrintToStdErr; 
  TR_BOOL_t            autoPrintToFile;   
  char                 logFile[1024];     
  TR_BOOL_t            appendToFile;      

  tr_callBackPTR callback;     
  void *         callbackData; 

  TR_BOOL_t callDefultHandlerWhenDone; 

  int signums[64]; 
};

struct tr_DefaultPrinter_Config {
  char prefix[64]; 
  char seper1[64]; 
  char seper2[64]; 
  char seper3[64]; 
  char suffix[64]; 

  char colorFrameNum[64]; 
  char colorNotFound[64]; 
  char colorAddress[64];  
  char colorFuncName[64]; 
  char colorLineInfo[64]; 
  char colorModule[64];   

  TR_BOOL_t shortenFiles;      
  TR_BOOL_t shortenModules;    
  TR_BOOL_t canonicalizePaths; 
};

struct tr_Frame {
  Address     frameAddr;  
  const char *funcName;   
  const char *moduleName; 
  const char *fileName;   
  int         line;       
  int         column;     
};

struct tr_Tracer_AvailableEngines {
  TR_TraceerEngines_t  tracer[8];    
  TR_DebuggerEngines_t debuggers[8]; 
};

typedef struct tr_TracerHandler           tr_TracerHandler_t;           
typedef struct tr_TracerHandler_Config    tr_TracerHandler_Config_t;    
typedef struct tr_Tracer                  tr_Tracer_t;                  
typedef struct tr_Tracer_AvailableEngines tr_Tracer_AvailableEngines_t; 
typedef struct tr_PrinterContainer        tr_Printer_t;                 
typedef struct tr_Frame                   tr_Frame_t;                   
typedef struct tr_DefaultPrinter_Config   tr_DefaultPrinter_Config_t;   

void tr_defaultSetup();

/* TracerHandler */

tr_TracerHandler_t *tr_getTracerHandler();
void tr_freeTracerHandler(tr_TracerHandler_t *trTH);
void tr_TracerHandler__reset();

TR_BOOL_t tr_TracerHandler__defaultSetup(tr_TracerHandler_t *trTH);
TR_BOOL_t tr_TracerHandler__setup(tr_TracerHandler_t *trTH, tr_Printer_t *pContainer);

tr_TracerHandler_Config_t tr_TracerHandler__getConfig(tr_TracerHandler_t *trTH);
void tr_TracerHandler__setConfig(tr_TracerHandler_t *trTH, tr_TracerHandler_Config_t cfg);

/* Tracer */

tr_Tracer_t *tr_getTracer();
tr_Tracer_t *tr_getTracerWithParam(TR_TraceerEngines_t tracer, TR_DebuggerEngines_t debugInfo);
tr_Tracer_t *tr_getTracerFromVoid(void *tVoid);

void tr_Tracer__trace(tr_Tracer_t *tracer);
size_t tr_Tracer__getNumFrames(tr_Tracer_t *tracer);
tr_Frame_t tr_Tracer__getFrame(tr_Tracer_t *tracer, size_t frameNum);

tr_Tracer_AvailableEngines_t tr_Tracer__getAvailableEngines();

void tr_freeTracer(tr_Tracer_t *tracer);

/* PrinterContainer */

tr_Printer_t *tr_getPrinter(void *printer);
tr_Printer_t *tr_getPrinter__fancy();
tr_Printer_t *tr_getPrinter__file();
tr_Printer_t *tr_getPrinter__system();
tr_Printer_t *tr_getPrinter__plain();

void *tr_PrinterContainer__get(tr_Printer_t *pContainer);

void tr_freePrinter(tr_Printer_t *pContainer);

/* Printer */

/*
 * ALL Printers are accessed with tr_Printer functions.
 * If a function is not supported by a printer then castOK is set to TR_FALSE
 */

void tr_Printer__genStringPreFrame(tr_Printer_t *p, size_t frameNum, char **outStr, TR_BOOL_t *castOK);
void tr_Printer__genStringForFrame(tr_Printer_t *p, size_t frameNum, char **outStr, TR_BOOL_t *castOK);
void tr_Printer__genStringPostFrame(tr_Printer_t *p, size_t frameNum, char **outStr, TR_BOOL_t *castOK);
void tr_Printer__generateString(tr_Printer_t *p, char **outStr, TR_BOOL_t *castOK);

void tr_Printer__printToFile(tr_Printer_t *p, const char *file, TR_BOOL_t append, TR_BOOL_t *castOK);
void tr_Printer__printToStdOut(tr_Printer_t *p, TR_BOOL_t *castOK);
void tr_Printer__printToStdErr(tr_Printer_t *p, TR_BOOL_t *castOK);

void tr_Printer__enableColor(tr_Printer_t *p, TR_BOOL_t *castOK);
void tr_Printer__disableColor(tr_Printer_t *p, TR_BOOL_t *castOK);

void tr_Printer__setTrace(tr_Printer_t *p, tr_Tracer_t *t, TR_BOOL_t *castOK);

tr_DefaultPrinter_Config_t tr_Printer__getConfig(tr_Printer_t *p, TR_BOOL_t *castOK);
void tr_Printer__setConfig(tr_Printer_t *p, tr_DefaultPrinter_Config_t cfg, TR_BOOL_t *castOK);

void tr_Printer__setSignum(tr_Printer_t *p, int signum, TR_BOOL_t *castOK);
void tr_Printer__addSystemEntry(tr_Printer_t *p, const char *name, const char *value, TR_BOOL_t *castOK);

#ifdef __cplusplus
}
#endif