category.h File Reference

central class in the log4c package. More...

`#include <stdio.h>`
`#include <stdarg.h>`
`#include <log4c/defs.h>`
`#include <log4c/priority.h>`
`#include <log4c/location_info.h>`

Go to the source code of this file.

## Macros

#define | log4c_category_define(a_category, a_name)

## Typedefs

typedef struct __log4c_category | log4c_category_t

## Functions

log4c_category_t * | log4c_category_get (const char *a_name)
int | log4c_category_list (log4c_category_t **a_cats, int a_ncats)
log4c_category_t * | log4c_category_new (const char *a_name)
void | log4c_category_delete (log4c_category_t *a_category)
const char * | log4c_category_get_name (const log4c_category_t *a_category)
const struct __log4c_appender * | log4c_category_get_appender (const log4c_category_t *a_category)
int | log4c_category_get_additivity (const log4c_category_t *a_category)
int | log4c_category_get_priority (const log4c_category_t *a_category)
int | log4c_category_get_chainedpriority (const log4c_category_t *a_category)
const struct __log4c_appender * | log4c_category_set_appender (log4c_category_t *a_category, struct __log4c_appender *a_appender)
int | log4c_category_set_priority (log4c_category_t *a_category, int a_priority)
int | log4c_category_set_additivity (log4c_category_t *a_category, int a_additivity)
void | log4c_category_print (const log4c_category_t *a_category, FILE *a_stream)
static int | log4c_category_is_priority_enabled (const log4c_category_t *a_category, int a_priority)
static int | log4c_category_is_fatal_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_alert_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_crit_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_error_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_warn_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_notice_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_info_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_debug_enabled (const log4c_category_t *a_category)
static int | log4c_category_is_trace_enabled (const log4c_category_t *a_category)
static LOG4C_INLINE void | log4c_category_log (const log4c_category_t *a_category, int a_priority, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_log_locinfo (const log4c_category_t *a_category, const log4c_location_info_t *a_locinfo, int a_priority, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_fatal (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_alert (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_crit (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_error (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_warn (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_notice (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_info (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | log4c_category_debug (const log4c_category_t *a_category, const char *a_format,...)
static LOG4C_INLINE void | __log4c_category_trace (const log4c_category_t *a_category, const char *a_format,...)

## Detailed Description

central class in the log4c package.

One of the distintive features of log4j (and hence log4c) are hierarchical categories and their evaluation.

## Macro Definition Documentation

## log4c_category_define

#define log4c_category_define | ( |  | a_category,
|  |  | a_name
| ) |  |

Helper macro to define static categories.

Parameters

  a_category | the log4c_category_t pointer name
  a_name | the category name

## Typedef Documentation

## log4c_category_t

typedef struct __log4c_category log4c_category_t

log4c category class

## Function Documentation

## __log4c_category_trace()

static LOG4C_INLINE void __log4c_category_trace | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with trace priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_TRACE.

## log4c_category_alert()

static LOG4C_INLINE void log4c_category_alert | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with alert priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_ALERT.

## log4c_category_crit()

static LOG4C_INLINE void log4c_category_crit | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with crit priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_CRIT.

## log4c_category_debug()

static LOG4C_INLINE void log4c_category_debug | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with debug priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_DEBUG.

## log4c_category_delete()

void log4c_category_delete | ( | log4c_category_t * | a_category | ) |

Destructor for a log4c_category_t.

Parameters

  a_category | the log4c_category_t object

## log4c_category_error()

static LOG4C_INLINE void log4c_category_error | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with error priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_ERROR.

## log4c_category_fatal()

static LOG4C_INLINE void log4c_category_fatal | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with fatal priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_FATAL.

## log4c_category_get()

log4c_category_t * log4c_category_get | ( | const char * | a_name | ) |

Instantiate a log4c_category_t with name name. This method does not set priority of the category which is by default `LOG4C_PRIORITY_NOTSET`.

Parameters

  a_name | The name of the category to retrieve.

Bug:
  the root category name should be "" not "root". *

## log4c_category_get_additivity()

int log4c_category_get_additivity | ( | const log4c_category_t * | a_category | ) |

Get the additivity flag for this log4c_category_t..

Parameters

  a_category | the log4c_category_t object

Returns
  the category additivity

## log4c_category_get_appender()

const struct __log4c_appender * log4c_category_get_appender | ( | const log4c_category_t * | a_category | ) |

Returns the Appender for this log4c_category_t, or NULL if no Appender has been set.

Parameters

  a_category | the log4c_category_t object

Returns
  The Appender.

## log4c_category_get_chainedpriority()

int log4c_category_get_chainedpriority | ( | const log4c_category_t * | a_category | ) |

Starting from this category, search the category hierarchy for a set priority and return it. Otherwise, return the priority of the root category.

Parameters

  a_category | the log4c_category_t object

Todo:
  the log4c_category_t is designed so that this method executes as quickly as possible. It could even be faster if the set priority was propagated through the children hierarchy of a category.

References LOG4C_PRIORITY_NOTSET, and LOG4C_PRIORITY_UNKNOWN.

## log4c_category_get_name()

const char * log4c_category_get_name | ( | const log4c_category_t * | a_category | ) |

Return the category name.

Parameters

  a_category | the log4c_category_t object

Returns
  the category name.

## log4c_category_get_priority()

int log4c_category_get_priority | ( | const log4c_category_t * | a_category | ) |

Returns the assigned Priority, if any, for this log4c_category_t.

Parameters

  a_category | the log4c_category_t object

Returns
  Priority - the assigned Priority, can be LOG4C_PRIORITY_NOTSET

References LOG4C_PRIORITY_UNKNOWN.

## log4c_category_info()

static LOG4C_INLINE void log4c_category_info | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with info priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_INFO.

## log4c_category_is_alert_enabled()

static int log4c_category_is_alert_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_ALERT`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_ALERT.

## log4c_category_is_crit_enabled()

static int log4c_category_is_crit_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_CRIT`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_CRIT.

## log4c_category_is_debug_enabled()

static int log4c_category_is_debug_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_DEBUG`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_DEBUG.

## log4c_category_is_error_enabled()

static int log4c_category_is_error_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_ERROR`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_ERROR.

## log4c_category_is_fatal_enabled()

static int log4c_category_is_fatal_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_FATAL`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_FATAL.

## log4c_category_is_info_enabled()

static int log4c_category_is_info_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_INFO`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_INFO.

## log4c_category_is_notice_enabled()

static int log4c_category_is_notice_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_NOTICE`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_NOTICE.

## log4c_category_is_priority_enabled()

static int log4c_category_is_priority_enabled | ( | const log4c_category_t * | a_category,
|  | int | a_priority
| ) |  |

inline static

Returns true if the chained priority of the log4c_category_t is equal to or higher than given priority.

Parameters

  a_category | the log4c_category_t object
  a_priority | The priority to compare with.

Returns
  whether logging is enable for this priority.

References log4c_category_get_chainedpriority().

## log4c_category_is_trace_enabled()

static int log4c_category_is_trace_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_TRACE`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_TRACE.

## log4c_category_is_warn_enabled()

static int log4c_category_is_warn_enabled | ( | const log4c_category_t * | a_category | ) |

inline static

Return true if the category will log messages with priority `LOG4C_PRIORITY_WARN`.

Parameters

  a_category | the log4c_category_t object

Returns
  Whether the category will log.

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_WARN.

## log4c_category_list()

int log4c_category_list | ( | log4c_category_t ** | a_cats,
|  | int | a_ncats
| ) |  |

Fill in an array with the log4c categories.

Parameters

  a_cats | array of categories that will be filled
  a_ncats | number of categories in the array

Returns
  -1 if it fails or the number of available categories in log4c.

## log4c_category_log()

static LOG4C_INLINE void log4c_category_log | ( | const log4c_category_t * | a_category,
|  | int | a_priority,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with the specified priority.

Parameters

  a_category | the log4c_category_t object
  a_priority | The priority of this log message.
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled().

## log4c_category_log_locinfo()

static LOG4C_INLINE void log4c_category_log_locinfo | ( | const log4c_category_t * | a_category,
|  | const log4c_location_info_t * | a_locinfo,
|  | int | a_priority,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with the specified priority and a user location info.

Parameters

  a_category | the log4c_category_t object
  a_locinfo | a user location info
  a_priority | The priority of this log message.
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled().

## log4c_category_new()

log4c_category_t * log4c_category_new | ( | const char * | a_name | ) |

Constructor for a log4c_category_t.

Parameters

  a_name | the category name

Returns
  a log4c_category object

Warning
  this method should not be called directly. You should use the log4c_category_get() method in order to preserve the categories hierarchy.

References LOG4C_PRIORITY_NOTSET.

## log4c_category_notice()

static LOG4C_INLINE void log4c_category_notice | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with notice priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_NOTICE.

## log4c_category_print()

void log4c_category_print | ( | const log4c_category_t * | a_category,
|  | FILE * | a_stream
| ) |  |

prints the log4c_category_t object on a stream

Parameters

  a_category | the log4c_category_t object
  a_stream | The stream

## log4c_category_set_additivity()

int log4c_category_set_additivity | ( | log4c_category_t * | a_category,
|  | int | a_additivity
| ) |  |

Sets a new additivity flag for this category.

Parameters

  a_category | the log4c_category_t object
  a_additivity | the new category additivity

Returns
  the previous category additivity

## log4c_category_set_appender()

const struct __log4c_appender * log4c_category_set_appender | ( | log4c_category_t * | this,
|  | log4c_appender_t * | a_appender
| ) |  |

Sets a new appender for this category.

Parameters

  a_category | the log4c_category_t object
  a_appender | the new category appender

Returns
  the previous category appender

Todo:
  need multiple appenders per category

## log4c_category_set_priority()

int log4c_category_set_priority | ( | log4c_category_t * | a_category,
|  | int | a_priority
| ) |  |

Sets a new priority of this category.

Parameters

  a_category | the log4c_category_t object
  a_priority | the new priority to set. Use LOG4C_PRIORITY_NOTSET to let the category use its parents priority as effective priority.

Returns
  the previous category priority

References LOG4C_PRIORITY_UNKNOWN.

## log4c_category_warn()

static LOG4C_INLINE void log4c_category_warn | ( | const log4c_category_t * | a_category,
|  | const char * | a_format,
|  |  | ...
| ) |  |

static

Log a message with warn priority.

Parameters

  a_category | the log4c_category_t object
  a_format | Format specifier for the string to write in the log file.
  ... | The arguments for a_format

References log4c_category_is_priority_enabled(), and LOG4C_PRIORITY_WARN.