blob: 7c60caebab635da3ad476ad21d0caca51c89190e [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
Radek Krejci5aeea3a2018-09-05 13:29:36 +020020#ifdef __cplusplus
21extern "C" {
22#endif
23
Radek Krejciad573502018-09-07 15:26:55 +020024/* dummy context structure */
25struct ly_ctx;
26
Radek Krejci5aeea3a2018-09-05 13:29:36 +020027/**
Radek Krejci857189e2020-09-01 13:26:36 +020028 * @brief Type to indicate boolean value.
29 *
30 * Do not test for actual value. Instead, handle it as true/false value in condition.
31 */
32typedef uint8_t ly_bool;
33
34/**
Radek Krejci8678fa42020-08-18 16:07:28 +020035 * @page howtoLogger Information Logging
36 *
37 * The libyang logger is supposed to process all the messages (and some other accompanied information) generated by the performed
38 * functions. According to the logger settings, the information can be printed, stored or further processed by a callback
39 * functions.
40 *
41 * The logger is tightly connected with [errors handling](@ref howtoErrors), because when an error appears, the logger (according
42 * to [logger options](@ref logopts)) generates error records available via libyang context.
43 *
44 * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be changed by the ::ly_log_level() function.
45 * By default, the verbosity level is set to #LY_LLERR value, so only the errors are processed.
46 *
47 * By default, all libyang messages are printed to `stderr`. However, the callers are able to set their own logging callback
48 * function (::ly_log_clb). In that case, instead of printing messages, libyang passes error level, message and path (if any) to
49 * the caller's callback function set via ::ly_set_log_clb(). In case of error level, the error information is still
50 * automatically stored and available via the [error handling functions](@ref howtoErrors).
51 *
52 * With [logging options](@ref logopts) set via ::ly_log_options(), the caller can modify what is done with all the messages.
53 * 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
54 * ::LY_LOSTORE, all the messages will be stored. Be careful because unless you regularly clean them, the error list in context
55 * will grow indefinitely.
56 *
57 * As a separate group, there are @ref dbggroup to select group of debugging messages to print. The options can be set via
58 * ::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 +010059 * [Debug build mode](@ref build).
Radek Krejci8678fa42020-08-18 16:07:28 +020060 *
61 * \note API for this group of functions is described in the [logger module](@ref log).
62 *
63 * Functions List
64 * --------------
65 * - ::ly_log_level()
66 * - ::ly_log_dbg_groups()
67 * - ::ly_log_options()
68 * - ::ly_set_log_clb()
69 * - ::ly_get_log_clb()
70 *
71 */
72
73/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +020074 * @defgroup log Logger
75 * @{
76 *
77 * Publicly visible functions and values of the libyang logger. For more
Michal Vasko8906ac12021-11-25 11:14:59 +010078 * information, see @ref howtoLogger.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020079 */
80
81/**
82 * @typedef LY_LOG_LEVEL
83 * @brief Verbosity levels of the libyang logger.
84 */
85typedef enum
86{
Michal Vasko8906ac12021-11-25 11:14:59 +010087 LY_LLERR = 0, /**< Print only error messages. */
88 LY_LLWRN = 1, /**< Print error and warning messages, default value. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +020089 LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */
Michal Vasko8906ac12021-11-25 11:14:59 +010090 LY_LLDBG = 3 /**< Print all messages including some development debug messages (be careful,
91 without subsequently calling ::ly_log_dbg_groups() no debug messages will be printed!). */
Radek Krejci5aeea3a2018-09-05 13:29:36 +020092} LY_LOG_LEVEL;
93
94/**
95 * @brief Set logger verbosity level.
Radek Krejciebdaed02020-11-09 13:05:06 +010096 *
aPiecekb0445f22021-06-24 11:34:07 +020097 * 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 +010098 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +020099 * @param[in] level Verbosity level.
100 * @return Previous verbosity level.
101 */
Radek Krejci52b6d512020-10-12 12:33:17 +0200102LY_LOG_LEVEL ly_log_level(LY_LOG_LEVEL level);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200103
104/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200105 * @ingroup logger
Radek Krejci8678fa42020-08-18 16:07:28 +0200106 * @defgroup logopts Logging options
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200107 *
108 * Logging option bits of libyang.
109 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200110 * Can be set via ::ly_log_options().
111 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200112 * @{
113 */
114#define LY_LOLOG 0x01 /**< Log messages normally, using callback if set. If not set, messages will
115 not be printed by libyang. */
116#define LY_LOSTORE 0x02 /**< Store any generated errors or warnings, never verbose or debug messages.
117 Note that if #LY_LOLOG is not set then verbose and debug messages are always lost. */
118#define LY_LOSTORE_LAST 0x06 /**< Store any generated errors or warnings but only the last message, always overwrite
119 the previous one. */
120
121/**
122 * @}
123 */
124
125/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200126 * @brief Set logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200127 *
aPiecekb0445f22021-06-24 11:34:07 +0200128 * 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 +0100129 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200130 * @param[in] opts Bitfield of @ref logopts.
131 * @return Previous logger options.
132 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200133uint32_t ly_log_options(uint32_t opts);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200134
135#ifndef NDEBUG
136
137/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200138 * @ingroup log
Radek Krejci8678fa42020-08-18 16:07:28 +0200139 * @defgroup dbggroup Debug messages groups
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200140 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200141 * Categories of the debug messages.
142 *
143 * Allows to show only the selected group(s) of the debug messages.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200144 *
145 * @{
146 */
147
Michal Vaskoe558f792021-07-28 08:20:15 +0200148#define LY_LDGDICT 0x01 /**< Dictionary additions and deletions. */
149#define LY_LDGXPATH 0x02 /**< XPath parsing end evaluation. */
150#define LY_LDGDEPSETS 0x04 /**< Dependency module sets for schema compilation. */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200151
152/**
153 * @}
154 */
155
156/**
157 * @brief Enable specific debugging messages (independent of log level).
Radek Krejciebdaed02020-11-09 13:05:06 +0100158 *
aPiecekb0445f22021-06-24 11:34:07 +0200159 * 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 +0100160 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200161 * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup).
Radek Krejciebdaed02020-11-09 13:05:06 +0100162 * @return Previous options bitfield.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200163 */
Radek Krejciebdaed02020-11-09 13:05:06 +0100164uint32_t ly_log_dbg_groups(uint32_t dbg_groups);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200165
166#endif
167
168/**
Michal Vaskod8085612020-08-21 12:55:23 +0200169 * @brief Logger callback.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200170 *
171 * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
172 * at the time of calling this callback. It will be set right after, so to retrieve it
Radek Krejci8678fa42020-08-18 16:07:28 +0200173 * it must be checked afterwards with ::ly_errapptag().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200174 *
Michal Vaskod8085612020-08-21 12:55:23 +0200175 * @param[in] level Log level of the message.
176 * @param[in] msg Message.
177 * @param[in] path Optional path of the concerned node.
178 */
179typedef void (*ly_log_clb)(LY_LOG_LEVEL level, const char *msg, const char *path);
180
181/**
182 * @brief Set logger callback.
183 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200184 * @param[in] clb Logging callback.
185 * @param[in] path flag to resolve and provide path as the third parameter of the callback function. In case of
186 * validation and some other errors, it can be useful to get the path to the problematic element. Note,
187 * that according to the tree type and the specific situation, the path can slightly differs (keys
188 * presence) or it can be NULL, so consider it as an optional parameter. If the flag is 0, libyang will
189 * not bother with resolving the path.
190 */
Radek Krejci857189e2020-09-01 13:26:36 +0200191void ly_set_log_clb(ly_log_clb clb, ly_bool path);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200192
193/**
194 * @brief Get logger callback.
195 * @return Logger callback (can be NULL).
196 */
Michal Vaskod8085612020-08-21 12:55:23 +0200197ly_log_clb ly_get_log_clb(void);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200198
199/** @} log */
200
201/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200202 * @page howtoErrors Errors Handling
203 *
204 * The most of the API functions directly returns error code in the form of ::LY_ERR value. In addition, if the ::LY_EVALID error
205 * arises, additional [validation error code](@ref ::LY_VECODE) is provided to categorize validation failures into several groups.
206 *
207 * All the errors arisen in connection with manipulation with the [context](@ref howtoContext), [YANG modules](@ref howtoSchema)
208 * or [YANG data](@ref howtoData), are recorded into the context and can be examined for the more detailed information. These
209 * records are stored as ::ly_err_item structures and they are not only context-specific, but also thread-specific.
210 *
211 * Storing error information is tightly connected with
212 * [logging](@ref howtoLogger). So the @ref logopts control if and which errors are stored in the context. By default, only the
213 * last error is recorded, so a new error replaces the previous one. This can be changed with ::LY_LOSTORE option set via
214 * ::ly_log_options(). Then, the errors are stored as a list preserving the previous error records. The stored records can be
215 * accessed using ::ly_err_last() or ::ly_err_first() functions. The ::ly_err_clean() is used to remove error records from the
216 * context.
217 *
218 * To print a specific error information via libyang logger, there is ::ly_err_print().
219 *
220 * To simplify access to the last error record in the context, there is a set of functions returning important error information.
221 * - ::ly_errapptag()
222 * - ::ly_errcode()
223 * - ::ly_vecode()
224 * - ::ly_errmsg()
225 * - ::ly_errpath()
226 *
227 * \note API for this group of functions is described in the [error information module](@ref errors).
228 */
229
230/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200231 * @defgroup errors Error information
Radek Krejci8678fa42020-08-18 16:07:28 +0200232 *
233 * Structures and functions to allow error information processing.
234 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200235 * @{
236 */
237
238/**
239 * @typedef LY_ERR
240 * @brief libyang's error codes returned by the libyang functions.
241 */
242typedef enum
243{
244 LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */
245 LY_EMEM, /**< Memory allocation failure */
Radek Krejcidc1c7e72018-09-07 14:58:20 +0200246 LY_ESYS, /**< System call failure */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200247 LY_EINVAL, /**< Invalid value */
248 LY_EEXIST, /**< Item already exists */
Radek Krejcid33273d2018-10-25 14:55:52 +0200249 LY_ENOTFOUND, /**< Item does not exists */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200250 LY_EINT, /**< Internal error */
251 LY_EVALID, /**< Validation failure */
Radek Krejcid3ca0632019-04-16 16:54:54 +0200252 LY_EDENIED, /**< Operation is not allowed */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200253 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 +0200254 According to the specific use case, the caller is usually supposed to perform the operation again. */
Michal Vasko1ccbf542021-04-19 11:35:00 +0200255 LY_ERECOMPILE, /**< The operation did not fail, but requires context recompilation before it can be completed.
256 According to the specific use case, the caller should react appropriately. */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200257 LY_ENOT, /**< Negative result */
Radek Krejcia4614e62020-05-15 14:19:28 +0200258 LY_EOTHER, /**< Unknown error */
259
260 LY_EPLUGIN = 128/**< Error reported by a plugin - the highest bit in the first byte is set.
261 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 +0200262} LY_ERR;
263
264/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200265 * @ingroup logger
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200266 * @typedef LY_VECODE
267 * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
268 * to the appropriate LY_VECODE value.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200269 */
270typedef enum {
271 LYVE_SUCCESS = 0, /**< no error */
Radek Krejci94aa9942018-09-07 17:12:17 +0200272 LYVE_SYNTAX, /**< generic syntax error */
273 LYVE_SYNTAX_YANG, /**< YANG-related syntax error */
David Sedlák0a875b42019-03-07 22:24:05 +0100274 LYVE_SYNTAX_YIN, /**< YIN-related syntax error */
Radek Krejci70853c52018-10-15 14:46:16 +0200275 LYVE_REFERENCE, /**< invalid referencing or using an item */
Radek Krejcib1646a92018-11-02 16:08:26 +0100276 LYVE_XPATH, /**< invalid XPath expression */
Radek Krejcie7b95092019-05-15 11:03:07 +0200277 LYVE_SEMANTICS, /**< generic semantic error */
278 LYVE_SYNTAX_XML, /**< XML-related syntax error */
Radek Krejci1798aae2020-07-14 13:26:06 +0200279 LYVE_SYNTAX_JSON, /**< JSON-related syntax error */
Michal Vaskoecd62de2019-11-13 12:35:11 +0100280 LYVE_DATA, /**< YANG data does not reflect some of the module restrictions */
Radek Krejcia4614e62020-05-15 14:19:28 +0200281
282 LYVE_OTHER /**< Unknown error */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200283} LY_VECODE;
284
285/**
286 * @brief Libyang full error structure.
287 */
288struct ly_err_item {
289 LY_LOG_LEVEL level;
290 LY_ERR no;
291 LY_VECODE vecode;
292 char *msg;
293 char *path;
294 char *apptag;
295 struct ly_err_item *next;
296 struct ly_err_item *prev; /* first item's prev points to the last item */
297};
298
299/**
300 * @brief Get the last (thread, context-specific) validation error code.
301 *
302 * This value is set only if ly_errno is #LY_EVALID.
303 *
304 * @param[in] ctx Relative context.
305 * @return Validation error code.
306 */
307LY_VECODE ly_vecode(const struct ly_ctx *ctx);
308
309/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200310 * @brief Get the last (thread, context-specific) error code.
311 *
312 * @param[in] ctx Relative context.
313 * @return LY_ERR value of the last error code.
314 */
315LY_ERR ly_errcode(const struct ly_ctx *ctx);
316
317/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200318 * @brief Get the last (thread, context-specific) error message. If the coresponding module defined
319 * a specific error message, it will be used instead the default one.
320 *
321 * Sometimes, the error message is extended with path of the element where the problem is.
Radek Krejci8678fa42020-08-18 16:07:28 +0200322 * The path is available via ::ly_errpath().
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200323 *
324 * @param[in] ctx Relative context.
325 * @return Text of the last error message, empty string if there is no error.
326 */
327const char *ly_errmsg(const struct ly_ctx *ctx);
328
329/**
330 * @brief Get the last (thread, context-specific) path of the element where was an error.
331 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200332 * The path always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200333 * whenever a subsequent error message is printed, the path is erased or rewritten.
334 * The path reflects the type of the processed tree - data path for data tree functions
335 * and schema path in case of schema tree functions. In case of processing YIN schema
336 * or XML data, the path can be just XML path. In such a case, the corresponding
337 * ly_vecode (value 1-3) is set.
338 *
339 * @param[in] ctx Relative context.
340 * @return Path of the error element, empty string if error path does not apply to the last error.
341 */
342const char *ly_errpath(const struct ly_ctx *ctx);
343
344/**
345 * @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined
346 * in the module for the last error.
347 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200348 * The app-tag always corresponds to the error message available via ::ly_errmsg(), so
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200349 * whenever a subsequent error message is printed, the app-tag is erased or rewritten.
350 *
351 * @param[in] ctx Relative context.
352 * @return Error-app-tag of the last error, empty string if the error-app-tag does not apply to the last error.
353 */
354const char *ly_errapptag(const struct ly_ctx *ctx);
355
356/**
357 * @brief Get the first (thread, context-specific) generated error structure.
358 *
359 * @param[in] ctx Relative context.
Radek Krejci572ee602020-09-16 14:35:08 +0200360 * @return The first error structure (can be NULL), do not modify!
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200361 */
362struct ly_err_item *ly_err_first(const struct ly_ctx *ctx);
363
364/**
Radek Krejci572ee602020-09-16 14:35:08 +0200365 * @brief Get the latest (thread, context-specific) generated error structure.
366 *
367 * @param[in] ctx Relative context.
368 * @return The last error structure (can be NULL), do not modify!
369 */
370struct ly_err_item *ly_err_last(const struct ly_ctx *ctx);
371
372/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200373 * @brief Print the error structure as if just generated.
374 *
Michal Vasko177d0ed2020-11-23 16:43:03 +0100375 * @param[in] ctx Optional context to store the message in.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200376 * @param[in] eitem Error item structure to print.
377 */
Michal Vasko177d0ed2020-11-23 16:43:03 +0100378void ly_err_print(const struct ly_ctx *ctx, struct ly_err_item *eitem);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200379
380/**
381 * @brief Free error structures from a context.
382 *
383 * If \p eitem is not set, free all the error structures.
384 *
385 * @param[in] ctx Relative context.
386 * @param[in] eitem Oldest error structure to remove, optional.
387 */
388void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem);
389
390/** @} errors */
391
392#ifdef __cplusplus
393}
394#endif
395
396#endif /* LY_LOG_H_ */