Adding upstream version 3.1.0+dfsg.upstream/3.1.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 361 insertions, 0 deletions

diff --git a/src/log.h b/src/log.h
new file mode 100644
index 0000000..85f2ac6
--- /dev/null
+++ b/src/log.h
@@ -0,0 +1,361 @@
+/**
+ * @file log.h
+ * @author Radek Krejci <rkrejci@cesnet.cz>
+ * @author Michal Vasko <mvasko@cesnet.cz>
+ * @brief Logger manipulation routines and error definitions.
+ *
+ * Copyright (c) 2015 - 2022 CESNET, z.s.p.o.
+ *
+ * This source code is licensed under BSD 3-Clause License (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://opensource.org/licenses/BSD-3-Clause
+ */
+
+#ifndef LY_LOG_H_
+#define LY_LOG_H_
+
+#include <stdint.h>
+
+#include "ly_config.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* dummy context structure */
+struct ly_ctx;
+
+/**
+ * @brief Type to indicate boolean value.
+ *
+ * Do not test for actual value. Instead, handle it as true/false value in condition.
+ */
+typedef uint8_t ly_bool;
+
+/**
+ * @page howtoLogger Information Logging
+ *
+ * The libyang logger is supposed to process all the messages (and some other accompanied information) generated by the performed
+ * functions. According to the logger settings, the information can be printed, stored or further processed by a callback
+ * functions.
+ *
+ * The logger is tightly connected with [errors handling](@ref howtoErrors), because when an error appears, the logger (according
+ * to [logger options](@ref logopts)) generates error records available via libyang context.
+ *
+ * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be changed by the ::ly_log_level() function.
+ * By default, the verbosity level is set to #LY_LLERR value, so only the errors are processed.
+ *
+ * By default, all libyang messages are printed to `stderr`. However, the callers are able to set their own logging callback
+ * function (::ly_log_clb). In that case, instead of printing messages, libyang passes error level, message and path (if any) to
+ * the caller's callback function set via ::ly_set_log_clb(). In case of error level, the error information is still
+ * automatically stored and available via the [error handling functions](@ref howtoErrors).
+ *
+ * With [logging options](@ref logopts) set via ::ly_log_options(), the caller can modify what is done with all the messages.
+ * 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
+ * ::LY_LOSTORE, all the messages will be stored. Be careful because unless you regularly clean them, the error list in context
+ * will grow indefinitely.
+ *
+ * As a separate group, there are @ref dbggroup to select group of debugging messages to print. The options can be set via
+ * ::ly_log_dbg_groups() function, but note that the options take effect only in case the libyang is compiled in
+ * [Debug build mode](@ref build).
+ *
+ * \note API for this group of functions is described in the [logger module](@ref log).
+ *
+ * Functions List
+ * --------------
+ * - ::ly_log_level()
+ * - ::ly_log_dbg_groups()
+ * - ::ly_log_options()
+ * - ::ly_set_log_clb()
+ * - ::ly_get_log_clb()
+ *
+ */
+
+/**
+ * @defgroup log Logger
+ * @{
+ *
+ * Publicly visible functions and values of the libyang logger. For more
+ * information, see @ref howtoLogger.
+ */
+
+/**
+ * @typedef LY_LOG_LEVEL
+ * @brief Verbosity levels of the libyang logger.
+ */
+typedef enum {
+    LY_LLERR = 0, /**< Print only error messages. */
+    LY_LLWRN = 1, /**< Print error and warning messages, default value. */
+    LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */
+    LY_LLDBG = 3  /**< Print all messages including some development debug messages (be careful,
+                       without subsequently calling ::ly_log_dbg_groups() no debug messages will be printed!). */
+} LY_LOG_LEVEL;
+
+/**
+ * @brief Set logger verbosity level.
+ *
+ * To get the current value, the function must be called twice resetting the level by the received value.
+ *
+ * @param[in] level Verbosity level.
+ * @return Previous verbosity level.
+ */
+LIBYANG_API_DECL LY_LOG_LEVEL ly_log_level(LY_LOG_LEVEL level);
+
+/**
+ * @ingroup log
+ * @defgroup logopts Logging options
+ *
+ * Logging option bits of libyang.
+ *
+ * Can be set via ::ly_log_options().
+ *
+ * @{
+ */
+#define LY_LOLOG        0x01 /**< Log messages normally, using callback if set. If not set, messages will
+                                  not be printed by libyang. */
+#define LY_LOSTORE      0x02 /**< Store any generated errors or warnings, never verbose or debug messages.
+                                  Note that if #LY_LOLOG is not set then verbose and debug messages are always lost. */
+#define LY_LOSTORE_LAST 0x06 /**< Store any generated errors or warnings but only the last message, always overwrite
+                                  the previous one. */
+
+/**
+ * @}
+ */
+
+/**
+ * @brief Set logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
+ *
+ * To get the current value, the function must be called twice resetting the level by the received value.
+ *
+ * @param[in] opts Bitfield of @ref logopts.
+ * @return Previous logger options.
+ */
+LIBYANG_API_DECL uint32_t ly_log_options(uint32_t opts);
+
+/**
+ * @brief Set temporary thread-safe logger options overwriting those set by ::ly_log_options().
+ *
+ * @param[in] opts Pointer to the temporary @ref logopts. If NULL, restores the effect of global logger options.
+ * @return Previous temporary options.
+ */
+LIBYANG_API_DECL uint32_t *ly_temp_log_options(uint32_t *opts);
+
+/**
+ * @ingroup log
+ * @defgroup dbggroup Debug messages groups
+ *
+ * Categories of the debug messages.
+ *
+ * Allows to show only the selected group(s) of the debug messages.
+ *
+ * @{
+ */
+
+#define LY_LDGDICT      0x01    /**< Dictionary additions and deletions. */
+#define LY_LDGXPATH     0x02    /**< XPath parsing end evaluation. */
+#define LY_LDGDEPSETS   0x04    /**< Dependency module sets for schema compilation. */
+
+/**
+ * @}
+ */
+
+/**
+ * @brief Enable specific debugging messages (independent of log level).
+ *
+ * To get the current value, the function must be called twice resetting the level by the received value.
+ * Note: does not have any effect on non-debug (Release) builds
+ *
+ * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup).
+ * @return Previous options bitfield.
+ */
+LIBYANG_API_DECL uint32_t ly_log_dbg_groups(uint32_t dbg_groups);
+
+/**
+ * @brief Logger callback.
+ *
+ * @param[in] level Log level of the message.
+ * @param[in] msg Message.
+ * @param[in] data_path Optional data path of the related node.
+ * @param[in] schema_path Optional schema path of the related node.
+ * @param[in] line Optional related input line.
+ */
+typedef void (*ly_log_clb)(LY_LOG_LEVEL level, const char *msg, const char *data_path, const char *schema_path,
+        uint64_t line);
+
+/**
+ * @brief Set logger callback.
+ *
+ * @param[in] clb Logging callback.
+ */
+LIBYANG_API_DECL void ly_set_log_clb(ly_log_clb clb);
+
+/**
+ * @brief Get logger callback.
+ *
+ * @return Logger callback (can be NULL).
+ */
+LIBYANG_API_DECL ly_log_clb ly_get_log_clb(void);
+
+/** @} log */
+
+/**
+ * @page howtoErrors Errors Handling
+ *
+ * The most of the API functions directly returns error code in the form of ::LY_ERR value. In addition, if the ::LY_EVALID error
+ * arises, additional [validation error code](@ref ::LY_VECODE) is provided to categorize validation failures into several groups.
+ *
+ * All the errors arisen in connection with manipulation with the [context](@ref howtoContext), [YANG modules](@ref howtoSchema)
+ * or [YANG data](@ref howtoData), are recorded into the context and can be examined for the more detailed information. These
+ * records are stored as ::ly_err_item structures and they are not only context-specific, but also thread-specific.
+ *
+ * Storing error information is tightly connected with
+ * [logging](@ref howtoLogger). So the @ref logopts control if and which errors are stored in the context. By default, only the
+ * last error is recorded, so a new error replaces the previous one. This can be changed with ::LY_LOSTORE option set via
+ * ::ly_log_options(). Then, the errors are stored as a list preserving the previous error records. The stored records can be
+ * accessed using ::ly_err_last() or ::ly_err_first() functions. The ::ly_err_clean() is used to remove error records from the
+ * context.
+ *
+ * To print a specific error information via libyang logger, there is ::ly_err_print().
+ *
+ * \note API for this group of functions is described in the [error information module](@ref errors).
+ */
+
+/**
+ * @defgroup errors Error information
+ *
+ * Structures and functions to allow error information processing.
+ *
+ * @{
+ */
+
+/**
+ * @typedef LY_ERR
+ * @brief libyang's error codes returned by the libyang functions.
+ */
+typedef enum {
+    LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */
+    LY_EMEM,        /**< Memory allocation failure */
+    LY_ESYS,        /**< System call failure */
+    LY_EINVAL,      /**< Invalid value */
+    LY_EEXIST,      /**< Item already exists */
+    LY_ENOTFOUND,   /**< Item does not exists */
+    LY_EINT,        /**< Internal error */
+    LY_EVALID,      /**< Validation failure */
+    LY_EDENIED,     /**< Operation is not allowed */
+    LY_EINCOMPLETE, /**< The operation did not fail, but for some reason it was not possible to finish it completely.
+                         According to the specific use case, the caller is usually supposed to perform the operation again. */
+    LY_ERECOMPILE,  /**< The operation did not fail, but requires context recompilation before it can be completed.
+                         According to the specific use case, the caller should react appropriately. */
+    LY_ENOT,        /**< Negative result */
+    LY_EOTHER,      /**< Unknown error */
+
+    LY_EPLUGIN = 128/**< Error reported by a plugin - the highest bit in the first byte is set.
+                         This value is used ORed with one of the other LY_ERR value and can be simply masked. */
+} LY_ERR;
+
+/**
+ * @ingroup log
+ * @typedef LY_VECODE
+ * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
+ * to the appropriate LY_VECODE value.
+ */
+typedef enum {
+    LYVE_SUCCESS = 0,  /**< no error */
+    LYVE_SYNTAX,       /**< generic syntax error */
+    LYVE_SYNTAX_YANG,  /**< YANG-related syntax error */
+    LYVE_SYNTAX_YIN,   /**< YIN-related syntax error */
+    LYVE_REFERENCE,    /**< invalid referencing or using an item */
+    LYVE_XPATH,        /**< invalid XPath expression */
+    LYVE_SEMANTICS,    /**< generic semantic error */
+    LYVE_SYNTAX_XML,   /**< XML-related syntax error */
+    LYVE_SYNTAX_JSON,  /**< JSON-related syntax error */
+    LYVE_DATA,         /**< YANG data does not reflect some of the module restrictions */
+
+    LYVE_OTHER         /**< Unknown error */
+} LY_VECODE;
+
+/**
+ * @brief Libyang full error structure.
+ */
+struct ly_err_item {
+    LY_LOG_LEVEL level;         /**< error (message) log level */
+    LY_ERR err;                 /**< error code number */
+    LY_VECODE vecode;           /**< validation error code, if any */
+    char *msg;                  /**< error message */
+    char *data_path;            /**< error data path related to the error, if any */
+    char *schema_path;          /**< error schema path related to the error, if any */
+    uint64_t line;              /**< input line the error occured on, if available */
+    char *apptag;               /**< error-app-tag, if any */
+    struct ly_err_item *next;   /**< next error item */
+    struct ly_err_item *prev;   /**< previous error item, points to the last item for the ifrst item */
+};
+
+/**
+ * @brief Get human-readable error message for an error code.
+ *
+ * @param[in] err Error code.
+ * @return String error message.
+ */
+LIBYANG_API_DECL const char *ly_strerr(LY_ERR err);
+
+/**
+ * @brief Get human-readable error message for a validation error code.
+ *
+ * @param[in] vecode Validation error code.
+ * @return String error message.
+ */
+LIBYANG_API_DECL const char *ly_strvecode(LY_VECODE vecode);
+
+/**
+ * @brief Get the last (thread-specific) full logged error message.
+ *
+ * This function is useful for getting errors from functions that do not have any context accessible and includes
+ * any additional information such as the path or line where the error occurred.
+ *
+ * @return Last generated error message.
+ */
+LIBYANG_API_DECL const char *ly_last_logmsg(void);
+
+/**
+ * @brief Get the first (thread, context-specific) generated error structure.
+ *
+ * @param[in] ctx Relative context.
+ * @return First error structure, NULL if none available.
+ */
+LIBYANG_API_DECL const struct ly_err_item *ly_err_first(const struct ly_ctx *ctx);
+
+/**
+ * @brief Get the latest (thread, context-specific) generated error structure.
+ *
+ * @param[in] ctx Relative context.
+ * @return Last error structure, NULL if none available.
+ */
+LIBYANG_API_DECL const struct ly_err_item *ly_err_last(const struct ly_ctx *ctx);
+
+/**
+ * @brief Print the error structure as if just generated.
+ *
+ * @param[in] ctx Optional context to store the message in.
+ * @param[in] eitem Error item structure to print.
+ */
+LIBYANG_API_DECL void ly_err_print(const struct ly_ctx *ctx, const struct ly_err_item *eitem);
+
+/**
+ * @brief Free error structures from a context.
+ *
+ * If @p eitem is not set, free all the error structures.
+ *
+ * @param[in] ctx Relative context.
+ * @param[in] eitem Oldest error structure to remove, optional.
+ */
+LIBYANG_API_DECL void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem);
+
+/** @} errors */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LY_LOG_H_ */