blob: d67eb96c6dca64f060ba0682d0c75b84a78d5b62 [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file log.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Logger manipulation routines and error definitions.
5 *
6 * Copyright (c) 2015 - 2018 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_LOG_H_
16#define LY_LOG_H_
17
Radek Krejci1deb5be2020-08-26 16:43:36 +020018#include <stdint.h>
19
Jan Kundrátc53a7ec2021-12-09 16:01:19 +010020#include "config.h"
21
Radek Krejci5aeea3a2018-09-05 13:29:36 +020022#ifdef __cplusplus
23extern "C" {
24#endif
25
Radek Krejciad573502018-09-07 15:26:55 +020026/* dummy context structure */
27struct ly_ctx;
28
Radek Krejci5aeea3a2018-09-05 13:29:36 +020029/**
Radek Krejci857189e2020-09-01 13:26:36 +020030 * @brief Type to indicate boolean value.
31 *
32 * Do not test for actual value. Instead, handle it as true/false value in condition.
33 */
34typedef uint8_t ly_bool;
35
36/**
Radek Krejci8678fa42020-08-18 16:07:28 +020037 * @page howtoLogger Information Logging
38 *
39 * The libyang logger is supposed to process all the messages (and some other accompanied information) generated by the performed
40 * functions. According to the logger settings, the information can be printed, stored or further processed by a callback
41 * functions.
42 *
43 * The logger is tightly connected with [errors handling](@ref howtoErrors), because when an error appears, the logger (according
44 * to [logger options](@ref logopts)) generates error records available via libyang context.
45 *
46 * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be changed by the ::ly_log_level() function.
47 * By default, the verbosity level is set to #LY_LLERR value, so only the errors are processed.
48 *
49 * By default, all libyang messages are printed to `stderr`. However, the callers are able to set their own logging callback
50 * function (::ly_log_clb). In that case, instead of printing messages, libyang passes error level, message and path (if any) to
51 * the caller's callback function set via ::ly_set_log_clb(). In case of error level, the error information is still
52 * automatically stored and available via the [error handling functions](@ref howtoErrors).
53 *
54 * With [logging options](@ref logopts) set via ::ly_log_options(), the caller can modify what is done with all the messages.
55 * 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
56 * ::LY_LOSTORE, all the messages will be stored. Be careful because unless you regularly clean them, the error list in context
57 * will grow indefinitely.
58 *
59 * As a separate group, there are @ref dbggroup to select group of debugging messages to print. The options can be set via
60 * ::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 +010061 * [Debug build mode](@ref build).
Radek Krejci8678fa42020-08-18 16:07:28 +020062 *
63 * \note API for this group of functions is described in the [logger module](@ref log).
64 *
65 * Functions List
66 * --------------
67 * - ::ly_log_level()
68 * - ::ly_log_dbg_groups()
69 * - ::ly_log_options()
70 * - ::ly_set_log_clb()
71 * - ::ly_get_log_clb()
72 *
73 */
74
75/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +020076 * @defgroup log Logger
77 * @{
78 *
79 * Publicly visible functions and values of the libyang logger. For more
Michal Vasko8906ac12021-11-25 11:14:59 +010080 * information, see @ref howtoLogger.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020081 */
82
83/**
84 * @typedef LY_LOG_LEVEL
85 * @brief Verbosity levels of the libyang logger.
86 */
87typedef enum
88{
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
137#ifndef NDEBUG
138
139/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200140 * @ingroup log
Radek Krejci8678fa42020-08-18 16:07:28 +0200141 * @defgroup dbggroup Debug messages groups
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200142 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200143 * Categories of the debug messages.
144 *
145 * Allows to show only the selected group(s) of the debug messages.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200146 *
147 * @{
148 */
149
Michal Vaskoe558f792021-07-28 08:20:15 +0200150#define LY_LDGDICT 0x01 /**< Dictionary additions and deletions. */
151#define LY_LDGXPATH 0x02 /**< XPath parsing end evaluation. */
152#define LY_LDGDEPSETS 0x04 /**< Dependency module sets for schema compilation. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200153
154/**
155 * @}
156 */
157
158/**
159 * @brief Enable specific debugging messages (independent of log level).
Radek Krejciebdaed02020-11-09 13:05:06 +0100160 *
aPiecekb0445f22021-06-24 11:34:07 +0200161 * 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 +0100162 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200163 * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup).
Radek Krejciebdaed02020-11-09 13:05:06 +0100164 * @return Previous options bitfield.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200165 */
Radek Krejciebdaed02020-11-09 13:05:06 +0100166uint32_t ly_log_dbg_groups(uint32_t dbg_groups);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200167
168#endif
169
170/**
Michal Vaskod8085612020-08-21 12:55:23 +0200171 * @brief Logger callback.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200172 *
173 * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
174 * at the time of calling this callback. It will be set right after, so to retrieve it
Radek Krejci8678fa42020-08-18 16:07:28 +0200175 * it must be checked afterwards with ::ly_errapptag().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200176 *
Michal Vaskod8085612020-08-21 12:55:23 +0200177 * @param[in] level Log level of the message.
178 * @param[in] msg Message.
179 * @param[in] path Optional path of the concerned node.
180 */
181typedef void (*ly_log_clb)(LY_LOG_LEVEL level, const char *msg, const char *path);
182
183/**
184 * @brief Set logger callback.
185 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200186 * @param[in] clb Logging callback.
187 * @param[in] path flag to resolve and provide path as the third parameter of the callback function. In case of
188 * validation and some other errors, it can be useful to get the path to the problematic element. Note,
189 * that according to the tree type and the specific situation, the path can slightly differs (keys
190 * presence) or it can be NULL, so consider it as an optional parameter. If the flag is 0, libyang will
191 * not bother with resolving the path.
192 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100193LIBYANG_API_DECL void ly_set_log_clb(ly_log_clb clb, ly_bool path);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200194
195/**
196 * @brief Get logger callback.
197 * @return Logger callback (can be NULL).
198 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100199LIBYANG_API_DECL ly_log_clb ly_get_log_clb(void);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200200
201/** @} log */
202
203/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200204 * @page howtoErrors Errors Handling
205 *
206 * The most of the API functions directly returns error code in the form of ::LY_ERR value. In addition, if the ::LY_EVALID error
207 * arises, additional [validation error code](@ref ::LY_VECODE) is provided to categorize validation failures into several groups.
208 *
209 * All the errors arisen in connection with manipulation with the [context](@ref howtoContext), [YANG modules](@ref howtoSchema)
210 * or [YANG data](@ref howtoData), are recorded into the context and can be examined for the more detailed information. These
211 * records are stored as ::ly_err_item structures and they are not only context-specific, but also thread-specific.
212 *
213 * Storing error information is tightly connected with
214 * [logging](@ref howtoLogger). So the @ref logopts control if and which errors are stored in the context. By default, only the
215 * last error is recorded, so a new error replaces the previous one. This can be changed with ::LY_LOSTORE option set via
216 * ::ly_log_options(). Then, the errors are stored as a list preserving the previous error records. The stored records can be
217 * accessed using ::ly_err_last() or ::ly_err_first() functions. The ::ly_err_clean() is used to remove error records from the
218 * context.
219 *
220 * To print a specific error information via libyang logger, there is ::ly_err_print().
221 *
222 * To simplify access to the last error record in the context, there is a set of functions returning important error information.
223 * - ::ly_errapptag()
224 * - ::ly_errcode()
225 * - ::ly_vecode()
226 * - ::ly_errmsg()
227 * - ::ly_errpath()
228 *
229 * \note API for this group of functions is described in the [error information module](@ref errors).
230 */
231
232/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200233 * @defgroup errors Error information
Radek Krejci8678fa42020-08-18 16:07:28 +0200234 *
235 * Structures and functions to allow error information processing.
236 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200237 * @{
238 */
239
240/**
241 * @typedef LY_ERR
242 * @brief libyang's error codes returned by the libyang functions.
243 */
244typedef enum
245{
246 LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */
247 LY_EMEM, /**< Memory allocation failure */
Radek Krejcidc1c7e72018-09-07 14:58:20 +0200248 LY_ESYS, /**< System call failure */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200249 LY_EINVAL, /**< Invalid value */
250 LY_EEXIST, /**< Item already exists */
Radek Krejcid33273d2018-10-25 14:55:52 +0200251 LY_ENOTFOUND, /**< Item does not exists */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200252 LY_EINT, /**< Internal error */
253 LY_EVALID, /**< Validation failure */
Radek Krejcid3ca0632019-04-16 16:54:54 +0200254 LY_EDENIED, /**< Operation is not allowed */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200255 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 +0200256 According to the specific use case, the caller is usually supposed to perform the operation again. */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200257 LY_ERECOMPILE, /**< The operation did not fail, but requires context recompilation before it can be completed.
258 According to the specific use case, the caller should react appropriately. */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200259 LY_ENOT, /**< Negative result */
Radek Krejcia4614e62020-05-15 14:19:28 +0200260 LY_EOTHER, /**< Unknown error */
261
262 LY_EPLUGIN = 128/**< Error reported by a plugin - the highest bit in the first byte is set.
263 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 +0200264} LY_ERR;
265
266/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200267 * @ingroup logger
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200268 * @typedef LY_VECODE
269 * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
270 * to the appropriate LY_VECODE value.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200271 */
272typedef enum {
273 LYVE_SUCCESS = 0, /**< no error */
Radek Krejci94aa9942018-09-07 17:12:17 +0200274 LYVE_SYNTAX, /**< generic syntax error */
275 LYVE_SYNTAX_YANG, /**< YANG-related syntax error */
David Sedlák0a875b42019-03-07 22:24:05 +0100276 LYVE_SYNTAX_YIN, /**< YIN-related syntax error */
Radek Krejci70853c52018-10-15 14:46:16 +0200277 LYVE_REFERENCE, /**< invalid referencing or using an item */
Radek Krejcib1646a92018-11-02 16:08:26 +0100278 LYVE_XPATH, /**< invalid XPath expression */
Radek Krejcie7b95092019-05-15 11:03:07 +0200279 LYVE_SEMANTICS, /**< generic semantic error */
280 LYVE_SYNTAX_XML, /**< XML-related syntax error */
Radek Krejci1798aae2020-07-14 13:26:06 +0200281 LYVE_SYNTAX_JSON, /**< JSON-related syntax error */
Michal Vaskoecd62de2019-11-13 12:35:11 +0100282 LYVE_DATA, /**< YANG data does not reflect some of the module restrictions */
Radek Krejcia4614e62020-05-15 14:19:28 +0200283
284 LYVE_OTHER /**< Unknown error */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200285} LY_VECODE;
286
287/**
288 * @brief Libyang full error structure.
289 */
290struct ly_err_item {
291 LY_LOG_LEVEL level;
292 LY_ERR no;
293 LY_VECODE vecode;
294 char *msg;
295 char *path;
296 char *apptag;
297 struct ly_err_item *next;
298 struct ly_err_item *prev; /* first item's prev points to the last item */
299};
300
301/**
302 * @brief Get the last (thread, context-specific) validation error code.
303 *
304 * This value is set only if ly_errno is #LY_EVALID.
305 *
306 * @param[in] ctx Relative context.
307 * @return Validation error code.
308 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100309LIBYANG_API_DECL LY_VECODE ly_vecode(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200310
311/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200312 * @brief Get the last (thread, context-specific) error code.
313 *
314 * @param[in] ctx Relative context.
315 * @return LY_ERR value of the last error code.
316 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100317LIBYANG_API_DECL LY_ERR ly_errcode(const struct ly_ctx *ctx);
Radek Krejcid33273d2018-10-25 14:55:52 +0200318
319/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200320 * @brief Get the last (thread, context-specific) error message. If the coresponding module defined
321 * a specific error message, it will be used instead the default one.
322 *
323 * Sometimes, the error message is extended with path of the element where the problem is.
Radek Krejci8678fa42020-08-18 16:07:28 +0200324 * The path is available via ::ly_errpath().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200325 *
326 * @param[in] ctx Relative context.
327 * @return Text of the last error message, empty string if there is no error.
328 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100329LIBYANG_API_DECL const char *ly_errmsg(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200330
331/**
332 * @brief Get the last (thread, context-specific) path of the element where was an error.
333 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200334 * The path always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200335 * whenever a subsequent error message is printed, the path is erased or rewritten.
336 * The path reflects the type of the processed tree - data path for data tree functions
337 * and schema path in case of schema tree functions. In case of processing YIN schema
338 * or XML data, the path can be just XML path. In such a case, the corresponding
339 * ly_vecode (value 1-3) is set.
340 *
341 * @param[in] ctx Relative context.
342 * @return Path of the error element, empty string if error path does not apply to the last error.
343 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100344LIBYANG_API_DECL const char *ly_errpath(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200345
346/**
347 * @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined
348 * in the module for the last error.
349 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200350 * The app-tag always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200351 * whenever a subsequent error message is printed, the app-tag is erased or rewritten.
352 *
353 * @param[in] ctx Relative context.
354 * @return Error-app-tag of the last error, empty string if the error-app-tag does not apply to the last error.
355 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100356LIBYANG_API_DECL const char *ly_errapptag(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200357
358/**
359 * @brief Get the first (thread, context-specific) generated error structure.
360 *
361 * @param[in] ctx Relative context.
Radek Krejci572ee602020-09-16 14:35:08 +0200362 * @return The first error structure (can be NULL), do not modify!
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200363 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100364LIBYANG_API_DECL struct ly_err_item *ly_err_first(const struct ly_ctx *ctx);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200365
366/**
Radek Krejci572ee602020-09-16 14:35:08 +0200367 * @brief Get the latest (thread, context-specific) generated error structure.
368 *
369 * @param[in] ctx Relative context.
370 * @return The last error structure (can be NULL), do not modify!
371 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100372LIBYANG_API_DECL struct ly_err_item *ly_err_last(const struct ly_ctx *ctx);
Radek Krejci572ee602020-09-16 14:35:08 +0200373
374/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200375 * @brief Print the error structure as if just generated.
376 *
Michal Vasko177d0ed2020-11-23 16:43:03 +0100377 * @param[in] ctx Optional context to store the message in.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200378 * @param[in] eitem Error item structure to print.
379 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100380LIBYANG_API_DECL void ly_err_print(const struct ly_ctx *ctx, struct ly_err_item *eitem);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200381
382/**
383 * @brief Free error structures from a context.
384 *
385 * If \p eitem is not set, free all the error structures.
386 *
387 * @param[in] ctx Relative context.
388 * @param[in] eitem Oldest error structure to remove, optional.
389 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100390LIBYANG_API_DECL void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200391
392/** @} errors */
393
394#ifdef __cplusplus
395}
396#endif
397
398#endif /* LY_LOG_H_ */