source: libcf/trunk/include/cf_debug.h@ 34

/**
 * @file    cf_debug.h
 * @author  myusgun <myusgun@gmail.com>
 * @version 0.1
 *
 * @remark
 * 디버그 함수를 직접 호출하지 않고 정의된 매크로를 사용하면,
 * Preprocessor에 _DEBUG가 정의되어 있는 경우에 만
 * 디버그 코드가 동작하도록 할 수 있음 <br />
 * 디버그 메시지는 stdout 및 stderr를 이용한 파일 포인터 출력을 지원하고,
 * 환경에 적합하도록 사용자가 구성한 컨텍스트를 이용하여 사용할 수도 있음 <br />
 * (단, 콜스택의 푸시/팝은 컨텍스트를 이용해야만 사용 가능)
 *
 * @section 샘플코드
 * @code

#include "cf_debug.h"

CF_Debug_Ctx gDebugCtx;

void callee (void) {
    CF_Debug_CallStack callstack;
    
    CF_DEBUG_CALLSTACK_PUSH (gDebugCtx);
    CF_DEBUG_CALLSTACK_POP (gDebugCtx, &callstack);
}

int main (void) {
    int fd = 0;
    gDebugCtx = CF_Debug_CreateCtx ();

    CF_DEBUG_CALLSTACK_PUSH (gDebugCtx);

    CF_DEBUG_TRACE (gDebugCtx, "print trace message with context to stderr\n");

    fd = CF_File_Create ("debug.txt");
    if (fd < 0) {
        CF_DEBUG_PRINT (stderr, "error ...\n");
        // error
    }
    CF_Debug_SetOutputFD (gDebugCtx, fd);

    CF_DEBUG_TRACE (gDebugCtx, "print trace message with context to debug.txt\n");

    CF_DEBUG_CALLSTACK_POP (gDebugCtx, NULL);

    CF_Debug_DestroyCtx (gDebugCtx);

    return 0;
}

 * @endcode
 */
#ifndef __CF_DEBUG_H__
#define __CF_DEBUG_H__

#include "cf_base.h"

#include <stdio.h>

#define CF_ERROR_DEBUG_INVALID_CTX          CF_ERROR_DEBUG - 1
#define CF_ERROR_DEBUG_SET_OUTPUT_FD        CF_ERROR_DEBUG - 2
#define CF_ERROR_DEBUG_PUSH_CALLSTACK       CF_ERROR_DEBUG - 3
#define CF_ERROR_DEBUG_POP_CALLSTACK        CF_ERROR_DEBUG - 4

/** Windows 함수 이름 매크로 재정의 */
#ifdef _WIN32
# define __func__   __FUNCTION__
#endif

#ifdef _DEBUG
/**
 * 디버그 컨텍스트 생성
 *
 * @see CF_Debug_CreateCtx
 */
# define CF_DEBUG_CREATE_CTX()                                      \
    CF_Debug_CreateCtx ()

/**
 * 디버그 컨텍스트 해제
 *
 * @param __ctx 디버그 컨텍스트
 *
 * @see CF_Debug_DestroyCtx
 */
# define CF_DEBUG_DESTROY_CTX(__ctx)                                \
    CF_Debug_DestroyCtx (__ctx)

/**
 * 디버그 메시지를 지정된 파일 포인터로 출력
 *
 * @param __fp  파일 포인터. 표준출력(stdout) 및 표준오류(stderr) 사용 가능
 * @param __fmt 포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_Debug_Print
 */
# define CF_DEBUG_PRINT(__fp,__fmt,...)                             \
    CF_Debug_Print (__fp,__FILE__,__func__,__LINE__,__fmt,##__VA_ARGS__)

/**
 * 바이너리 데이터를 디버그 메시지와 함께 지정된 파일 포인터로 출력
 *
 * @param __fp  파일 포인터. 표준출력(stdout) 및 표준오류(stderr) 사용 가능
 * @param __bin 바이너리 데이터
 * @param __len 바이너리 길이
 * @param __fmt 포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_Debug_PrintBin
 */
# define CF_DEBUG_PRINT_BIN(__fp,__bin,__len,__fmt,...)             \
    CF_Debug_PrintBin (__fp,__FILE__,__func__,__LINE__,__bin,__len,__fmt,##__VA_ARGS__)

/**
 * 컨텍스트를 업데이트하고 디버그 메시지를 출력
 *
 * @param __ctx 디버그 컨텍스트
 * @param __fmt 포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_UPDATE_CTX, CF_Debug_Trace
 */
# define CF_DEBUG_TRACE(__ctx,__fmt,...)                            \
    CF_Debug_Trace (__ctx,__FILE__,__func__,__LINE__,__fmt,##__VA_ARGS__)

/**
 * 컨텍스트를 업데이트하고 바이너리 데이터를 디버그 메시지와 함께 출력
 *
 * @param __ctx 디버그 컨텍스트
 * @param __bin 바이너리 데이터
 * @param __len 바이너리 길이
 * @param __fmt 포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_UPDATE_CTX, CF_Debug_TraceBin
 */
# define CF_DEBUG_TRACE_BIN(__ctx,__bin,__len,__fmt,...)            \
    CF_Debug_TraceBin (__ctx,__FILE__,__func__,__LINE__,__bin,__len,__fmt,##__VA_ARGS__)

/**
 * 컨텍스트에 콜스택 푸시
 *
 * @param __ctx 디버그 컨텍스트
 *
 * @see CF_Debug_CallStackPush
 */
# define CF_DEBUG_CALLSTACK_PUSH(__ctx)                             \
    CF_Debug_CallStackPush (__ctx,__FILE__,__func__,__LINE__)

/**
 * 컨텍스트에서 콜스택 팝
 *
 * @param __ctx         디버그 컨텍스트
 * @param __callstack   콜스택 정보를 가져올 콜스택 데이터 구조체 포인터
 *
 * @see CF_Debug_CallStackPop, CF_Debug_CallStack
 */
# define CF_DEBUG_CALLSTACK_POP(__ctx,__callstack)                  \
    CF_Debug_CallStackPop (__ctx,__callstack)
#else // #ifdef _DEBUG
# define CF_DEBUG_CREATE_CTX()                          NULL
# define CF_DEBUG_DESTROY_CTX(__ctx)
# define CF_DEBUG_UPDATE_CTX(__ctx)
# define CF_DEBUG_PRINT(__fp,__fmt,...)
# define CF_DEBUG_PRINT_BIN(__fp,__bin,__len,__fmt,...)
# define CF_DEBUG_TRACE(__ctx,__fmt,...)
# define CF_DEBUG_TRACE_BIN(__ctx,__bin,__len,__fmt,...)
# define CF_DEBUG_CALLSTACK_PUSH(__ctx)
# define CF_DEBUG_CALLSTACK_POP(__ctx,__callstack)      1
#endif // #ifdef _DEBUG

/** 디버그 컨텍스트 */
typedef void *  CF_Debug_Ctx;

/** 콜스택 데이터 */
typedef struct cf_debug_callStack {
    char    file[NAME_LENGTH + 1];      /**< 파일 이름 */
    char    function[NAME_LENGTH + 1];  /**< 함수 이름 */
    int     line;                       /**< 라인 넘버 */
} CF_Debug_CallStack;

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 디버그 컨텍스트를 생성
 *
 * @return 성공 시, CF_Debug_Ctx 형태의 컨텍스트; 실패 시, NULL
 * @see CF_DEBUG_CREATE_CTX
 */
CF_EXPORT CF_Debug_Ctx
CF_Debug_CreateCtx      (void);

/**
 * 디버그 컨텍스트를 해제
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param ctx 디버그 컨텍스트
 *
 * @see CF_DEBUG_DESTROY_CTX
 */
CF_EXPORT int
CF_Debug_DestroyCtx     (CF_Debug_Ctx ctx);

/**
 * 디버그 컨텍스트에 출력할 파일 디스크립터를 설정
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param ctx   디버그 컨텍스트
 * @param fd    파일 디스크립터
 *
 * @see CF_File_Open, CF_File_Create
 */
CF_EXPORT int
CF_Debug_SetOutputFD    (CF_Debug_Ctx   ctx,
                         int            fd);

/**
 * 디버그 메시지를 지정된 파일 포인터로 출력
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param fp    파일 포인터. 표준출력(stdout) 및 표준오류(stderr) 사용 가능
 * @param file  파일 경로
 * @param func  함수 이름
 * @param line  라인 넘버
 * @param fmt   포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_PRINT
 */
CF_EXPORT int
CF_Debug_Print          (FILE       * fp,
                         const char * file,
                         const char * func,
                         const int  line,
                         const char * fmt, ...);

/**
 * 바이너리 데이터를 디버그 메시지와 함께 지정된 파일 포인터로 출력
 *
 * @return CF_OK 반환
 *
 * @param fp    파일 포인터. 표준출력(stdout) 및 표준오류(stderr) 사용 가능
 * @param file  파일 경로
 * @param func  함수 이름
 * @param line  라인 넘버
 * @param bin   라인 넘버
 * @param len   바이너리 길이
 * @param fmt   포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_PRINT_BIN
 */
CF_EXPORT int
CF_Debug_PrintBin       (FILE                   * fp,
                         const char             * file,
                         const char             * func,
                         const int              line,
                         const unsigned char    * bin,
                         const int              len,
                         const char             * fmt, ...);

/**
 * 컨텍스트를 업데이트하고 디버그 메시지를 출력
 *
 * @return CF_OK 반환
 *
 * @param ctx   디버그 컨텍스트
 * @param file  파일 경로
 * @param func  함수 이름
 * @param line  라인 넘버
 * @param fmt   포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_UPDATE_CTX, CF_Debug_Trace
 */
CF_EXPORT int
CF_Debug_Trace          (CF_Debug_Ctx   ctx,
                         const char     * file,
                         const char     * func,
                         const int      line,
                         const char     * fmt, ...);

/**
 * 컨텍스트를 업데이트하고 바이너리 데이터를 디버그 메시지와 함께 출력
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param ctx   디버그 컨텍스트
 * @param file  파일 경로
 * @param func  함수 이름
 * @param line  라인 넘버
 * @param bin   바이너리 데이터
 * @param len   바이너리 길이
 * @param fmt   포맷 스트링
 * @param ...   가변 인자
 *
 * @see CF_DEBUG_UPDATE_CTX, CF_DEBUG_TRACE_BIN
 */
CF_EXPORT int
CF_Debug_TraceBin       (CF_Debug_Ctx           ctx,
                         const char             * file,
                         const char             * func,
                         const int              line,
                         const unsigned char    * bin,
                         const int              len,
                         const char             * fmt, ...);

/**
 * 컨텍스트에 콜스택 푸시
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param ctx   디버그 컨텍스트
 * @param file  파일 경로
 * @param func  함수 이름
 * @param line  라인 넘버
 *
 * @see CF_DEBUG_CALLSTACK_PUSH
 */
CF_EXPORT int
CF_Debug_CallStackPush  (CF_Debug_Ctx   ctx,
                         const char     * file,
                         const char     * func,
                         const int      line);

/**
 * 컨텍스트에서 콜스택 팝
 *
 * @return 성공 시, CF_OK; 실패 시, 오류 코드
 *
 * @param ctx       디버그 컨텍스트
 * @param callstack 콜스택 정보를 가져올 콜스택 데이터 구조체 포인터
 *
 * @see CF_Debug_CallStackPop, CF_Debug_CallStack
 */
CF_EXPORT int
CF_Debug_CallStackPop   (CF_Debug_Ctx       ctx,
                         CF_Debug_CallStack * callstack);

#ifdef __cplusplus
}
#endif

#endif // #ifndef __CF_DEBUG_H__