/usr/share/doc/liblognorm-dev/html/libraryapi.html is in liblognorm-dev 1.1.2-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Library API — A fast log normalization library</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.1.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="A fast log normalization library" href="index.html" />
<link rel="next" title="Liblognorm internals" href="internals.html" />
<link rel="prev" title="Lognormalizer" href="lognormalizer.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Liblognorm 1.1.2 documentation</span></a></h1>
<h2 class="heading"><span>Library API</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="lognormalizer.html">Lognormalizer</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="internals.html">Liblognorm internals</a>  »
</p>
</div>
<div class="content">
<div class="section" id="library-api">
<h1>Library API<a class="headerlink" href="#library-api" title="Permalink to this headline">¶</a></h1>
<p>To use the library, include liblognorm.h (which is quoted below) into your code.
The API is fairly simple and hardly needs further explanations.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdlib.h> </span><span class="cm">/* we need size_t */</span><span class="cp"></span>
<span class="cp">#include <libestr.h></span>
<span class="cp">#include <json.h></span>
<span class="cm">/* error codes */</span>
<span class="cp">#define LN_NOMEM -1</span>
<span class="cp">#define LN_INVLDFDESCR -1</span>
<span class="cp">#define LN_BADCONFIG -250</span>
<span class="cp">#define LN_BADPARSERSTATE -500</span>
<span class="cp">#define LN_WRONGPARSER -1000</span>
<span class="cp">#define LN_RB_LINE_TOO_LONG -1001</span>
<span class="cm">/**</span>
<span class="cm"> * The library context descriptor.</span>
<span class="cm"> * This is used to permit multiple independent instances of the</span>
<span class="cm"> * library to be called within a single program. This is most</span>
<span class="cm"> * useful for plugin-based architectures.</span>
<span class="cm"> */</span>
<span class="k">typedef</span> <span class="k">struct</span> <span class="n">ln_ctx_s</span><span class="o">*</span> <span class="n">ln_ctx</span><span class="p">;</span>
<span class="cm">/* API */</span>
<span class="cm">/**</span>
<span class="cm"> * Return library version string.</span>
<span class="cm"> *</span>
<span class="cm"> * Returns the version of the currently used library.</span>
<span class="cm"> *</span>
<span class="cm"> * @return Zero-Terminated library version string.</span>
<span class="cm"> */</span>
<span class="cm">/* Note: this MUST NOT be inline to make sure the actual library</span>
<span class="cm"> * has the right version, not just what was used to compile!</span>
<span class="cm"> */</span>
<span class="kt">char</span> <span class="o">*</span><span class="nf">ln_version</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Initialize a library context.</span>
<span class="cm"> *</span>
<span class="cm"> * To prevent memory leaks, ln_exitCtx() must be called on a library</span>
<span class="cm"> * context that is no longer needed.</span>
<span class="cm"> *</span>
<span class="cm"> * @return new library context or NULL if an error occured</span>
<span class="cm"> */</span>
<span class="n">ln_ctx</span> <span class="nf">ln_initCtx</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Inherit control attributes from a library context.</span>
<span class="cm"> *</span>
<span class="cm"> * This does not copy the parse-tree, but does copy</span>
<span class="cm"> * behaviour-controling attributes such as enableRegex.</span>
<span class="cm"> *</span>
<span class="cm"> * Just as with ln_initCtx, ln_exitCtx() must be called on a library</span>
<span class="cm"> * context that is no longer needed.</span>
<span class="cm"> *</span>
<span class="cm"> * @return new library context or NULL if an error occured</span>
<span class="cm"> */</span>
<span class="n">ln_ctx</span> <span class="nf">ln_inherittedCtx</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">parent</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Discard a library context.</span>
<span class="cm"> *</span>
<span class="cm"> * Free's the ressources associated with the given library context. It</span>
<span class="cm"> * MUST NOT be accessed after calling this function.</span>
<span class="cm"> *</span>
<span class="cm"> * @param ctx The context to be discarded.</span>
<span class="cm"> *</span>
<span class="cm"> * @return Returns zero on success, something else otherwise.</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">ln_exitCtx</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Set options on ctx.</span>
<span class="cm"> *</span>
<span class="cm"> * @param ctx The context to be modified.</span>
<span class="cm"> * @param allow_regex A boolean indicating regex-usage should/shouldn't be allowed</span>
<span class="cm"> */</span>
<span class="kt">void</span>
<span class="nf">ln_setCtxOpts</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="kt">int</span> <span class="n">allow_regex</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Set a debug message handler (callback).</span>
<span class="cm"> *</span>
<span class="cm"> * Liblognorm can provide helpful information for debugging</span>
<span class="cm"> * - it's internal processing</span>
<span class="cm"> * - the way a log message is being normalized</span>
<span class="cm"> *</span>
<span class="cm"> * It does so by emiting "interesting" information about its processing</span>
<span class="cm"> * at various stages. A caller can obtain this information by registering</span>
<span class="cm"> * an entry point. When done so, liblognorm will call the entry point</span>
<span class="cm"> * whenever it has something to emit. Note that debugging can be rather</span>
<span class="cm"> * verbose.</span>
<span class="cm"> *</span>
<span class="cm"> * The callback will be called with the following three parameters in that order:</span>
<span class="cm"> * - the caller-provided cookie</span>
<span class="cm"> * - a zero-terminated string buffer</span>
<span class="cm"> * - the length of the string buffer, without the trailing NUL byte</span>
<span class="cm"> *</span>
<span class="cm"> * @note</span>
<span class="cm"> * The provided callback function <b>must not</b> call any liblognorm</span>
<span class="cm"> * APIs except when specifically flagged as safe for calling by a debug</span>
<span class="cm"> * callback handler.</span>
<span class="cm"> *</span>
<span class="cm"> * @param[in] ctx The library context to apply callback to.</span>
<span class="cm"> * @param[in] cb The function to be called for debugging</span>
<span class="cm"> * @param[in] cookie Opaque cookie to be passed down to debug handler. Can be</span>
<span class="cm"> * used for some state tracking by the caller. This is defined as</span>
<span class="cm"> * void* to support pointers. To play it safe, a pointer should be</span>
<span class="cm"> * passed (but advantorous folks may also use an unsigned).</span>
<span class="cm"> *</span>
<span class="cm"> * @return Returns zero on success, something else otherwise.</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">ln_setDebugCB</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">cb</span><span class="p">)(</span><span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">cookie</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Set a error message handler (callback).</span>
<span class="cm"> *</span>
<span class="cm"> * If set, this is used to emit error messages of interest to the user, e.g.</span>
<span class="cm"> * on failures during rulebase load. It is suggested that a caller uses this</span>
<span class="cm"> * feedback to aid its users in resolving issues.</span>
<span class="cm"> * Its semantics are otherwise exactly the same like ln_setDebugCB().</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">ln_setErrMsgCB</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">cb</span><span class="p">)(</span><span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">cookie</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * enable or disable debug mode.</span>
<span class="cm"> *</span>
<span class="cm"> * @param[in] ctx context</span>
<span class="cm"> * @param[in] b boolean 0 - disable debug mode, 1 - enable debug mode</span>
<span class="cm"> */</span>
<span class="kt">void</span> <span class="nf">ln_enableDebug</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="kt">int</span> <span class="n">i</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Reads a sample stored in buffer buf and creates a new ln_samp object</span>
<span class="cm"> * out of it.</span>
<span class="cm"> *</span>
<span class="cm"> * @note</span>
<span class="cm"> * It is the caller's responsibility to delete the newly</span>
<span class="cm"> * created ln_samp object if it is no longer needed.</span>
<span class="cm"> *</span>
<span class="cm"> * @param[ctx] ctx current library context</span>
<span class="cm"> * @param[buf] NULL terminated cstr containing the contents of the sample</span>
<span class="cm"> * @return Returns zero on success, something else otherwise.</span>
<span class="cm"> */</span>
<span class="kt">int</span>
<span class="nf">ln_loadSample</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Load a (log) sample file.</span>
<span class="cm"> *</span>
<span class="cm"> * The file must contain log samples in syntactically correct format. Samples are added</span>
<span class="cm"> * to set already loaded in the current context. If there is a sample with duplicate</span>
<span class="cm"> * semantics, this sample will be ignored. Most importantly, this can \b not be used</span>
<span class="cm"> * to change tag assignments for a given sample.</span>
<span class="cm"> *</span>
<span class="cm"> * @param[in] ctx The library context to apply callback to.</span>
<span class="cm"> * @param[in] file Name of file to be loaded.</span>
<span class="cm"> *</span>
<span class="cm"> * @return Returns zero on success, something else otherwise.</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">ln_loadSamples</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">file</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * Normalize a message.</span>
<span class="cm"> *</span>
<span class="cm"> * This is the main library entry point. It is called with a message</span>
<span class="cm"> * to normalize and will return a normalized in-memory representation</span>
<span class="cm"> * of it.</span>
<span class="cm"> *</span>
<span class="cm"> * If an error occurs, the function returns -1. In that case, an</span>
<span class="cm"> * in-memory event representation has been generated if event is</span>
<span class="cm"> * non-NULL. In that case, the event contains further error details in</span>
<span class="cm"> * normalized form.</span>
<span class="cm"> *</span>
<span class="cm"> * @note</span>
<span class="cm"> * This function works on byte-counted strings and as such is able to</span>
<span class="cm"> * process NUL bytes if they occur inside the message. On the other hand,</span>
<span class="cm"> * this means the the correct messages size, \b excluding the NUL byte,</span>
<span class="cm"> * must be provided.</span>
<span class="cm"> *</span>
<span class="cm"> * @param[in] ctx The library context to use.</span>
<span class="cm"> * @param[in] str The message string (see note above).</span>
<span class="cm"> * @param[in] strLen The length of the message in bytes.</span>
<span class="cm"> * @param[out] json_p A new event record or NULL if an error occured. <b>Must be</span>
<span class="cm"> * destructed if no longer needed.</b></span>
<span class="cm"> *</span>
<span class="cm"> * @return Returns zero on success, something else otherwise.</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">ln_normalize</span><span class="p">(</span><span class="n">ln_ctx</span> <span class="n">ctx</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">strLen</span><span class="p">,</span> <span class="k">struct</span> <span class="n">json_object</span> <span class="o">**</span><span class="n">json_p</span><span class="p">);</span>
</pre></div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="lognormalizer.html">Lognormalizer</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="internals.html">Liblognorm internals</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
</div>
</body>
</html>
|