logger_category.c File Reference

#include "asterisk.h"
#include "asterisk/cli.h"
#include "asterisk/conversions.h"
#include "asterisk/logger_category.h"
#include "asterisk/vector.h"

Include dependency graph for logger_category.c:

Go to the source code of this file.

Data Structures
struct	categories_level_t
struct	category_t

Functions
char *	ast_debug_category_complete (const char *const *argv, int argc, const char *word, int state)
	Add a unique (no duplicates) result to a request for completion for debug categories.
int	ast_debug_category_is_allowed (int sublevel, uintmax_t ids)
	Check if a debug category is enabled, and allowed to output.
uintmax_t	ast_debug_category_register (const char *name)
	Register a debug level logger category.
int	ast_debug_category_set_sublevel (const char *name, int sublevel)
	Set the debug category's sublevel.
int	ast_debug_category_set_sublevels (const char *const *names, size_t size, int default_sublevel)
	Set one or more debug category's sublevel.
int	ast_debug_category_unregister (const char *name)
	Un-register a debug level logger category.
int	ast_logger_category_load (void)
	Load/Initialize system wide logger category functionality.
int	ast_logger_category_unload (void)
	Unload system wide logger category functionality.
	AST_VECTOR_RW (categories_t, struct category_t *)
static int	casecmp_by_name (const struct category_t *category, const char *name)
static char *	category_complete (struct categories_level_t *level, const char *const *argv, int argc, const char *word, int state)
static int	category_is_allowed (int sublevel, struct categories_level_t *level, uintmax_t ids)
static uintmax_t	category_register (struct categories_level_t *level, const char *name)
static int	category_set_sublevel (struct category_t *category, struct categories_level_t *level, const char *name, int sublevel)
static int	category_set_sublevels (struct categories_level_t *level, const char *const *names, size_t size, int default_sublevel)
static int	category_unregister (struct categories_level_t *level, const char *name)
static int	cmp_by_name (const struct category_t *category, const char *name)
static uintmax_t	get_next_id (struct categories_level_t *level)
	Retrieve the next available id.

Variables
static struct categories_level_t	debug_categories

Function Documentation

ast_debug_category_complete()

char * ast_debug_category_complete	(	const char *const *	argv,
		int	argc,
		const char *	word,
		int	state
	)

Add a unique (no duplicates) result to a request for completion for debug categories.

Parameters

argv	A list of already completed options
argc	The number of already completed options
word	The word to complete
state	The state

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 300 of file logger_category.c.

{
    return category_complete(&debug_categories, argv, argc, word, state);
}

References category_complete(), and debug_categories.

Referenced by handle_debug_category().

ast_debug_category_is_allowed()

int ast_debug_category_is_allowed	(	int	sublevel,
		uintmax_t	ids
	)

Check if a debug category is enabled, and allowed to output.

Note

If more than one id is specified then if even one is allowed "true" is returned.

Parameters

sublevel	Current set sublevel must be this sublevel or less
ids	One or more unique category ids to check

Return values

1	if allowed
0	if not allowed

Since

16.14

17.8

18.0

Definition at line 306 of file logger_category.c.

{
    return category_is_allowed(sublevel, &debug_categories, ids);
}

References category_is_allowed(), debug_categories, and categories_level_t::sublevel.

ast_debug_category_register()

uintmax_t ast_debug_category_register

(

const char *

name

)

Register a debug level logger category.

Parameters

name	The name of the category

Return values

0	if failed to register/retrieve an id

Returns

id for the registered category

Since

16.14

17.8

18.0

Definition at line 279 of file logger_category.c.

{
    return category_register(&debug_categories, name);
}

References category_register(), debug_categories, and name.

Referenced by ast_rtp_engine_init(), and ast_stun_init().

ast_debug_category_set_sublevel()

int ast_debug_category_set_sublevel	(	const char *	name,
		int	sublevel
	)

Set the debug category's sublevel.

Statements are output at a specified sublevel. Typically any number greater than or equal to 0. Other acceptable values include AST_LOG_CATEGORY_ENABLED and AST_LOG_CATEGORY_DISABLED.

Parameters

name	The name of the category
sublevel	The debug sublevel output number

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 289 of file logger_category.c.

{
    return category_set_sublevel(NULL, &debug_categories, name, sublevel);
}

References category_set_sublevel(), debug_categories, name, NULL, and categories_level_t::sublevel.

Referenced by handle_cli_rtcp_set_debug(), handle_cli_rtp_set_debug(), handle_cli_stun_set_debug(), rtcp_do_debug_ip(), and rtp_do_debug_ip().

ast_debug_category_set_sublevels()

int ast_debug_category_set_sublevels	(	const char *const *	names,
		size_t	size,
		int	default_sublevel
	)

Set one or more debug category's sublevel.

Accepts an array of category names, and optional associated sublevels. Sublevels can be associated with a name by using a ':' as a separator. For example:

<category name>:<category sublevel> 

The given default sublevel is used if no sublevel is associated with a name.

Parameters

names	An array of category names
size	The size of the array (number of elements)
default_sublevel	The sublevel value to use if one is not associated with a name

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 294 of file logger_category.c.

{
    return category_set_sublevels(&debug_categories, names, size, default_sublevel);
}

References category_set_sublevels(), and debug_categories.

Referenced by handle_debug_category().

ast_debug_category_unregister()

int ast_debug_category_unregister

(

const char *

name

)

Un-register a debug level logger category.

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 284 of file logger_category.c.

{
    return category_unregister(&debug_categories, name);
}

References category_unregister(), debug_categories, and name.

Referenced by rtp_engine_atexit(), and stun_shutdown().

ast_logger_category_load()

int ast_logger_category_load

(

void

)

Load/Initialize system wide logger category functionality.

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 317 of file logger_category.c.

{
    if (AST_VECTOR_RW_INIT(&debug_categories.categories, 10)) {
        return -1;
    }
 
    return 0;
}

References AST_VECTOR_RW_INIT, categories_level_t::categories, and debug_categories.

Referenced by init_logger().

ast_logger_category_unload()

int ast_logger_category_unload

(

void

)

Unload system wide logger category functionality.

Return values

0	Success
-1	Failure

Since

16.14

17.8

18.0

Definition at line 311 of file logger_category.c.

{
    AST_VECTOR_RW_FREE(&debug_categories.categories);
    return 0;
}

References AST_VECTOR_RW_FREE, categories_level_t::categories, and debug_categories.

Referenced by close_logger().

AST_VECTOR_RW()

AST_VECTOR_RW	(	categories_t	,
		struct category_t *
	)

casecmp_by_name()

static int casecmp_by_name ( const struct category_t *  category, const char *  name  )

static

Definition at line 113 of file logger_category.c.

{
    return !strcasecmp(category->name, name);
}

References category_t::name, and name.

Referenced by category_set_sublevel().

category_complete()

static char * category_complete ( struct categories_level_t *  level, const char *const *  argv, int  argc, const char *  word, int  state  )

static

Definition at line 196 of file logger_category.c.

{
    int wordlen = strlen(word);
    int which = 0;
    int i, j;
 
    AST_VECTOR_RW_RDLOCK(&level->categories);
 
    if (argc == AST_VECTOR_SIZE(&level->categories)) {
        AST_VECTOR_RW_UNLOCK(&level->categories);
        return NULL;
    }
 
    for (i = 0; i < AST_VECTOR_SIZE(&level->categories); ++i) {
        struct category_t *category = AST_VECTOR_GET(&level->categories, i);
 
        if (!strncasecmp(word, category->name, wordlen) && (++which > state)) {
            /* Check to see if one is already been included */
            for (j = 0; j < argc; ++j) {
                if (!strncasecmp(category->name, argv[j], strlen(category->name))) {
                    break;
                }
            }
 
            if (j != argc) {
                continue;
            }
 
            if (state != -1) {
                AST_VECTOR_RW_UNLOCK(&level->categories);
                return ast_strdup(category->name);
            }
 
            if (ast_cli_completion_add(ast_strdup(category->name))) {
                AST_VECTOR_RW_UNLOCK(&level->categories);
                return NULL;
            }
        }
    }
 
    AST_VECTOR_RW_UNLOCK(&level->categories);
    return NULL;
}

References ast_cli_completion_add(), ast_strdup, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, categories_level_t::categories, category_t::name, and NULL.

Referenced by ast_debug_category_complete().

category_is_allowed()

static int category_is_allowed ( int  sublevel, struct categories_level_t *  level, uintmax_t  ids  )

static

Definition at line 241 of file logger_category.c.

{
    /* Check level, and potentially allow but only if there is a matching state enabled */
    if (ids & level->state) {
        int i;
 
        if (sublevel == AST_LOG_CATEGORY_ENABLED || sublevel == 0) {
            /* If at least one id is enabled then always allow these sublevels */
            return 1;
        }
 
        AST_VECTOR_RW_RDLOCK(&level->categories);
        for (i = 0; i < AST_VECTOR_SIZE(&level->categories); ++i) {
            struct category_t *category = AST_VECTOR_GET(&level->categories, i);
 
            /*
             * If there is at least one matching category, and that category is enabled
             * or its sub-level is at or above the given sub-level then allow.
             */
            if ((category->id & ids) && category->sublevel != AST_LOG_CATEGORY_DISABLED &&
                (category->sublevel == AST_LOG_CATEGORY_ENABLED || category->sublevel >= sublevel)) {
                AST_VECTOR_RW_UNLOCK(&level->categories);
                return 1;
            }
        }
        AST_VECTOR_RW_UNLOCK(&level->categories);
    }
 
    return 0;
}

References AST_LOG_CATEGORY_DISABLED, AST_LOG_CATEGORY_ENABLED, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, categories_level_t::categories, category_t::id, categories_level_t::state, and category_t::sublevel.

Referenced by ast_debug_category_is_allowed().

category_register()

static uintmax_t category_register ( struct categories_level_t *  level, const char *  name  )

static

Definition at line 66 of file logger_category.c.

{
    int i;
    struct category_t *category;
 
    AST_VECTOR_RW_WRLOCK(&level->categories);
 
    i = AST_VECTOR_GET_INDEX(&level->categories, name, cmp_by_name);
    if (i >= 0) {
        AST_VECTOR_RW_UNLOCK(&level->categories);
        ast_log(LOG_ERROR, "Cannot register logger category '%s'. "
                "Name already used for type.\n", name);
        return 0;
    }
 
    category = ast_calloc(1, sizeof(*category) + strlen(name) + 1);
    if (!category) {
        AST_VECTOR_RW_UNLOCK(&level->categories);
        return 0;
    }
 
    category->id = get_next_id(level);
    category->sublevel = AST_LOG_CATEGORY_DISABLED;
    strcpy(category->name, name); /* Safe */
 
    if (AST_VECTOR_APPEND(&level->categories, category)) {
        AST_VECTOR_RW_UNLOCK(&level->categories);
        ast_log(LOG_ERROR, "Cannot register logger category '%s'. "
                "Unable to append.\n", name);
        return 0;
    }
 
    AST_VECTOR_RW_UNLOCK(&level->categories);
    return category->id;
}

References ast_calloc, ast_log, AST_LOG_CATEGORY_DISABLED, AST_VECTOR_APPEND, AST_VECTOR_GET_INDEX, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, categories_level_t::categories, cmp_by_name(), get_next_id(), category_t::id, LOG_ERROR, category_t::name, name, and category_t::sublevel.

Referenced by ast_debug_category_register().

category_set_sublevel()

static int category_set_sublevel ( struct category_t *  category, struct categories_level_t *  level, const char *  name, int  sublevel  )

static

Definition at line 118 of file logger_category.c.

{
    int locked = 0;
 
    if (!category) {
        struct category_t **obj;
 
        if (!name) {
            return -1;
        }
 
        locked = !AST_VECTOR_RW_WRLOCK(&level->categories);
        if (!locked) {
            return -1;
        }
 
        obj = AST_VECTOR_GET_CMP(&level->categories, name, casecmp_by_name);
        if (!obj) {
            AST_VECTOR_RW_UNLOCK(&level->categories);
            return -1;
        }
 
        category = *obj;
    }
 
    category->sublevel = sublevel;
 
    if (category->sublevel == AST_LOG_CATEGORY_DISABLED) {
        level->state &= ~category->id;
    } else {
        level->state |= category->id;
    }
 
    if (locked) {
        AST_VECTOR_RW_UNLOCK(&level->categories);
    }
 
    return 0;
}

References AST_LOG_CATEGORY_DISABLED, AST_VECTOR_GET_CMP, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, casecmp_by_name(), categories_level_t::categories, category_t::id, name, categories_level_t::state, and category_t::sublevel.

Referenced by ast_debug_category_set_sublevel(), and category_set_sublevels().

category_set_sublevels()

static int category_set_sublevels ( struct categories_level_t *  level, const char *const *  names, size_t  size, int  default_sublevel  )

static

Definition at line 159 of file logger_category.c.

{
    int i;
 
    if (!names || !size) {
        level->state = default_sublevel;
        AST_VECTOR_RW_WRLOCK(&level->categories);
        AST_VECTOR_CALLBACK_VOID(&level->categories, category_set_sublevel,
            level, NULL, default_sublevel);
        AST_VECTOR_RW_UNLOCK(&level->categories);
        return 0;
    }
 
    for (i = 0; i < size; ++i) {
        const char *sublevel;
        int num = default_sublevel;
 
        sublevel = strchr(names[i], ':');
        if (sublevel) {
            size_t len = ++sublevel - names[i];
            char name[len];
 
            if (*sublevel && ast_str_to_int(sublevel, &num)) {
                continue;
            }
 
            ast_copy_string(name, names[i], len);
            category_set_sublevel(NULL, level, name, num);
        } else {
            category_set_sublevel(NULL, level, names[i], num);
        }
    }
 
    return 0;
}

References ast_copy_string(), ast_str_to_int(), AST_VECTOR_CALLBACK_VOID, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, categories_level_t::categories, category_set_sublevel(), len(), name, NULL, categories_level_t::state, and category_t::sublevel.

Referenced by ast_debug_category_set_sublevels().

category_unregister()

static int category_unregister ( struct categories_level_t *  level, const char *  name  )

static

Definition at line 102 of file logger_category.c.

{
    int res;
 
    AST_VECTOR_RW_WRLOCK(&level->categories);
    res = AST_VECTOR_REMOVE_CMP_UNORDERED(&level->categories, name, cmp_by_name, ast_free);
    AST_VECTOR_RW_UNLOCK(&level->categories);
 
    return res;
}

References ast_free, AST_VECTOR_REMOVE_CMP_UNORDERED, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, categories_level_t::categories, cmp_by_name(), and name.

Referenced by ast_debug_category_unregister().

cmp_by_name()

static int cmp_by_name ( const struct category_t *  category, const char *  name  )

static

Definition at line 61 of file logger_category.c.

{
    return !strcmp(category->name, name);
}

References category_t::name, and name.

Referenced by category_register(), and category_unregister().

get_next_id()

static uintmax_t get_next_id ( struct categories_level_t *  level )

static

Retrieve the next available id.

Ids must be a power of 2. This allows for fast lookup, and "or'ing" of ids in order to permit multiple categories in a log statement.

Definition at line 47 of file logger_category.c.

{
    if (level->id_pool == 0) {
        level->id_pool = 1;
    } else if (level->id_pool >= (UINTMAX_MAX / 2)) {
        /* No more ids left*/
        return 0;
    } else {
        level->id_pool <<= 1;
    }
 
    return level->id_pool;
}

References categories_level_t::id_pool.

Referenced by category_register().

Variable Documentation

debug_categories

struct categories_level_t debug_categories

static

Definition at line 272 of file logger_category.c.

                                                    {
    .type = __LOG_DEBUG,
    .sublevel = 0,
    .id_pool = 0,
    .state = 0,
};

Referenced by ast_debug_category_complete(), ast_debug_category_is_allowed(), ast_debug_category_register(), ast_debug_category_set_sublevel(), ast_debug_category_set_sublevels(), ast_debug_category_unregister(), ast_logger_category_load(), and ast_logger_category_unload().