To use the library, include liblognorm.h (which is quoted below) into your code. The API is fairly simple and hardly needs further explanations.
#include <stdlib.h> /* we need size_t */ #include <json.h> /* error codes */ #define LN_NOMEM -1 #define LN_INVLDFDESCR -1 #define LN_BADCONFIG -250 #define LN_BADPARSERSTATE -500 #define LN_WRONGPARSER -1000 #define LN_RB_LINE_TOO_LONG -1001 #define LN_OVER_SIZE_LIMIT -1002 /** * The library context descriptor. * This is used to permit multiple independent instances of the * library to be called within a single program. This is most * useful for plugin-based architectures. */ typedef struct ln_ctx_s* ln_ctx; /* API */ /** * Return library version string. * * Returns the version of the currently used library. * * @return Zero-Terminated library version string. */ /* Note: this MUST NOT be inline to make sure the actual library * has the right version, not just what was used to compile! */ const char *ln_version(void); /** * Return if library is build with advanced statistics * activated. * * @return 1 if advanced stats are active, 0 if not */ int ln_hasAdvancedStats(void); /** * Initialize a library context. * * To prevent memory leaks, ln_exitCtx() must be called on a library * context that is no longer needed. * * @return new library context or NULL if an error occured */ ln_ctx ln_initCtx(void); /** * Inherit control attributes from a library context. * * This does not copy the parse-tree, but does copy * behaviour-controling attributes such as enableRegex. * * Just as with ln_initCtx, ln_exitCtx() must be called on a library * context that is no longer needed. * * @return new library context or NULL if an error occured */ ln_ctx ln_inherittedCtx(ln_ctx parent); /** * Discard a library context. * * Free's the ressources associated with the given library context. It * MUST NOT be accessed after calling this function. * * @param ctx The context to be discarded. * * @return Returns zero on success, something else otherwise. */ int ln_exitCtx(ln_ctx ctx); /* binary values, so that we can "or" them together */ #define LN_CTXOPT_ALLOW_REGEX 0x01 /**< permit regex matching */ #define LN_CTXOPT_ADD_EXEC_PATH 0x02 /**< add exec_path attribute (time-consuming!) */ #define LN_CTXOPT_ADD_ORIGINALMSG 0x04 /**< always add original message to output (not just in error case) */ #define LN_CTXOPT_ADD_RULE 0x08 /**< add mockup rule */ #define LN_CTXOPT_ADD_RULE_LOCATION 0x10 /**< add rule location (file, lineno) to metadata */ /** * Set options on ctx. * * @param ctx The context to be modified. * @param opts a potentially or-ed list of options, see LN_CTXOPT_* */ void ln_setCtxOpts(ln_ctx ctx, unsigned opts); /** * Set a debug message handler (callback). * * Liblognorm can provide helpful information for debugging * - it's internal processing * - the way a log message is being normalized * * It does so by emiting "interesting" information about its processing * at various stages. A caller can obtain this information by registering * an entry point. When done so, liblognorm will call the entry point * whenever it has something to emit. Note that debugging can be rather * verbose. * * The callback will be called with the following three parameters in that order: * - the caller-provided cookie * - a zero-terminated string buffer * - the length of the string buffer, without the trailing NUL byte * * @note * The provided callback function <b>must not</b> call any liblognorm * APIs except when specifically flagged as safe for calling by a debug * callback handler. * * @param[in] ctx The library context to apply callback to. * @param[in] cb The function to be called for debugging * @param[in] cookie Opaque cookie to be passed down to debug handler. Can be * used for some state tracking by the caller. This is defined as * void* to support pointers. To play it safe, a pointer should be * passed (but advantorous folks may also use an unsigned). * * @return Returns zero on success, something else otherwise. */ int ln_setDebugCB(ln_ctx ctx, void (*cb)(void*, const char*, size_t), void *cookie); /** * Set a error message handler (callback). * * If set, this is used to emit error messages of interest to the user, e.g. * on failures during rulebase load. It is suggested that a caller uses this * feedback to aid its users in resolving issues. * Its semantics are otherwise exactly the same like ln_setDebugCB(). */ int ln_setErrMsgCB(ln_ctx ctx, void (*cb)(void*, const char*, size_t), void *cookie); /** * enable or disable debug mode. * * @param[in] ctx context * @param[in] b boolean 0 - disable debug mode, 1 - enable debug mode */ void ln_enableDebug(ln_ctx ctx, int i); /** * Load a (log) sample file. * * The file must contain log samples in syntactically correct format. Samples are added * to set already loaded in the current context. If there is a sample with duplicate * semantics, this sample will be ignored. Most importantly, this can \b not be used * to change tag assignments for a given sample. * * @param[in] ctx The library context to apply callback to. * @param[in] file Name of file to be loaded. * * @return Returns zero on success, something else otherwise. */ int ln_loadSamples(ln_ctx ctx, const char *file); /** * Normalize a message. * * This is the main library entry point. It is called with a message * to normalize and will return a normalized in-memory representation * of it. * * If an error occurs, the function returns -1. In that case, an * in-memory event representation has been generated if event is * non-NULL. In that case, the event contains further error details in * normalized form. * * @note * This function works on byte-counted strings and as such is able to * process NUL bytes if they occur inside the message. On the other hand, * this means the the correct messages size, \b excluding the NUL byte, * must be provided. * * @param[in] ctx The library context to use. * @param[in] str The message string (see note above). * @param[in] strLen The length of the message in bytes. * @param[out] json_p A new event record or NULL if an error occured. <b>Must be * destructed if no longer needed.</b> * * @return Returns zero on success, something else otherwise. */ int ln_normalize(ln_ctx ctx, const char *str, const size_t strLen, struct json_object **json_p);