diff options
Diffstat (limited to 'doc/api.rst')
| -rw-r--r-- | doc/api.rst | 196 |
1 files changed, 98 insertions, 98 deletions
diff --git a/doc/api.rst b/doc/api.rst index ef5f985a8162..4ca51306472a 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,4 +1,4 @@ -.. index: API +.. index:: API The libxo API ============= @@ -155,14 +155,14 @@ Output Styles (XO_STYLE\_\*) The libxo functions accept a set of output styles: -=============== ========================= - Flag Description -=============== ========================= - XO_STYLE_TEXT Traditional text output - XO_STYLE_XML XML encoded data - XO_STYLE_JSON JSON encoded data - XO_STYLE_HTML HTML encoded data -=============== ========================= + =============== ========================= + Flag Description + =============== ========================= + XO_STYLE_TEXT Traditional text output + XO_STYLE_XML XML encoded data + XO_STYLE_JSON JSON encoded data + XO_STYLE_HTML HTML encoded data + =============== ========================= The "XML", "JSON", and "HTML" output styles all use the UTF-8 character encoding. "TEXT" using locale-based encoding. @@ -256,26 +256,26 @@ Flags (XOF\_\*) The set of valid flags include: -=================== ========================================= - Flag Description -=================== ========================================= - XOF_CLOSE_FP Close file pointer on `xo_destroy` - XOF_COLOR Enable color and effects in output - XOF_COLOR_ALLOWED Allow color/effect for terminal output - XOF_DTRT Enable "do the right thing" mode - XOF_INFO Display info data attributes (HTML) - XOF_KEYS Emit the key attribute (XML) - XOF_NO_ENV Do not use the :ref:`libxo-options` env var - XOF_NO_HUMANIZE Display humanization (TEXT, HTML) - XOF_PRETTY Make "pretty printed" output - XOF_UNDERSCORES Replaces hyphens with underscores - XOF_UNITS Display units (XML, HMTL) - XOF_WARN Generate warnings for broken calls - XOF_WARN_XML Generate warnings in XML on stdout - XOF_XPATH Emit XPath expressions (HTML) - XOF_COLUMNS Force xo_emit to return columns used - XOF_FLUSH Flush output after each `xo_emit` call -=================== ========================================= + =================== ========================================= + Flag Description + =================== ========================================= + XOF_CLOSE_FP Close file pointer on `xo_destroy` + XOF_COLOR Enable color and effects in output + XOF_COLOR_ALLOWED Allow color/effect for terminal output + XOF_DTRT Enable "do the right thing" mode + XOF_INFO Display info data attributes (HTML) + XOF_KEYS Emit the key attribute (XML) + XOF_NO_ENV Do not use the :ref:`libxo-options` env var + XOF_NO_HUMANIZE Display humanization (TEXT, HTML) + XOF_PRETTY Make "pretty printed" output + XOF_UNDERSCORES Replaces hyphens with underscores + XOF_UNITS Display units (XML, HMTL) + XOF_WARN Generate warnings for broken calls + XOF_WARN_XML Generate warnings in XML on stdout + XOF_XPATH Emit XPath expressions (HTML) + XOF_COLUMNS Force xo_emit to return columns used + XOF_FLUSH Flush output after each `xo_emit` call + =================== ========================================= The `XOF_CLOSE_FP` flag will trigger the call of the *close_func* (provided via `xo_set_writer`) when the handle is destroyed. @@ -300,12 +300,12 @@ regardless of whether warnings are enabled. If the style is `XO_STYLE_HTML`, the following additional flags can be used: -=============== ========================================= - Flag Description -=============== ========================================= - XOF_XPATH Emit "data-xpath" attributes - XOF_INFO Emit additional info fields -=============== ========================================= + =============== ========================================= + Flag Description + =============== ========================================= + XOF_XPATH Emit "data-xpath" attributes + XOF_INFO Emit additional info fields + =============== ========================================= The `XOF_XPATH` flag enables the emission of XPath expressions detailing the hierarchy of XML elements used to encode the data field, if the @@ -317,11 +317,11 @@ output. See :ref:`field-information` for details. If the style is `XO_STYLE_XML`, the following additional flags can be used: -=============== ========================================= - Flag Description -=============== ========================================= - XOF_KEYS Flag "key" fields for XML -=============== ========================================= + =============== ========================================= + Flag Description + =============== ========================================= + XOF_KEYS Flag "key" fields for XML + =============== ========================================= The `XOF_KEYS` flag adds "key" attribute to the XML encoding for field definitions that use the "k" modifier. The key attribute has @@ -1308,52 +1308,52 @@ These values are defined in <syslog.h>. The priority value indicates the importance and potential impact of each message: -============= ======================================================= - Priority Description -============= ======================================================= - LOG_EMERG A panic condition, normally broadcast to all users - LOG_ALERT A condition that should be corrected immediately - LOG_CRIT Critical conditions - LOG_ERR Generic errors - LOG_WARNING Warning messages - LOG_NOTICE Non-error conditions that might need special handling - LOG_INFO Informational messages - LOG_DEBUG Developer-oriented messages -============= ======================================================= + ============= ======================================================= + Priority Description + ============= ======================================================= + LOG_EMERG A panic condition, normally broadcast to all users + LOG_ALERT A condition that should be corrected immediately + LOG_CRIT Critical conditions + LOG_ERR Generic errors + LOG_WARNING Warning messages + LOG_NOTICE Non-error conditions that might need special handling + LOG_INFO Informational messages + LOG_DEBUG Developer-oriented messages + ============= ======================================================= The facility value indicates the source of message, in fairly generic terms: -=============== ======================================================= - Facility Description -=============== ======================================================= - LOG_AUTH The authorization system (e.g. :manpage:`login(1)`) - LOG_AUTHPRIV As LOG_AUTH, but logged to a privileged file - LOG_CRON The cron daemon: :manpage:`cron(8)` - LOG_DAEMON System daemons, not otherwise explicitly listed - LOG_FTP The file transfer protocol daemons - LOG_KERN Messages generated by the kernel - LOG_LPR The line printer spooling system - LOG_MAIL The mail system - LOG_NEWS The network news system - LOG_SECURITY Security subsystems, such as :manpage:`ipfw(4)` - LOG_SYSLOG Messages generated internally by :manpage:`syslogd(8)` - LOG_USER Messages generated by user processes (default) - LOG_UUCP The uucp system - LOG_LOCAL0..7 Reserved for local use -=============== ======================================================= + =============== ======================================================= + Facility Description + =============== ======================================================= + LOG_AUTH The authorization system (e.g. :manpage:`login(1)`) + LOG_AUTHPRIV As LOG_AUTH, but logged to a privileged file + LOG_CRON The cron daemon: :manpage:`cron(8)` + LOG_DAEMON System daemons, not otherwise explicitly listed + LOG_FTP The file transfer protocol daemons + LOG_KERN Messages generated by the kernel + LOG_LPR The line printer spooling system + LOG_MAIL The mail system + LOG_NEWS The network news system + LOG_SECURITY Security subsystems, such as :manpage:`ipfw(4)` + LOG_SYSLOG Messages generated internally by :manpage:`syslogd(8)` + LOG_USER Messages generated by user processes (default) + LOG_UUCP The uucp system + LOG_LOCAL0..7 Reserved for local use + =============== ======================================================= In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific logging behaviors: -============ ==================================================== - Flag Description -============ ==================================================== - LOG_CONS If syslogd fails, attempt to write to /dev/console - LOG_NDELAY Open the connection to :manpage:`syslogd(8)` immediately - LOG_PERROR Write the message also to standard error output - LOG_PID Log the process id with each message -============ ==================================================== + ============ ==================================================== + Flag Description + ============ ==================================================== + LOG_CONS If syslogd fails, attempt to write to /dev/console + LOG_NDELAY Open the connection to :manpage:`syslogd(8)` immediately + LOG_PERROR Write the message also to standard error output + LOG_PID Log the process id with each message + ============ ==================================================== .. index:: xo_syslog @@ -1588,26 +1588,26 @@ processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed: -======================= ======================================= - Operation Meaning (Base function) -======================= ======================================= - XO_OP_CREATE Called when the handle is created - XO_OP_OPEN_CONTAINER Container opened (xo_open_container) - XO_OP_CLOSE_CONTAINER Container closed (xo_close_container) - XO_OP_OPEN_LIST List opened (xo_open_list) - XO_OP_CLOSE_LIST List closed (xo_close_list) - XO_OP_OPEN_LEAF_LIST Leaf list opened (xo_open_leaf_list) - XO_OP_CLOSE_LEAF_LIST Leaf list closed (xo_close_leaf_list) - XO_OP_OPEN_INSTANCE Instance opened (xo_open_instance) - XO_OP_CLOSE_INSTANCE Instance closed (xo_close_instance) - XO_OP_STRING Field with Quoted UTF-8 string - XO_OP_CONTENT Field with content - XO_OP_FINISH Finish any pending output - XO_OP_FLUSH Flush any buffered output - XO_OP_DESTROY Clean up resources - XO_OP_ATTRIBUTE An attribute name/value pair - XO_OP_VERSION A version string -======================= ======================================= + ======================= ======================================= + Operation Meaning (Base function) + ======================= ======================================= + XO_OP_CREATE Called when the handle is created + XO_OP_OPEN_CONTAINER Container opened (xo_open_container) + XO_OP_CLOSE_CONTAINER Container closed (xo_close_container) + XO_OP_OPEN_LIST List opened (xo_open_list) + XO_OP_CLOSE_LIST List closed (xo_close_list) + XO_OP_OPEN_LEAF_LIST Leaf list opened (xo_open_leaf_list) + XO_OP_CLOSE_LEAF_LIST Leaf list closed (xo_close_leaf_list) + XO_OP_OPEN_INSTANCE Instance opened (xo_open_instance) + XO_OP_CLOSE_INSTANCE Instance closed (xo_close_instance) + XO_OP_STRING Field with Quoted UTF-8 string + XO_OP_CONTENT Field with content + XO_OP_FINISH Finish any pending output + XO_OP_FLUSH Flush any buffered output + XO_OP_DESTROY Clean up resources + XO_OP_ATTRIBUTE An attribute name/value pair + XO_OP_VERSION A version string + ======================= ======================================= For all the open and close operations, the name parameter holds the name of the construct. For string, content, and attribute operations, |