blob: 2144668c0632ca7a64b3730df2950b0fe29ed25e [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file log.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vasko193dacd2022-10-13 08:43:05 +02004 * @author Michal Vasko <mvasko@cesnet.cz>
Radek Krejci5aeea3a2018-09-05 13:29:36 +02005 * @brief Logger manipulation routines and error definitions.
6 *
Michal Vasko193dacd2022-10-13 08:43:05 +02007 * Copyright (c) 2015 - 2022 CESNET, z.s.p.o.
Radek Krejci5aeea3a2018-09-05 13:29:36 +02008 *
9 * This source code is licensed under BSD 3-Clause License (the "License").
10 * You may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * https://opensource.org/licenses/BSD-3-Clause
14 */
15
16#ifndef LY_LOG_H_
17#define LY_LOG_H_
18
Radek Krejci1deb5be2020-08-26 16:43:36 +020019#include <stdint.h>
20
Jan Kundrátc53a7ec2021-12-09 16:01:19 +010021#include "config.h"
22
Radek Krejci5aeea3a2018-09-05 13:29:36 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
Radek Krejciad573502018-09-07 15:26:55 +020027/* dummy context structure */
28struct ly_ctx;
29
Radek Krejci5aeea3a2018-09-05 13:29:36 +020030/**
Radek Krejci857189e2020-09-01 13:26:36 +020031 * @brief Type to indicate boolean value.
32 *
33 * Do not test for actual value. Instead, handle it as true/false value in condition.
34 */
35typedef uint8_t ly_bool;
36
37/**
Radek Krejci8678fa42020-08-18 16:07:28 +020038 * @page howtoLogger Information Logging
39 *
40 * The libyang logger is supposed to process all the messages (and some other accompanied information) generated by the performed
41 * functions. According to the logger settings, the information can be printed, stored or further processed by a callback
42 * functions.
43 *
44 * The logger is tightly connected with [errors handling](@ref howtoErrors), because when an error appears, the logger (according
45 * to [logger options](@ref logopts)) generates error records available via libyang context.
46 *
47 * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be changed by the ::ly_log_level() function.
48 * By default, the verbosity level is set to #LY_LLERR value, so only the errors are processed.
49 *
50 * By default, all libyang messages are printed to `stderr`. However, the callers are able to set their own logging callback
51 * function (::ly_log_clb). In that case, instead of printing messages, libyang passes error level, message and path (if any) to
52 * the caller's callback function set via ::ly_set_log_clb(). In case of error level, the error information is still
53 * automatically stored and available via the [error handling functions](@ref howtoErrors).
54 *
55 * With [logging options](@ref logopts) set via ::ly_log_options(), the caller can modify what is done with all the messages.
56 * Default flags are ::LY_LOLOG and ::LY_LOSTORE_LAST so that messages are logged and the last one is stored. If you set the flag
57 * ::LY_LOSTORE, all the messages will be stored. Be careful because unless you regularly clean them, the error list in context
58 * will grow indefinitely.
59 *
60 * As a separate group, there are @ref dbggroup to select group of debugging messages to print. The options can be set via
61 * ::ly_log_dbg_groups() function, but note that the options take effect only in case the libyang is compiled in
Radek Krejci7132fc52020-10-26 14:34:06 +010062 * [Debug build mode](@ref build).
Radek Krejci8678fa42020-08-18 16:07:28 +020063 *
64 * \note API for this group of functions is described in the [logger module](@ref log).
65 *
66 * Functions List
67 * --------------
68 * - ::ly_log_level()
69 * - ::ly_log_dbg_groups()
70 * - ::ly_log_options()
71 * - ::ly_set_log_clb()
72 * - ::ly_get_log_clb()
73 *
74 */
75
76/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +020077 * @defgroup log Logger
78 * @{
79 *
80 * Publicly visible functions and values of the libyang logger. For more
Michal Vasko8906ac12021-11-25 11:14:59 +010081 * information, see @ref howtoLogger.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020082 */
83
84/**
85 * @typedef LY_LOG_LEVEL
86 * @brief Verbosity levels of the libyang logger.
87 */
Michal Vasko26bbb272022-08-02 14:54:33 +020088typedef enum {
Michal Vasko8906ac12021-11-25 11:14:59 +010089 LY_LLERR = 0, /**< Print only error messages. */
90 LY_LLWRN = 1, /**< Print error and warning messages, default value. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +020091 LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */
Michal Vasko8906ac12021-11-25 11:14:59 +010092 LY_LLDBG = 3 /**< Print all messages including some development debug messages (be careful,
93 without subsequently calling ::ly_log_dbg_groups() no debug messages will be printed!). */
Radek Krejci5aeea3a2018-09-05 13:29:36 +020094} LY_LOG_LEVEL;
95
96/**
97 * @brief Set logger verbosity level.
Radek Krejciebdaed02020-11-09 13:05:06 +010098 *
aPiecekb0445f22021-06-24 11:34:07 +020099 * To get the current value, the function must be called twice resetting the level by the received value.
Radek Krejciebdaed02020-11-09 13:05:06 +0100100 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200101 * @param[in] level Verbosity level.
102 * @return Previous verbosity level.
103 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100104LIBYANG_API_DECL LY_LOG_LEVEL ly_log_level(LY_LOG_LEVEL level);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200105
106/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200107 * @ingroup logger
Radek Krejci8678fa42020-08-18 16:07:28 +0200108 * @defgroup logopts Logging options
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200109 *
110 * Logging option bits of libyang.
111 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200112 * Can be set via ::ly_log_options().
113 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200114 * @{
115 */
116#define LY_LOLOG 0x01 /**< Log messages normally, using callback if set. If not set, messages will
117 not be printed by libyang. */
118#define LY_LOSTORE 0x02 /**< Store any generated errors or warnings, never verbose or debug messages.
119 Note that if #LY_LOLOG is not set then verbose and debug messages are always lost. */
120#define LY_LOSTORE_LAST 0x06 /**< Store any generated errors or warnings but only the last message, always overwrite
121 the previous one. */
122
123/**
124 * @}
125 */
126
127/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200128 * @brief Set logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200129 *
aPiecekb0445f22021-06-24 11:34:07 +0200130 * To get the current value, the function must be called twice resetting the level by the received value.
Radek Krejciebdaed02020-11-09 13:05:06 +0100131 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200132 * @param[in] opts Bitfield of @ref logopts.
133 * @return Previous logger options.
134 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100135LIBYANG_API_DECL uint32_t ly_log_options(uint32_t opts);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200136
Michal Vaskod4a6d042022-12-08 08:34:29 +0100137/**
138 * @brief Set temporary thread-safe logger options overwriting those set by ::ly_log_options().
139 *
140 * @param[in] opts Pointer to the temporary @ref logopts. If NULL, restores the effect of global logger options.
141 */
142LIBYANG_API_DECL void ly_temp_log_options(uint32_t *opts);
143
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200144#ifndef NDEBUG
145
146/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200147 * @ingroup log
Radek Krejci8678fa42020-08-18 16:07:28 +0200148 * @defgroup dbggroup Debug messages groups
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200149 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200150 * Categories of the debug messages.
151 *
152 * Allows to show only the selected group(s) of the debug messages.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200153 *
154 * @{
155 */
156
Michal Vaskoe558f792021-07-28 08:20:15 +0200157#define LY_LDGDICT 0x01 /**< Dictionary additions and deletions. */
158#define LY_LDGXPATH 0x02 /**< XPath parsing end evaluation. */
159#define LY_LDGDEPSETS 0x04 /**< Dependency module sets for schema compilation. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200160
161/**
162 * @}
163 */
164
165/**
166 * @brief Enable specific debugging messages (independent of log level).
Radek Krejciebdaed02020-11-09 13:05:06 +0100167 *
aPiecekb0445f22021-06-24 11:34:07 +0200168 * To get the current value, the function must be called twice resetting the level by the received value.
Radek Krejciebdaed02020-11-09 13:05:06 +0100169 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200170 * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup).
Radek Krejciebdaed02020-11-09 13:05:06 +0100171 * @return Previous options bitfield.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200172 */
Radek Krejciebdaed02020-11-09 13:05:06 +0100173uint32_t ly_log_dbg_groups(uint32_t dbg_groups);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200174
175#endif
176
177/**
Michal Vaskod8085612020-08-21 12:55:23 +0200178 * @brief Logger callback.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200179 *
180 * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
181 * at the time of calling this callback. It will be set right after, so to retrieve it
Radek Krejci8678fa42020-08-18 16:07:28 +0200182 * it must be checked afterwards with ::ly_errapptag().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200183 *
Michal Vaskod8085612020-08-21 12:55:23 +0200184 * @param[in] level Log level of the message.
185 * @param[in] msg Message.
186 * @param[in] path Optional path of the concerned node.
187 */
188typedef void (*ly_log_clb)(LY_LOG_LEVEL level, const char *msg, const char *path);
189
190/**
191 * @brief Set logger callback.
192 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200193 * @param[in] clb Logging callback.
194 * @param[in] path flag to resolve and provide path as the third parameter of the callback function. In case of
195 * validation and some other errors, it can be useful to get the path to the problematic element. Note,
196 * that according to the tree type and the specific situation, the path can slightly differs (keys
197 * presence) or it can be NULL, so consider it as an optional parameter. If the flag is 0, libyang will
198 * not bother with resolving the path.
199 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100200LIBYANG_API_DECL void ly_set_log_clb(ly_log_clb clb, ly_bool path);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200201
202/**
203 * @brief Get logger callback.
204 * @return Logger callback (can be NULL).
205 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100206LIBYANG_API_DECL ly_log_clb ly_get_log_clb(void);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200207
208/** @} log */
209
210/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200211 * @page howtoErrors Errors Handling
212 *
213 * The most of the API functions directly returns error code in the form of ::LY_ERR value. In addition, if the ::LY_EVALID error
214 * arises, additional [validation error code](@ref ::LY_VECODE) is provided to categorize validation failures into several groups.
215 *
216 * All the errors arisen in connection with manipulation with the [context](@ref howtoContext), [YANG modules](@ref howtoSchema)
217 * or [YANG data](@ref howtoData), are recorded into the context and can be examined for the more detailed information. These
218 * records are stored as ::ly_err_item structures and they are not only context-specific, but also thread-specific.
219 *
220 * Storing error information is tightly connected with
221 * [logging](@ref howtoLogger). So the @ref logopts control if and which errors are stored in the context. By default, only the
222 * last error is recorded, so a new error replaces the previous one. This can be changed with ::LY_LOSTORE option set via
223 * ::ly_log_options(). Then, the errors are stored as a list preserving the previous error records. The stored records can be
224 * accessed using ::ly_err_last() or ::ly_err_first() functions. The ::ly_err_clean() is used to remove error records from the
225 * context.
226 *
227 * To print a specific error information via libyang logger, there is ::ly_err_print().
228 *
229 * To simplify access to the last error record in the context, there is a set of functions returning important error information.
230 * - ::ly_errapptag()
231 * - ::ly_errcode()
232 * - ::ly_vecode()
233 * - ::ly_errmsg()
234 * - ::ly_errpath()
235 *
236 * \note API for this group of functions is described in the [error information module](@ref errors).
237 */
238
239/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200240 * @defgroup errors Error information
Radek Krejci8678fa42020-08-18 16:07:28 +0200241 *
242 * Structures and functions to allow error information processing.
243 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200244 * @{
245 */
246
247/**
248 * @typedef LY_ERR
249 * @brief libyang's error codes returned by the libyang functions.
250 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100251typedef enum {
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200252 LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */
253 LY_EMEM, /**< Memory allocation failure */
Radek Krejcidc1c7e72018-09-07 14:58:20 +0200254 LY_ESYS, /**< System call failure */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200255 LY_EINVAL, /**< Invalid value */
256 LY_EEXIST, /**< Item already exists */
Radek Krejcid33273d2018-10-25 14:55:52 +0200257 LY_ENOTFOUND, /**< Item does not exists */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200258 LY_EINT, /**< Internal error */
259 LY_EVALID, /**< Validation failure */
Radek Krejcid3ca0632019-04-16 16:54:54 +0200260 LY_EDENIED, /**< Operation is not allowed */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200261 LY_EINCOMPLETE, /**< The operation did not fail, but for some reason it was not possible to finish it completely.
Radek Krejcie553e6d2019-06-07 15:33:18 +0200262 According to the specific use case, the caller is usually supposed to perform the operation again. */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200263 LY_ERECOMPILE, /**< The operation did not fail, but requires context recompilation before it can be completed.
264 According to the specific use case, the caller should react appropriately. */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200265 LY_ENOT, /**< Negative result */
Radek Krejcia4614e62020-05-15 14:19:28 +0200266 LY_EOTHER, /**< Unknown error */
267
268 LY_EPLUGIN = 128/**< Error reported by a plugin - the highest bit in the first byte is set.
269 This value is used ORed with one of the other LY_ERR value and can be simply masked. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200270} LY_ERR;
271
272/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200273 * @ingroup logger
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200274 * @typedef LY_VECODE
275 * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
276 * to the appropriate LY_VECODE value.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200277 */
278typedef enum {
279 LYVE_SUCCESS = 0, /**< no error */
Radek Krejci94aa9942018-09-07 17:12:17 +0200280 LYVE_SYNTAX, /**< generic syntax error */
281 LYVE_SYNTAX_YANG, /**< YANG-related syntax error */
David Sedlák0a875b42019-03-07 22:24:05 +0100282 LYVE_SYNTAX_YIN, /**< YIN-related syntax error */
Radek Krejci70853c52018-10-15 14:46:16 +0200283 LYVE_REFERENCE, /**< invalid referencing or using an item */
Radek Krejcib1646a92018-11-02 16:08:26 +0100284 LYVE_XPATH, /**< invalid XPath expression */
Radek Krejcie7b95092019-05-15 11:03:07 +0200285 LYVE_SEMANTICS, /**< generic semantic error */
286 LYVE_SYNTAX_XML, /**< XML-related syntax error */
Radek Krejci1798aae2020-07-14 13:26:06 +0200287 LYVE_SYNTAX_JSON, /**< JSON-related syntax error */
Michal Vaskoecd62de2019-11-13 12:35:11 +0100288 LYVE_DATA, /**< YANG data does not reflect some of the module restrictions */
Radek Krejcia4614e62020-05-15 14:19:28 +0200289
290 LYVE_OTHER /**< Unknown error */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200291} LY_VECODE;
292
293/**
294 * @brief Libyang full error structure.
295 */
296struct ly_err_item {
297 LY_LOG_LEVEL level;
298 LY_ERR no;
299 LY_VECODE vecode;
300 char *msg;
301 char *path;
302 char *apptag;
303 struct ly_err_item *next;
304 struct ly_err_item *prev; /* first item's prev points to the last item */
305};
306
307/**
308 * @brief Get the last (thread, context-specific) validation error code.
309 *
310 * This value is set only if ly_errno is #LY_EVALID.
311 *
312 * @param[in] ctx Relative context.
313 * @return Validation error code.
314 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100315LIBYANG_API_DECL LY_VECODE ly_vecode(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200316
317/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200318 * @brief Get the last (thread, context-specific) error code.
319 *
320 * @param[in] ctx Relative context.
321 * @return LY_ERR value of the last error code.
322 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100323LIBYANG_API_DECL LY_ERR ly_errcode(const struct ly_ctx *ctx);
Radek Krejcid33273d2018-10-25 14:55:52 +0200324
325/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200326 * @brief Get the last (thread, context-specific) error message. If the coresponding module defined
327 * a specific error message, it will be used instead the default one.
328 *
329 * Sometimes, the error message is extended with path of the element where the problem is.
Radek Krejci8678fa42020-08-18 16:07:28 +0200330 * The path is available via ::ly_errpath().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200331 *
332 * @param[in] ctx Relative context.
333 * @return Text of the last error message, empty string if there is no error.
334 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100335LIBYANG_API_DECL const char *ly_errmsg(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200336
337/**
338 * @brief Get the last (thread, context-specific) path of the element where was an error.
339 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200340 * The path always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200341 * whenever a subsequent error message is printed, the path is erased or rewritten.
342 * The path reflects the type of the processed tree - data path for data tree functions
343 * and schema path in case of schema tree functions. In case of processing YIN schema
344 * or XML data, the path can be just XML path. In such a case, the corresponding
345 * ly_vecode (value 1-3) is set.
346 *
347 * @param[in] ctx Relative context.
348 * @return Path of the error element, empty string if error path does not apply to the last error.
349 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100350LIBYANG_API_DECL const char *ly_errpath(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200351
352/**
353 * @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined
354 * in the module for the last error.
355 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200356 * The app-tag always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200357 * whenever a subsequent error message is printed, the app-tag is erased or rewritten.
358 *
359 * @param[in] ctx Relative context.
360 * @return Error-app-tag of the last error, empty string if the error-app-tag does not apply to the last error.
361 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100362LIBYANG_API_DECL const char *ly_errapptag(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200363
364/**
365 * @brief Get the first (thread, context-specific) generated error structure.
366 *
367 * @param[in] ctx Relative context.
Radek Krejci572ee602020-09-16 14:35:08 +0200368 * @return The first error structure (can be NULL), do not modify!
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200369 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100370LIBYANG_API_DECL struct ly_err_item *ly_err_first(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200371
372/**
Radek Krejci572ee602020-09-16 14:35:08 +0200373 * @brief Get the latest (thread, context-specific) generated error structure.
374 *
375 * @param[in] ctx Relative context.
376 * @return The last error structure (can be NULL), do not modify!
377 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100378LIBYANG_API_DECL struct ly_err_item *ly_err_last(const struct ly_ctx *ctx);
Radek Krejci572ee602020-09-16 14:35:08 +0200379
380/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200381 * @brief Print the error structure as if just generated.
382 *
Michal Vasko177d0ed2020-11-23 16:43:03 +0100383 * @param[in] ctx Optional context to store the message in.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200384 * @param[in] eitem Error item structure to print.
385 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100386LIBYANG_API_DECL void ly_err_print(const struct ly_ctx *ctx, struct ly_err_item *eitem);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200387
388/**
389 * @brief Free error structures from a context.
390 *
391 * If \p eitem is not set, free all the error structures.
392 *
393 * @param[in] ctx Relative context.
394 * @param[in] eitem Oldest error structure to remove, optional.
395 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100396LIBYANG_API_DECL void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200397
398/** @} errors */
399
400#ifdef __cplusplus
401}
402#endif
403
404#endif /* LY_LOG_H_ */