--- name: "rte_log.h" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_log.h" --- # rte\_log.h(3) ## NAME rte\_log.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### Macros \#define **RTE\_LOGTYPE\_EAL** 0\ \#define **RTE\_LOGTYPE\_USER1** 24\ \#define **RTE\_LOGTYPE\_USER2** 25\ \#define **RTE\_LOGTYPE\_USER3** 26\ \#define **RTE\_LOGTYPE\_USER4** 27\ \#define **RTE\_LOGTYPE\_USER5** 28\ \#define **RTE\_LOGTYPE\_USER6** 29\ \#define **RTE\_LOGTYPE\_USER7** 30\ \#define **RTE\_LOGTYPE\_USER8** 31\ \#define **RTE\_LOGTYPE\_FIRST\_EXT\_ID** 32\ \#define **RTE\_LOG\_EMERG** 1U\ \#define **RTE\_LOG\_ALERT** 2U\ \#define **RTE\_LOG\_CRIT** 3U\ \#define **RTE\_LOG\_ERR** 4U\ \#define **RTE\_LOG\_WARNING** 5U\ \#define **RTE\_LOG\_NOTICE** 6U\ \#define **RTE\_LOG\_INFO** 7U\ \#define **RTE\_LOG\_DEBUG** 8U\ \#define **RTE\_LOG\_MAX** **RTE\_LOG\_DEBUG**\ \#define **RTE\_LOG**(l, t, ...)\ \#define **RTE\_LOG\_DP**(l, t, ...)\ \#define **RTE\_LOG\_LINE**(l, t, ...)\ \#define **RTE\_LOG\_DP\_LINE**(l, t, ...)\ \#define **RTE\_LOG\_LINE\_PREFIX**(l, t, prefix, args, ...)\ \#define **RTE\_LOG\_DP\_LINE\_PREFIX**(l, t, prefix, args, ...)\ \#define **RTE\_LOG\_REGISTER**(type, name, level) RTE\_LOG\_REGISTER\_IMPL(type, **RTE\_STR**(name), level)\ \#define **RTE\_LOG\_REGISTER\_DEFAULT**(type, level) RTE\_LOG\_REGISTER\_IMPL(type, **RTE\_STR**(RTE\_LOG\_DEFAULT\_LOGTYPE), level)\ \#define **RTE\_LOG\_REGISTER\_SUFFIX**(type, suffix, level)\ ### Functions int **rte\_openlog\_stream** (FILE \*f)\ FILE \* **rte\_log\_get\_stream** (void)\ void **rte\_log\_set\_global\_level** (uint32\_t level)\ uint32\_t **rte\_log\_get\_global\_level** (void)\ int **rte\_log\_get\_level** (uint32\_t logtype)\ bool **rte\_log\_can\_log** (uint32\_t logtype, uint32\_t loglevel)\ int **rte\_log\_set\_level\_pattern** (const char \*pattern, uint32\_t level)\ int **rte\_log\_set\_level\_regexp** (const char \*regex, uint32\_t level)\ int **rte\_log\_set\_level** (uint32\_t logtype, uint32\_t level)\ int **rte\_log\_cur\_msg\_loglevel** (void)\ int **rte\_log\_cur\_msg\_logtype** (void)\ int **rte\_log\_register** (const char \*name)\ int **rte\_log\_register\_type\_and\_pick\_level** (const char \*name, uint32\_t level\_def)\ void **rte\_log\_list\_types** (FILE \*out, const char \*prefix)\ void **rte\_log\_dump** (FILE \*f)\ int **rte\_log** (uint32\_t level, uint32\_t logtype, const char \*format,...) **\_\_rte\_cold** **\_\_rte\_format\_printf**(3\ int int **rte\_vlog** (uint32\_t level, uint32\_t logtype, const char \*format, va\_list ap) **\_\_rte\_format\_printf**(3\ ## Detailed Description RTE Logs API This file provides a log API to RTE applications. Definition in file **rte\_log.h**. ## Macro Definition Documentation ### #define RTE\_LOGTYPE\_EAL 0 Log related to eal. Definition at line **30** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER1 24 User-defined log type 1. Definition at line **53** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER2 25 User-defined log type 2. Definition at line **54** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER3 26 User-defined log type 3. Definition at line **55** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER4 27 User-defined log type 4. Definition at line **56** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER5 28 User-defined log type 5. Definition at line **57** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER6 29 User-defined log type 6. Definition at line **58** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER7 30 User-defined log type 7. Definition at line **59** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_USER8 31 User-defined log type 8. Definition at line **60** of file **rte\_log.h**. ### #define RTE\_LOGTYPE\_FIRST\_EXT\_ID 32 First identifier for extended logs Definition at line **63** of file **rte\_log.h**. ### #define RTE\_LOG\_EMERG 1U System is unusable. \ Definition at line **66** of file **rte\_log.h**. ### #define RTE\_LOG\_ALERT 2U Action must be taken immediately. Definition at line **67** of file **rte\_log.h**. ### #define RTE\_LOG\_CRIT 3U Critical conditions. \ Definition at line **68** of file **rte\_log.h**. ### #define RTE\_LOG\_ERR 4U Error conditions. \ Definition at line **69** of file **rte\_log.h**. ### #define RTE\_LOG\_WARNING 5U Warning conditions. \ Definition at line **70** of file **rte\_log.h**. ### #define RTE\_LOG\_NOTICE 6U Normal but significant condition. Definition at line **71** of file **rte\_log.h**. ### #define RTE\_LOG\_INFO 7U Informational. \ Definition at line **72** of file **rte\_log.h**. ### #define RTE\_LOG\_DEBUG 8U Debug-level messages. \ Definition at line **73** of file **rte\_log.h**. ### #define RTE\_LOG\_MAX RTE\_LOG\_DEBUG Most detailed log level. \ Definition at line **74** of file **rte\_log.h**. ### #define RTE\_LOG(l, t, ...) **Value:**.PP ``` rte_log(RTE_LOG_ ## l, \ RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) ``` Generates a log message. The **RTE\_LOG()** is a helper that prefixes the string with the log level and type, and call **rte\_log()**. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. **Returns** - • 0: Success. - • Negative on error. Definition at line **332** of file **rte\_log.h**. ### #define RTE\_LOG\_DP(l, t, ...) **Value:**.PP ``` (void)((RTE_LOG_ ## l <= RTE_LOG_DP_LEVEL) ? \ rte_log(RTE_LOG_ ## l, \ RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) : \ 0) ``` Generates a log message for data path. Similar to **RTE\_LOG()**, except that it is removed at compilation time if the RTE\_LOG\_DP\_LEVEL configuration option is lower than the log level argument. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. **Returns** - • 0: Success. - • Negative on error. Definition at line **356** of file **rte\_log.h**. ### #define RTE\_LOG\_LINE(l, t, ...) **Value:**.PP ``` do { \ RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(__VA_ARGS__ ,)); \ RTE_LOG(l, t, RTE_FMT(RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ RTE_FMT_TAIL(__VA_ARGS__ ,))); \ } while (0) ``` Generates a log message with a single trailing newline. The **RTE\_LOG\_LINE()** is a helper that expands logging of a message with **RTE\_LOG()** appending a single newline to the formatted message. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. Definition at line **386** of file **rte\_log.h**. ### #define RTE\_LOG\_DP\_LINE(l, t, ...) **Value:**.PP ``` do { \ RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(__VA_ARGS__ ,)); \ RTE_LOG_DP(l, t, RTE_FMT(RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ RTE_FMT_TAIL(__VA_ARGS__ ,))); \ } while (0) ``` Generates a log message for data path with a single trailing newline. Similar to **RTE\_LOG\_LINE()**, except that it is removed at compilation time if the RTE\_LOG\_DP\_LEVEL configuration option is lower than the log level argument. The **RTE\_LOG\_LINE()** is a helper that expands logging of a message with **RTE\_LOG\_DP()** appending a single newline to the formatted message. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. Definition at line **413** of file **rte\_log.h**. ### #define RTE\_LOG\_LINE\_PREFIX(l, t, prefix, args, ...) **Value:**.PP ``` do { \ RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(prefix __VA_ARGS__ ,)); \ RTE_LOG(l, t, RTE_FMT(prefix RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ args RTE_LOG_COMMA RTE_FMT_TAIL(__VA_ARGS__ ,))); \ } while (0) ``` Generates a log message with a supplied prefix and arguments with a single trailing newline. The **RTE\_LOG\_LINE\_PREFIX()** is a helper that expands logging of a message with **RTE\_LOG()** prepending the supplied prefix and arguments appending a single newline to the formatted message. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *prefix* The prefix format string. \ *args* The arguments for the prefix format string. If args contains multiple arguments use RTE\_LOG\_COMMA to defer expansion. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. Definition at line **444** of file **rte\_log.h**. ### #define RTE\_LOG\_DP\_LINE\_PREFIX(l, t, prefix, args, ...) **Value:**.PP ``` do { \ RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(prefix __VA_ARGS__ ,)); \ RTE_LOG_DP(l, t, RTE_FMT(prefix RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ args RTE_LOG_COMMA RTE_FMT_TAIL(__VA_ARGS__ ,))); \ } while (0) ``` Generates a log message for the data path with a supplied prefix and arguments with a single trailing newline. The **RTE\_LOG\_DP\_LINE\_PREFIX()** is a helper that expands logging of a message with **RTE\_LOG\_DP()** prepending the supplied prefix and arguments appending a single newline to the formatted message. **Parameters** *l* Log level. A value between EMERG (1) and DEBUG (8). The short name is expanded by the macro, so it cannot be an integer value. \ *t* The log type, for example, EAL. The short name is expanded by the macro, so it cannot be an integer value. \ *prefix* The prefix format string. \ *args* The arguments for the prefix format string. If args contains multiple arguments use RTE\_LOG\_COMMA to defer expansion. \ *...* The fmt string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. Definition at line **473** of file **rte\_log.h**. ### #define RTE\_LOG\_REGISTER(type, name, level) RTE\_LOG\_REGISTER\_IMPL(type, RTE\_STR(name), level) Register a dynamic log type in constructor context with its name and level. It is a wrapper macro for declaring the logtype, register the log and sets it's level in the constructor context. **Parameters** *type* The log type identifier \ *name* Name for the log type to be registered \ *level* Log level. A value between EMERG (1) and DEBUG (8). Definition at line **501** of file **rte\_log.h**. ### #define RTE\_LOG\_REGISTER\_DEFAULT(type, level) RTE\_LOG\_REGISTER\_IMPL(type, RTE\_STR(RTE\_LOG\_DEFAULT\_LOGTYPE), level) This is an equivalent to RTE\_LOG\_REGISTER, but relying on the build system to select the right format for the logtype. Definition at line **508** of file **rte\_log.h**. ### #define RTE\_LOG\_REGISTER\_SUFFIX(type, suffix, level) **Value:**.PP ``` RTE_LOG_REGISTER_IMPL(type, \ RTE_STR(RTE_LOG_DEFAULT_LOGTYPE) "." RTE_STR(suffix), level) ``` This is an equivalent to RTE\_LOG\_REGISTER, but relying on the build system to select the right prefix for the logtype. Definition at line **515** of file **rte\_log.h**. ## Function Documentation ### int rte\_openlog\_stream (FILE \* f) Change the stream that will be used by the logging system. This can be done at any time. The f argument represents the stream to be used to send the logs. If f is NULL, the default output is used (stderr). **Parameters** *f* Pointer to the stream. **Returns** - • 0 on success. - • Negative on error. ### FILE \* rte\_log\_get\_stream (void) Retrieve the stream used by the logging system (see **rte\_openlog\_stream()** to change it). **Returns** Pointer to the stream. ### void rte\_log\_set\_global\_level (uint32\_t level) Set the global log level. After this call, logs with a level lower or equal than the level passed as argument will be displayed. **Parameters** *level* Log level. A value between RTE\_LOG\_EMERG (1) and RTE\_LOG\_DEBUG (8). ### uint32\_t rte\_log\_get\_global\_level (void) Get the global log level. **Returns** The current global log level. ### int rte\_log\_get\_level (uint32\_t logtype) Get the log level for a given type. **Parameters** *logtype* The log type identifier. **Returns** 0 on success, a negative value if logtype is invalid. ### bool rte\_log\_can\_log (uint32\_t logtype, uint32\_t loglevel) For a given `logtype`, check if a log with `loglevel` can be printed. **Parameters** *logtype* The log type identifier \ *loglevel* Log level. A value between RTE\_LOG\_EMERG (1) and RTE\_LOG\_DEBUG (8). **Returns** Returns 'true' if log can be printed and 'false' if it can't. ### int rte\_log\_set\_level\_pattern (const char \* pattern, uint32\_t level) Set the log level for a given type based on globbing pattern. **Parameters** *pattern* The globbing pattern identifying the log type. \ *level* The level to be set. **Returns** 0 on success, a negative value if level is invalid. ### int rte\_log\_set\_level\_regexp (const char \* regex, uint32\_t level) Set the log level for a given type based on regular expression. **Parameters** *regex* The regular expression identifying the log type. \ *level* The level to be set. **Returns** 0 on success, a negative value if level is invalid. ### int rte\_log\_set\_level (uint32\_t logtype, uint32\_t level) Set the log level for a given type. **Parameters** *logtype* The log type identifier. \ *level* The level to be set. **Returns** 0 on success, a negative value if logtype or level is invalid. ### int rte\_log\_cur\_msg\_loglevel (void) Get the current loglevel for the message being processed. Before calling the user-defined stream for logging, the log subsystem sets a per-lcore variable containing the loglevel and the logtype of the message being processed. This information can be accessed by the user-defined log output function through this function. **Returns** The loglevel of the message being processed. ### int rte\_log\_cur\_msg\_logtype (void) Get the current logtype for the message being processed. Before calling the user-defined stream for logging, the log subsystem sets a per-lcore variable containing the loglevel and the logtype of the message being processed. This information can be accessed by the user-defined log output function through this function. **Returns** The logtype of the message being processed. ### int rte\_log\_register (const char \* name) Register a dynamic log type If a log is already registered with the same type, the returned value is the same than the previous one. **Parameters** *name* The string identifying the log type. **Returns** - • \>0: success, the returned value is the log type identifier. - • (-ENOMEM): cannot allocate memory. ### int rte\_log\_register\_type\_and\_pick\_level (const char \* name, uint32\_t level\_def) Register a dynamic log type and try to pick its level from EAL options **rte\_log\_register()** is called inside. If successful, the function tries to search for matching regexp in the list of EAL log level options and pick the level from the last matching entry. If nothing can be applied from the list, the level will be set to the user-defined default value. **Parameters** *name* Name for the log type to be registered \ *level\_def* Fallback level to be set if the global list has no matching options **Returns** - • \>=0: the newly registered log type - • \<0: **rte\_log\_register()** error value ### void rte\_log\_list\_types (FILE \* out, const char \* prefix) Dump name of each logtype, one per line. **Parameters** *out* Stream where the list is sent. \ *prefix* String preceding each logtype in the output. ### void rte\_log\_dump (FILE \* f) Dump log information. Dump the global level and the registered log types. **Parameters** *f* The output stream where the dump should be sent. ### int rte\_log (uint32\_t level, uint32\_t logtype, const char \* format, ...) Generates a log message. The message will be sent in the stream defined by the previous call to **rte\_openlog\_stream()**. The level argument determines if the log should be displayed or not, depending on the loglevel settings. The preferred alternative is the **RTE\_LOG()** because it adds the level and type in the logged string. **Parameters** *level* Log level. A value between RTE\_LOG\_EMERG (1) and RTE\_LOG\_DEBUG (8). \ *logtype* The log type, for example, RTE\_LOGTYPE\_EAL. \ *format* The format string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. **Returns** - • 0: Success. - • Negative on error. ### int int rte\_vlog (uint32\_t level, uint32\_t logtype, const char \* format, va\_list ap) Generates a log message. The message will be sent in the stream defined by the previous call to **rte\_openlog\_stream()**. The level argument determines if the log should be displayed or not, depending on the loglevel settings. A trailing newline may be added if needed. The preferred alternative is the **RTE\_LOG()** because it adds the level and type in the logged string. **Parameters** *level* Log level. A value between RTE\_LOG\_EMERG (1) and RTE\_LOG\_DEBUG (8). \ *logtype* The log type, for example, RTE\_LOGTYPE\_EAL. \ *format* The format string, as in [printf(3)](/printf/3.md), followed by the variable arguments required by the format. \ *ap* The va\_list of the variable arguments required by the format. **Returns** - • 0: Success. - • Negative on error. ## Author Generated automatically by Doxygen for DPDK from the source code.