---
name: "log4c_category.h"
section: "3"
platform: "linux"
package: "liblog4c-doc"
version: "1.2.4-5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/log4c_category.h"
---

# log4c\_category.h(3)

central class in the log4c package.

## NAME

category.h - central class in the log4c package.

## SYNOPSIS

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

### 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

### #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

### typedef struct \_\_log4c\_category log4c\_category\_t

log4c category class

## Function Documentation

### 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**.

### 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**.

### 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**.

### 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**.

### void log4c\_category\_delete (log4c\_category\_t \* a\_category)

Destructor for a log4c\_category\_t.

**Parameters**

*a\_category* the log4c\_category\_t object

### 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**.

### 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\_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'. \*

### 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

### 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.

### 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**.

### 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.

### 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**.

### 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**.

### 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**.

### 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**.

### 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**.

### 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**.

### 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**.

### 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**.

### 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**.

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

### 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**.

### 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**.

### 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.

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

### 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\_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**.

### 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**.

### 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

### 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

### 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

### 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**.

### 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**.

## Author

Generated automatically by Doxygen for log4c from the source code.