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. More...
int	ast_debug_category_is_allowed (int sublevel, uintmax_t ids)
	Check if a debug category is enabled, and allowed to output. More...
uintmax_t	ast_debug_category_register (const char *name)
	Register a debug level logger category. More...
int	ast_debug_category_set_sublevel (const char *name, int sublevel)
	Set the debug category's sublevel. More...
int	ast_debug_category_set_sublevels (const char *const *names, size_t size, int default_sublevel)
	Set one or more debug category's sublevel. More...
int	ast_debug_category_unregister (const char *name)
	Un-register a debug level logger category. More...
int	ast_logger_category_load (void)
	Load/Initialize system wide logger category functionality. More...
int	ast_logger_category_unload (void)
	Unload system wide logger category functionality. More...
	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. More...

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.

References category_complete().

Referenced by handle_debug_category().

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

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.

References category_is_allowed().

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

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
id	The unique id of the category

Return values

0	if failed to register/retrieve an id. Otherwise it returns the id for the registered category.

Since

16.14

17.8

18.0

Definition at line 279 of file logger_category.c.

References category_register().

Referenced by ast_rtp_engine_init(), and ast_stun_init().

{
   return category_register(&debug_categories, name);
}

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.

References category_set_sublevel(), and NULL.

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().

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

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.

References category_set_sublevels().

Referenced by handle_debug_category().

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

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.

References category_unregister().

Referenced by rtp_engine_shutdown(), and stun_shutdown().

{
   return category_unregister(&debug_categories, name);
}

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.

References AST_VECTOR_RW_INIT, and categories_level_t::categories.

Referenced by init_logger().

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

   return 0;
}

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.

References AST_VECTOR_RW_FREE, and categories_level_t::categories.

Referenced by close_logger().

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

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.

References category_t::name.

Referenced by category_set_sublevel().

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

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.

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().

{
   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;
}

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.

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().

{
   /* 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;
}

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.

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, and category_t::sublevel.

Referenced by ast_debug_category_register().

{
   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;
}

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.

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, categories_level_t::state, and category_t::sublevel.

Referenced by ast_debug_category_set_sublevel(), and category_set_sublevels().

{
   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;
}

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.

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(), category_t::name, NULL, categories_level_t::state, and category_t::sublevel.

Referenced by ast_debug_category_set_sublevels().

{
   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;
}

category_unregister()

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

static

Definition at line 102 of file logger_category.c.

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

Referenced by ast_debug_category_unregister().

{
   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;
}

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.

References category_t::name.

Referenced by category_register(), and category_unregister().

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

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.

References categories_level_t::id_pool.

Referenced by category_register().

{
   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;
}

Variable Documentation

debug_categories

struct categories_level_t debug_categories

static

Definition at line 272 of file logger_category.c.