debug.h File Reference

Debug utilities for various data types and arrays. More...

#include <stdbool.h>
#include <stdio.h>

Macros
#define	DBG_OUTSTREAM   stderr
	Macro for the debug output stream.
#define	SOURCE_PATH_SIZE   0
	Macro to truncate the root file path.
#define	__FILENAME__   ((__FILE__) + (SOURCE_PATH_SIZE))
	Macro to adjust the file path based on SOURCE_PATH_SIZE.
#define	dbg(value)
	Macro to print a debug message for a variable.
#define	dbg_array(value, length)
	Macro to print a debug message for an array.
#define	CALL_DBG(dbg_func_name, value)
	Macro to call a debug function for a variable.
#define	CALL_DBG_ARRAY(dbg_func_name, value, length)
	Macro to call a debug function for an array.
#define	RESET   "\033[0m"
#define	DBG_FUNC_DECL(type, name, fmt)
	Macro to declare a debug function for a variable.
#define	DBG_ARRAY_FUNC_DECL(type, name, fmt)
	Macro to declare a debug function for an array.

Functions
void	set_breakpoint (void)
	Function to set a breakpoint for debugging.

Detailed Description

Debug utilities for various data types and arrays.

This header provides macros and functions to facilitate debugging by printing values of various data types and arrays, along with their expressions, file names, line numbers, and function names. The dbg() macro aims to be similar to the rust dbg!() one.

Note

You can define NODBG to remove dbg() and dbg_array() macro call without removing the expression statement

Warning

The dbg() and dbg_array() macro are only defined for C11 or newer. In version lower than C11, the comportement is like if NODBG was defined. If you work on version lower than C11, you are free to use the CALL_DBG() and CALL_DBG_ARRAY() macros.

Usage example:

#include <ayaztub/utils/debug.h>
 
DBG_ARRAY_FUNC_DECL(const char **, string, "\"%s\"")
 
int main(int argc, char **argv) {
    if (dbg((bool)(argc == 1))) {
         dbg(argv[0]);
    }
    CALL_DBG_ARRAY(dbg_array_string, (const char **)argv, argc);
 
    set_breakpoint();
 
    return 0;
}

Macro Definition Documentation

__FILENAME__

#define __FILENAME__   ((__FILE__) + (SOURCE_PATH_SIZE))

Macro to adjust the file path based on SOURCE_PATH_SIZE.

This macro modifies the __FILE__ macro to remove a specified number of characters from the beginning, making the logged file paths more readable.

CALL_DBG

#define CALL_DBG	(		dbg_func_name,
			value )

Value:

        dbg_func_name(__FILENAME__, __LINE__, __func__, #value, value)

Macro to call a debug function for a variable.

This macro calls a debug function for the specified variable.

Note

You can remove the CALL_DBG() macro defining NODBG. Removing the macro will not remove the value (aka, return of the macro still useful).

Instead of the dbg() macro, this has no C version requirement.

Parameters

dbg_func_name	The name of the debug function.
value	The variable to debug.

Returns

the value itself.

Example usage:

int x = 69;
if ((CALL_DBG(dbg_int, x) + 1) % 10 == 0) {
    printf("This is true!\n");
}

CALL_DBG_ARRAY

#define CALL_DBG_ARRAY	(		dbg_func_name,
			value,
			length )

Value:

        dbg_func_name(__FILENAME__, __LINE__, __func__, #value, value, length)

Macro to call a debug function for an array.

This macro calls a debug function for the specified array.

Note

You can remove the CALL_DBG_ARRAY() macro defining NODBG. Removing the macro will not remove the value (aka, return of the macro still useful).

Instead of the dbg_array() macro, this has no C version requirement.

Parameters

dbg_func_name	The name of the debug function.
value	The array to debug.
length	The length of the array.

Returns

the value array itself.

Example usage:

int arr[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
if (CALL_DBG_ARRAY(dbg_array_int, arr, 10)[0] == 0) {
    printf("This is true!\n");
}

Examples

example_debug.c.

dbg

#define dbg

(

value

)

Value:

            _Generic((value),                                                  \
             char: dbg_char,                                                   \
             signed char: dbg_schar,                                           \
             unsigned char: dbg_uchar,                                         \
             short: dbg_short,                                                 \
             unsigned short: dbg_ushort,                                       \
             int: dbg_int,                                                     \
             unsigned int: dbg_uint,                                           \
             long: dbg_long,                                                   \
             unsigned long: dbg_ulong,                                         \
             long long: dbg_llong,                                             \
             unsigned long long: dbg_ullong,                                   \
             float: dbg_float,                                                 \
             double: dbg_double,                                               \
             bool: dbg_bool,                                                   \
             char *: dbg_char_p,                                               \
             const char *: dbg_const_char_p,                                   \
             signed char *: dbg_schar_p,                                       \
             const signed char *: dbg_const_schar_p,                           \
             unsigned char *: dbg_uchar_p,                                     \
             const unsigned char *: dbg_const_uchar_p,                         \
             default: dbg_pointer)                                             \
        (__FILENAME__, __LINE__, __func__, #value, value)

Macro to print a debug message for a variable.

This macro prints a debug message for the specified variable, including its name and value. It aims to be the same as the rust dbg!() macro.

Note

You can remove the dbg() macro defining NODBG. Removing the macro will not remove the value (aka, return of the macro still useful).

Warning

This macro is only defined for C11 or newer.

Parameters

value

The variable to debug.

Returns

the value itself.

Example usage:

int x = 42;
float f = ((float) dbg(x)) + 0.5f;
dbg(f);

Examples

example_debug.c.

dbg_array

#define dbg_array	(		value,
			length )

Value:

            _Generic((value),                                                  \
             short *: dbg_array_short,                                         \
             const short *: dbg_array_const_short,                             \
             unsigned short *: dbg_array_ushort,                               \
             const unsigned short *: dbg_array_const_ushort,                   \
             int *: dbg_array_int,                                             \
             const int *: dbg_array_const_int,                                 \
             unsigned int *: dbg_array_uint,                                   \
             const unsigned int *: dbg_array_const_uint,                       \
             long *: dbg_array_long,                                           \
             const long *: dbg_array_const_long,                               \
             unsigned long *: dbg_array_ulong,                                 \
             const unsigned long *: dbg_array_const_ulong,                     \
             long long *: dbg_array_llong,                                     \
             const long long *: dbg_array_const_llong,                         \
             unsigned long long *: dbg_array_ullong,                           \
             const unsigned long long *: dbg_array_const_ullong,               \
             float *: dbg_array_float,                                         \
             const float *: dbg_array_const_float,                             \
             double *: dbg_array_double,                                       \
             const double *: dbg_array_const_double,                           \
             char *: dbg_array_char,                                           \
             const char *: dbg_array_const_char,                               \
             signed char *: dbg_array_schar,                                   \
             const signed char *: dbg_array_const_schar,                       \
             unsigned char *: dbg_array_uchar,                                 \
             const unsigned char *: dbg_array_const_uchar,                     \
             bool *: dbg_array_bool,                                           \
             const bool *: dbg_array_const_bool)                               \
        (__FILENAME__, __LINE__, __func__, #value, value, length)

Macro to print a debug message for an array.

This macro prints a debug message for the specified array, including its name and elements. It aims to be the same as the rust dbg!() macro but for arrays.

Note

You can remove the dbg_array() macro defining NODBG. Removing the macro will not remove the value (aka, return of the macro still useful).

Warning

This macro is only defined for C11 or newer.

Parameters

value	The array to debug.
length	The length of the array.

Returns

the value array itself.

Example usage:

int arr[] = {1, 2, 3, 4, 5};
if (dbg_array(arr, 5)[0] == 0) {
    printf("This should not be true...\n");
}

DBG_ARRAY_FUNC_DECL

#define DBG_ARRAY_FUNC_DECL	(		type,
			name,
			fmt )

Value:

    static inline type dbg_array_##name(                                       \
        const char *file, unsigned int line, const char *func_name,            \
        const char *expr, type array, size_t length) {                         \
        fprintf(DBG_OUTSTREAM,                                                 \
                GRAY "%s:%u in %s()" RESET ": " TURQUOISE "%s" RESET " = [ ",  \
                file, line, func_name, expr);                                  \
        for (size_t i = 0; i < length; i++) {                                  \
            if (i)                                                             \
                fprintf(DBG_OUTSTREAM, ", ");                                  \
            fprintf(DBG_OUTSTREAM, fmt, array[i]);                             \
        }                                                                      \
        fprintf(DBG_OUTSTREAM, " ] with length = %zu\n", length);              \
        return array;                                                          \
    }

Macro to declare a debug function for an array.

This macro declares a debug function for the specified array type.

Parameters

type	The type of the array elements.
name	The name of the debug function.
fmt	The format string for the array elements.

Example usage:

DBG_ARRAY_FUNC_DECL(const char **, string, "\"%s\"");
// create a function following the prototype:
// static inline const char **dbg_array_string(const char *file,
//                                             unsigned int line,
//                                             const char *func_name,
//                                             const char *expr,
//                                             const char **array,
//                                             size_t length);
// This function can now be called using CALL_DBG_ARRAY() macro
int main(int argc, char **argv) {
    CALL_DBG_ARRAY(dbg_array_string, (const char **)argv, argc);
    return 0;

Examples

example_debug.c.

DBG_FUNC_DECL

#define DBG_FUNC_DECL	(		type,
			name,
			fmt )

Value:

    static inline type dbg_##name(const char *file, unsigned int line,         \
                                  const char *func_name, const char *expr,     \
                                  type value) {                                \
        fprintf(DBG_OUTSTREAM,                                                 \
                GRAY "%s:%u in %s()" RESET ": " TURQUOISE "%s" RESET " = " fmt \
                     "\n",                                                     \
                file, line, func_name, expr, value);                           \
        return value;                                                          \
    }

Macro to declare a debug function for a variable.

This macro declares a debug function for the specified variable type.

Parameters

type	The type of the variable.
name	The name of the debug function.
fmt	The format string for the variable value.

Example usage:

DBG_FUNC_DECL(int, my_int, "%d");
// create a function following the prototype:
// static inline int dbg_my_int(const char *file, unsigned int line,
//                              const char *func_name, const char *expr,
//                              int value);
// This function can now be called using CALL_DBG() macro
int main(int argc, char **argv) {
    CALL_DBG(dbg_my_int, argc);
    return 0;
}

DBG_OUTSTREAM

#define DBG_OUTSTREAM   stderr

Macro for the debug output stream.

This macro allow you to set the debuf output stream as you want (file/stdio/stderr). By default, if undefined, it is an alias of the stderr standard stream.

RESET

#define RESET   "\033[0m"

SOURCE_PATH_SIZE

#define SOURCE_PATH_SIZE   0

Macro to truncate the root file path.

This macro is useful when the project is compiled with CMake, allowing for a cleaner file path in logs by removing a fixed number of characters from the start of the __FILE__ macro. The default value if the macro wasn't defined earlier is 0.

Function Documentation

set_breakpoint()

void set_breakpoint

(

void

)

Function to set a breakpoint for debugging.

This function raises a SIGTRAP signal, which causes the program to stop and enter a state where a debugger can be attached. It is useful for setting breakpoints in code.

Examples

example_debug.c.