root/src/libsir/include/sir.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


   1 /**
   2  * @file sir.h
   3  *
   4  * @brief Public interface to libsir
   5  *
   6  * The functions and types defined here comprise the entire set intended for
   7  * use by an implementer of the library-unless modification is desired.
   8  *
   9  * @version 2.2.5
  10  *
  11  * -----------------------------------------------------------------------------
  12  *
  13  * SPDX-License-Identifier: MIT
  14  *
  15  * Copyright (c) 2018-2024 Ryan M. Lederman <lederman@gmail.com>
  16  *
  17  * Permission is hereby granted, free of charge, to any person obtaining a copy of
  18  * this software and associated documentation files (the "Software"), to deal in
  19  * the Software without restriction, including without limitation the rights to
  20  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  21  * the Software, and to permit persons to whom the Software is furnished to do so,
  22  * subject to the following conditions:
  23  *
  24  * The above copyright notice and this permission notice shall be included in all
  25  * copies or substantial portions of the Software.
  26  *
  27  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  28  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  29  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  30  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  31  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  32  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  33  *
  34  * -----------------------------------------------------------------------------
  35  */
  36 
  37 #ifndef _SIR_H_INCLUDED
  38 # define _SIR_H_INCLUDED
  39 
  40 # include "sir/platform.h"
  41 # include "sir/version.h"
  42 # include "sir/types.h"
  43 
  44 # if defined(SWIG)
  45 #  define PRINTF_FORMAT
  46 #  define PRINTF_FORMAT_ATTR(fmt_p, va_p)
  47 # endif
  48 
  49 # if defined(__cplusplus)
  50 extern "C" {
  51 # endif
  52 
  53 /**
  54  * @defgroup public Public Interface
  55  *
  56  * Functions and types that comprise the public interface to libsir.
  57  *
  58  * @addtogroup public
  59  * @{
  60  *
  61  * @defgroup publicfuncs Functions
  62  * @{
  63  */
  64 
  65 /**
  66  * @brief Fills out a ::sirinit structure with default values.
  67  *
  68  * Creates an initialization configuration for libsir essentially using all of
  69  * the default values (i.e., level registrations, formatting options, and text
  70  * styling).
  71  *
  72  * @note Does not fill in string fields, such as ::sirinit.name.
  73  *
  74  * @param   si   Pointer to a ::sirinit structure to receive default values.
  75  * @returns bool `true` if `si` is not `NULL`, `false` otherwise.
  76  */
  77 bool sir_makeinit(sirinit* si);
  78 
  79 /**
  80  * @brief Initializes libsir for use.
  81  *
  82  * Must be called before making any other calls into libsir (with the exception
  83  * of ::sir_makeinit).
  84  *
  85  * For every call to ::sir_init, there must be a corresponding call to
  86  * ::sir_cleanup. All exported libsir functions are thread-safe, so you may
  87  * initialize and cleanup on whichever thread you wish.
  88  *
  89  * @see ::sir_makeinit
  90  * @see ::sir_cleanup
  91  *
  92  * @param si Pointer to a ::sirinit structure containing the desired settings
  93  * and configuration. libsir makes a copy of this structure, so its lifetime
  94  * is not a concern.
  95  *
  96  * @returns bool `true` if initialization was successful, `false` otherwise. Call
  97  * ::sir_geterror to obtain information about any error that may have occurred.
  98  */
  99 bool sir_init(sirinit* si);
 100 
 101 /**
 102  * @brief Tears down and cleans up libsir after use.
 103  *
 104  * Deallocates resources such as memory buffers, file descriptors, etc. and
 105  * resets the internal state. No calls into libsir will succeed after calling
 106  * ::sir_cleanup (with the exception of ::sir_makeinit, ::sir_init,
 107  * ::sir_isinitialized,::sir_geterror, and ::sir_geterrorinfo).
 108  *
 109  * May be called from any thread. If you wish to utilize libsir again during the
 110  * same process' lifetime, simply call ::sir_init again.
 111  *
 112  * @returns bool `true` if cleanup was successful, `false otherwise`. Call
 113  * ::sir_geterror to obtain information about any error that may have occurred.
 114  */
 115 bool sir_cleanup(void);
 116 
 117 /**
 118  * @brief Determines whether or not libsir is in the initialized state.
 119  *
 120  * Provided as a convenience method to detect whether libsir requires initial-
 121  * ization or cleanup at any given time.
 122  *
 123  * @remark Calling ::sir_init after libsir is initialized produces an error.
 124  * Similarly, ::sir_cleanup behaves the same way if libsir is not initialized.
 125  *
 126  * @returns bool `true` if ::sir_init has been called and libsir is initialized;
 127  * `false` if ::sir_init has not yet been called, or a corresponding call to
 128  * ::sir_cleanup has already been made.
 129  */
 130 bool sir_isinitialized(void);
 131 
 132 /**
 133  * @brief Retrieves a formatted message for the last error that occurred on the
 134  * calling thread and returns the associated error code.
 135  *
 136  * To retrieve more granular information about an error, or to customize the
 137  * error message format, use ::sir_geterrorinfo.
 138  *
 139  * @remark libsir maintains errors on a per-thread basis, so it's important that
 140  * the same thread that encountered a failed library call be the one to retrieve
 141  * the error message.
 142  *
 143  * @param   message  A buffer of ::SIR_MAXERROR chars into which the error message
 144  *                   is placed.
 145  * @returns uint16_t An error code (see ::sir_errorcode). Returns ::SIR_E_NOERROR
 146  *                   if no error has occurred.
 147  */
 148 uint16_t sir_geterror(char message[SIR_MAXERROR]);
 149 
 150 /**
 151  * @brief Retrieves granular information about the last error that occurred on
 152  * the calling thread.
 153  *
 154  * To retrieve just an error code and a formatted message, use ::sir_geterror.
 155  *
 156  * @remark libsir maintains errors on a per-thread basis, so it's important that
 157  * the same thread that encountered a failed library call be the one to retrieve
 158  * the error message.
 159  *
 160  * @param err Pointer to a ::sir_errorinfo structure into which the error infor-
 161  *            mation is placed.
 162  */
 163 void sir_geterrorinfo(sir_errorinfo* err);
 164 
 165 /**
 166  * @brief Dispatches a ::SIRL_DEBUG level message.
 167  *
 168  * The message will be delivered to all destinations registered to receive
 169  * debug-level messages, each with their own formatting and styling options.
 170  *
 171  * @remark To change options or level registrations for `stdout`/`stderr`, call
 172  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 173  * respectively. To change the text styling on a per-level basis, call
 174  * ::sir_settextstyle.
 175  *
 176  * @see ::sir_level
 177  * @see ::sir_option
 178  * @see ::default
 179  *
 180  * @param   format A printf-style format string, representing the template for
 181  *                 the message to dispatch.
 182  * @param   ...    Arguments whose type and position align with the format
 183  *                 specifiers in `format`.
 184  * @returns bool   `true` if the message was dispatched successfully to all
 185  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 186  *                 to obtain information about any error that may have occurred.
 187  */
 188 PRINTF_FORMAT_ATTR(1, 2)
 189 bool sir_debug(PRINTF_FORMAT const char* format, ...);
 190 
 191 /**
 192  * @brief Dispatches a ::SIRL_INFO level message.
 193  *
 194  * The message will be delivered to all destinations registered to receive
 195  * information-level messages, each with their own formatting and styling options.
 196  *
 197  * @remark To change options or level registrations for `stdout`/`stderr`, call
 198  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 199  * respectively. To change the text styling on a per-level basis, call
 200  * ::sir_settextstyle.
 201  *
 202  * @see ::sir_level
 203  * @see ::sir_option
 204  * @see ::default
 205  *
 206  * @param   format A printf-style format string, representing the template for
 207  *                 the message to dispatch.
 208  * @param   ...    Arguments whose type and position align with the format
 209  *                 specifiers in `format`.
 210  * @returns bool   `true` if the message was dispatched successfully to all
 211  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 212  *                 to obtain information about any error that may have occurred.
 213  */
 214 PRINTF_FORMAT_ATTR(1, 2)
 215 bool sir_info(PRINTF_FORMAT const char* format, ...);
 216 
 217 /**
 218  * @brief Dispatches a ::SIRL_NOTICE level message.
 219  *
 220  * The message will be delivered to all destinations registered to receive
 221  * notice-level messages, each with their own formatting and styling options.
 222  *
 223  * @remark To change options or level registrations for `stdout`/`stderr`, call
 224  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 225  * respectively. To change the text styling on a per-level basis, call
 226  * ::sir_settextstyle.
 227  *
 228  * @see ::sir_level
 229  * @see ::sir_option
 230  * @see ::default
 231  *
 232  * @param   format A printf-style format string, representing the template for
 233  *                 the message to dispatch.
 234  * @param   ...    Arguments whose type and position align with the format
 235  *                 specifiers in `format`.
 236  * @returns bool   `true` if the message was dispatched successfully to all
 237  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 238  *                 to obtain information about any error that may have occurred.
 239  */
 240 PRINTF_FORMAT_ATTR(1, 2)
 241 bool sir_notice(PRINTF_FORMAT const char* format, ...);
 242 
 243 /**
 244  * @brief Dispatches a ::SIRL_WARN level message.
 245  *
 246  * The message will be delivered to all destinations registered to receive
 247  * warning-level messages, each with their own formatting and styling options.
 248  *
 249  * @remark To change options or level registrations for `stdout`/`stderr`, call
 250  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 251  * respectively. To change the text styling on a per-level basis, call
 252  * ::sir_settextstyle.
 253  *
 254  * @see ::sir_level
 255  * @see ::sir_option
 256  * @see ::default
 257  *
 258  * @param   format A printf-style format string, representing the template for
 259  *                 the message to dispatch.
 260  * @param   ...    Arguments whose type and position align with the format
 261  *                 specifiers in `format`.
 262  * @returns bool   `true` if the message was dispatched successfully to all
 263  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 264  *                 to obtain information about any error that may have occurred.
 265  */
 266 PRINTF_FORMAT_ATTR(1, 2)
 267 bool sir_warn(PRINTF_FORMAT const char* format, ...);
 268 
 269 /**
 270  * @brief Dispatches a ::SIRL_ERROR level message.
 271  *
 272  * The message will be delivered to all destinations registered to receive
 273  * error-level messages, each with their own formatting and styling options.
 274  *
 275  * @remark To change options or level registrations for `stdout`/`stderr`, call
 276  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 277  * respectively. To change the text styling on a per-level basis, call
 278  * ::sir_settextstyle.
 279  *
 280  * @see ::sir_level
 281  * @see ::sir_option
 282  * @see ::default
 283  *
 284  * @param   format A printf-style format string, representing the template for
 285  *                 the message to dispatch.
 286  * @param   ...    Arguments whose type and position align with the format
 287  *                 specifiers in `format`.
 288  * @returns bool   `true` if the message was dispatched successfully to all
 289  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 290  *                 to obtain information about any error that may have occurred.
 291  */
 292 PRINTF_FORMAT_ATTR(1, 2)
 293 bool sir_error(PRINTF_FORMAT const char* format, ...);
 294 
 295 /**
 296  * @brief Dispatches a ::SIRL_CRIT level message.
 297  *
 298  * The message will be delivered to all destinations registered to receive
 299  * critical-level messages, each with their own formatting and styling options.
 300  *
 301  * @remark To change options or level registrations for `stdout`/`stderr`, call
 302  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 303  * respectively. To change the text styling on a per-level basis, call
 304  * ::sir_settextstyle.
 305  *
 306  * @see ::sir_level
 307  * @see ::sir_option
 308  * @see ::default
 309  *
 310  * @param   format A printf-style format string, representing the template for
 311  *                 the message to dispatch.
 312  * @param   ...    Arguments whose type and position align with the format
 313  *                 specifiers in `format`.
 314  * @returns bool   `true` if the message was dispatched successfully to all
 315  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 316  *                 to obtain information about any error that may have occurred.
 317  */
 318 PRINTF_FORMAT_ATTR(1, 2)
 319 bool sir_crit(PRINTF_FORMAT const char* format, ...);
 320 
 321 /**
 322  * @brief Dispatches a ::SIRL_ALERT level message.
 323  *
 324  * The message will be delivered to all destinations registered to receive
 325  * alert-level messages, each with their own formatting and styling options.
 326  *
 327  * @remark To change options or level registrations for `stdout`/`stderr`, call
 328  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 329  * respectively. To change the text styling on a per-level basis, call
 330  * ::sir_settextstyle.
 331  *
 332  * @see ::sir_level
 333  * @see ::sir_option
 334  * @see ::default
 335  *
 336  * @param   format A printf-style format string, representing the template for
 337  *                 the message to dispatch.
 338  * @param   ...    Arguments whose type and position align with the format
 339  *                 specifiers in `format`.
 340  * @returns bool   `true` if the message was dispatched successfully to all
 341  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 342  *                 to obtain information about any error that may have occurred.
 343  */
 344 PRINTF_FORMAT_ATTR(1, 2)
 345 bool sir_alert(PRINTF_FORMAT const char* format, ...);
 346 
 347 /**
 348  * @brief Dispatches a ::SIRL_EMERG level message.
 349  *
 350  * The message will be delivered to all destinations registered to receive
 351  * emergency-level messages, each with their own formatting and styling options.
 352  *
 353  * @remark To change options or level registrations for `stdout`/`stderr`, call
 354  * ::sir_stdoutopts/::sir_stdoutlevels and ::sir_stderropts/::sir_stderrlevels,
 355  * respectively. To change the text styling on a per-level basis, call
 356  * ::sir_settextstyle.
 357  *
 358  * @see ::sir_level
 359  * @see ::sir_option
 360  * @see ::default
 361  *
 362  * @param   format A printf-style format string, representing the template for
 363  *                 the message to dispatch.
 364  * @param   ...    Arguments whose type and position align with the format
 365  *                 specifiers in `format`.
 366  * @returns bool   `true` if the message was dispatched successfully to all
 367  *                 registered destinations, `false` otherwise. Call ::sir_geterror
 368  *                 to obtain information about any error that may have occurred.
 369  */
 370 PRINTF_FORMAT_ATTR(1, 2)
 371 bool sir_emerg(PRINTF_FORMAT const char* format, ...);
 372 
 373 /**
 374  * @brief Adds a log file and registers it to receive log output.
 375  *
 376  * The file at `path` will be created if it does not exist, otherwise it will
 377  * be appended to.
 378  *
 379  * The levels for which the file will receive output are specified in the
 380  * `levels` bitmask. If you wish to use the default levels, pass
 381  * ::SIRL_DEFAULT.
 382  *
 383  * The formatting options for the log output sent to the file are specified in
 384  * the `opts` bitmask. If you wish to use the default options, pass
 385  * ::SIRO_DEFAULT. By default, log files receive all available information.
 386  *
 387  * @remark Take note of the ::SIR_FROLLSIZE compile-time constant. When any log
 388  * file reaches that size in bytes, it will be archived to a date-stamped file
 389  * in the same directory, and logging will resume at the path of the original file.
 390  *
 391  * @remark If `path` is a relative path, it shall be treated as relative to the
 392  * _current working directory_. This is not necessarily the same directory that
 393  * your application's binary file resides in.
 394  *
 395  * @remark The return value from this function is only valid for the lifetime of
 396  * the process. If a crash or restart occurs, you will no longer be able to refer
 397  * to the file by that identifier, and will have to add it again (libsir does not
 398  * persist its log file cache).
 399  *
 400  * @remark To change the file's level registrations or options after adding it,
 401  * call ::sir_filelevels and ::sir_fileopts, respectively.
 402  *
 403  * @see ::sir_remfile
 404  *
 405  * @param path        The absolute or relative path of the file to become a
 406  *                    logging destination for libsir.
 407  * @param levels      Level registration bitmask.
 408  * @param opts        Formatting options bitmask.
 409  * @returns sirfileid If successful, a unique identifier that can later be used
 410  *                    to modify level registrations, options, or remove the file
 411  *                    from libsir. Upon failure, returns zero. Use ::sir_geterror
 412  *                    to obtain information about any error that may have occurred.
 413  */
 414 sirfileid sir_addfile(const char* path, sir_levels levels, sir_options opts);
 415 
 416 /**
 417  * @brief Removes a file previously added to libsir.
 418  *
 419  * Immediately causes the file represented by `id` (the value returned from
 420  * ::sir_addfile) to be removed from libsir, and its file descriptor closed.
 421  *
 422  * Its contents will remain intact, and any pending writes will be flushed to
 423  * the file before it is closed.
 424  *
 425  * @see ::sir_filelevels
 426  * @see ::sir_fileopts
 427  *
 428  * @param   id   The ::sirfileid obtained when the file was added to libsir.
 429  * @returns bool `true` if the file is known to libsir and was successfully
 430  *               removed, `false` otherwise. Use ::sir_geterror to obtain
 431  *               information about any error that may have occurred.
 432  */
 433 bool sir_remfile(sirfileid id);
 434 
 435 /**
 436  * @brief Loads a plugin module from disk.
 437  *
 438  * Loads, queries, validates, and initializes a libsir plugin module. If loading
 439  * and validation are successful, the plugin is registered in the internal cache.
 440  *
 441  * After that point in time, the plugin will be notified upon the dispatching of
 442  * log messages on any ::sir_level the plugin registered for when it was loaded.
 443  *
 444  * @remark If `path` is a relative path, it shall be treated as relative to the
 445  * _current working directory_. This is not necessarily the same directory that
 446  * your application's binary file resides in.
 447  *
 448  * @remark The return value from this function is only valid for the lifetime of
 449  * the process. If a crash or restart occurs, you will no longer be able to refer
 450  * to the plugin by that identifier, and will have to load it again (libsir does
 451  * not persist its plugin cache).
 452  *
 453  * @see ::sir_unloadplugin
 454  * @see ::plugins
 455  *
 456  * @param  path         The absolute or relative path of the plugin to be loaded
 457  *                      and registered.
 458  * @returns sirpluginid If successful, a unique identifier that may later be used
 459  *                      to unload the plugin module. Upon failure, returns zero.
 460  *                      Use ::sir_geterror to obtain information about any error
 461  *                      that may have occurred.
 462  */
 463 sirpluginid sir_loadplugin(const char* path);
 464 
 465 /**
 466  * @brief Unloads a previously registered plugin module.
 467  *
 468  * Cleans up, de-registers, and unloads a plugin represented by `id` (the value
 469  * returned from ::sir_loadplugin).
 470  *
 471  * If the plugin is located in the cache, it is instructed to clean up and prepare
 472  * to be unloaded. Upon completion of the plugin's clean up routine, it is unloaded.
 473  *
 474  * @see ::sir_loadplugin
 475  * @see ::plugins
 476  *
 477  * @param   id   The ::sirpluginid obtained when the plugin was loaded.
 478  * @returns bool `true` if the plugin was located and successfully unloaded,`false`
 479  *               otherwise. Use ::sir_geterror to obtain information about any
 480  *               error that may have occurred.
 481  */
 482 bool sir_unloadplugin(sirpluginid id);
 483 
 484 /**
 485  * @brief Set new level registrations for a log file already managed by libsir.
 486  *
 487  * By default, log files are registered for the following levels:
 488  *
 489  * - all levels (SIRL_ALL)
 490  *
 491  * @see ::sir_fileopts
 492  *
 493  * @param   id     The ::sirfileid obtained when the file was added to libsir.
 494  * @param   levels New bitmask of ::sir_level to register for. If you wish to use
 495  *                 the default levels, pass ::SIRL_DEFAULT.
 496  * @returns bool   `true` if the file is known to libsir and was successfully
 497  *                 updated, `false` otherwise. Use ::sir_geterror to obtain
 498  *                 information about any error that may have occurred.
 499  */
 500 bool sir_filelevels(sirfileid id, sir_levels levels);
 501 
 502 /**
 503  * @brief Set new formatting options for a log file already managed by libsir.
 504  *
 505  * By default, log files have the following formatting options:
 506  *
 507  * - ::SIRO_ALL
 508  * - ::SIRO_NOHOST
 509  *
 510  * @see ::sir_filelevels
 511  *
 512  * @param   id   The ::sirfileid obtained when the file was added to libsir.
 513  * @param   opts New bitmask of ::sir_option for the file. If you wish to use
 514  *               the default options, pass ::SIRO_DEFAULT.
 515  * @returns bool `true` if the file is known to libsir and was successfully
 516  *               updated, `false` otherwise. Use ::sir_geterror to obtain
 517  *               information about any error that may have occurred.
 518  */
 519 bool sir_fileopts(sirfileid id, sir_options opts);
 520 
 521 /**
 522  * @brief Set new text styling for stdio (stdout/stderr) destinations on a
 523  * per-level basis.
 524  *
 525  * @see ::sir_setcolormode
 526  * @see ::sir_resettextstyles
 527  * @see ::default
 528  *
 529  * @note Use `SIRTC_DEFAULT` to get the default foreground or background color.
 530  * To set colors in RGB color mode, use ::sir_makergb to create the foreground
 531  * and background colors.
 532  *
 533  * @param   level The ::sir_level for which to set the text styling.
 534  * @param   attr  The ::sir_textattr attributes to apply to the text.
 535  * @param   fg    The foreground color to apply to the text.
 536  * @param   bg    The background color to apply to the text.
 537  * @returns bool  `true` if successfully updated, `false` otherwise. Use
 538  *                ::sir_geterror to obtain information about any error that may
 539  *                have occurred.
 540  */
 541 bool sir_settextstyle(sir_level level, sir_textattr attr, sir_textcolor fg,
 542     sir_textcolor bg);
 543 
 544 /**
 545  * @brief Reset text styling for stdio (stdout/stderr) destinations to their
 546  * default values.
 547  *
 548  * @note The text styling will be applied according to the current color mode
 549  * (as previously set by ::sir_setcolormode, or by default, 16-color mode).
 550  *
 551  * @see ::sir_setcolormode
 552  * @see ::sir_settextstyle
 553  * @see ::default
 554  *
 555  * @returns bool `true` if successfully reset, `false` otherwise. Use
 556  * ::sir_geterror to obtain information about any error that may have occurred.
 557  */
 558 bool sir_resettextstyles(void);
 559 
 560 /**
 561  * @brief Creates a ::sir_textcolor from red, green, and blue components.
 562  *
 563  * @note Use this function to create colors suitable for ::sir_settextstyle when
 564  * using RGB color mode.
 565  *
 566  * @see ::sir_setcolormode
 567  * @see ::sir_settextstyle
 568  * @see ::default
 569  *
 570  * @param   r             The red component (0..255)
 571  * @param   g             The green component (0..255)
 572  * @param   b             The blue component (0..255)
 573  * @returns sir_textcolor The color created by combining the r, g, and b components.
 574  */
 575 sir_textcolor sir_makergb(sir_textcolor r, sir_textcolor g, sir_textcolor b);
 576 
 577 /**
 578  * @brief Sets the ANSI color mode for stdio destinations.
 579  *
 580  * @note Some terminals may not support the color modes offered by libsir, so
 581  * make sure everything looks right after changing the mode.
 582  *
 583  * @note When you change the color mode, all previously set text styles will be
 584  * reset to their defaults. You will have to reapply any text styles set before
 585  * this call.
 586  *
 587  * The available modes are:
 588  *
 589  * - `SIRCM_16`:  4-bit, 16-color mode. Colors are defined by the `SIRTC_*` values.
 590  *                This is the default mode.
 591  * - `SIRCM_256`: 8-bit, 256-color mode. Colors are defined by numeric value (0..255)
 592  * - `SIRCM_RGB`: 24-bit RGB color mode. Colors are defined by numeric value, with
 593  *                red, green, and blue components (0..255) each.
 594  *
 595  * @see ::sir_makergb
 596  * @see ::sir_settextstyle
 597  * @see ::default
 598  *
 599  * @param   mode One of the `SIRCM_*` constants, defining the mode to use.
 600  * @returns bool `true` if the color mode was changed successfully, `false`
 601  *               otherwise. Use ::sir_geterror to obtain information about any
 602  *               error that may have occurred.
 603  */
 604 bool sir_setcolormode(sir_colormode mode);
 605 
 606 /**
 607  * @brief Set new level registrations for `stdout`.
 608  *
 609  * By default, `stdout` is registered for the following levels:
 610  *
 611  * - debug   (SIRL_DEBUG)
 612  * - info    (SIRL_INFO)
 613  * - notice  (SIRL_NOTICE)
 614  * - warning (SIRL_WARN)
 615  *
 616  * To modify formatting options for `stdout`, use ::sir_stdoutopts.
 617  *
 618  * @see ::sir_stdoutopts
 619  *
 620  * @param   levels New bitmask of ::sir_level to register for. If you wish to use
 621  *                 the default levels, pass ::SIRL_DEFAULT.
 622  * @returns bool   `true` if successfully updated, `false` otherwise. Use
 623  *                 ::sir_geterror to obtain information about any error that may
 624  *                 have occurred.
 625  */
 626 bool sir_stdoutlevels(sir_levels levels);
 627 
 628 /**
 629  * @brief Set new formatting options for `stdout`.
 630  *
 631  * By default, `stdout` has the following formatting options:
 632  *
 633  * - ::SIRO_NOTIME
 634  * - ::SIRO_NOHOST
 635  * - ::SIRO_NOPID
 636  * - ::SIRO_NOTID
 637  *
 638  * To modify level registrations for `stdout`, use ::sir_stdoutlevels.
 639  *
 640  * @see ::sir_stdoutlevels
 641  *
 642  * @param   opts New bitmask of ::sir_option for `stdout`. If you wish to use the
 643  *               default values, pass ::SIRL_DEFAULT.
 644  * @returns bool `true` if successfully updated, `false` otherwise. Use
 645  *               ::sir_geterror to obtain information about any error that may
 646  *               have occurred.
 647  */
 648 bool sir_stdoutopts(sir_options opts);
 649 
 650 /**
 651  * @brief Set new level registrations for `stderr`.
 652  *
 653  * By default, `stderr` is registered for the following levels:
 654  *
 655  * - error     (SIRL_ERROR)
 656  * - critical  (SIRL_CRIT)
 657  * - alert     (SIRL_ALERT)
 658  * - emergency (SIRL_EMERG)
 659  *
 660  * To modify formatting options for `stderr`, use ::sir_stderropts.
 661  *
 662  * @see ::sir_stderropts
 663  *
 664  * @param   levels New bitmask of ::sir_level to register for. If you wish to use
 665  *                 the default levels, pass ::SIRL_DEFAULT.
 666  * @returns bool   `true` if successfully updated, `false` otherwise. Use
 667  *                 ::sir_geterror to obtain information about any error that may
 668  *                 have occurred.
 669  */
 670 bool sir_stderrlevels(sir_levels levels);
 671 
 672 /**
 673  * @brief Set new formatting options for `stderr`.
 674  *
 675  * By default, `stderr` has the following formatting options:
 676  *
 677  * - ::SIRO_NOTIME
 678  * - ::SIRO_NOHOST
 679  * - ::SIRO_NOPID
 680  * - ::SIRO_NOTID
 681  *
 682  * To modify level registrations for `stderr`, use ::sir_stderrlevels.
 683  *
 684  * @see ::sir_stderrlevels
 685  *
 686  * @param   opts New bitmask of ::sir_option for `stderr`. If you wish to use the
 687  *               default values, pass ::SIRL_DEFAULT.
 688  * @returns bool `true` if successfully updated, `false` otherwise. Use
 689  *               ::sir_geterror to obtain information about any error that may
 690  *               have occurred.
 691  */
 692 bool sir_stderropts(sir_options opts);
 693 
 694 /**
 695  * @brief Set new level registrations for the system logger destination.
 696  *
 697  * By default, the system logger is registered for the following levels:
 698  *
 699  * - notice    (SIRL_NOTICE)
 700  * - warning   (SIRL_WARNING)
 701  * - error     (SIRL_ERROR)
 702  * - critical  (SIRL_CRIT)
 703  * - emergency (SIRL_EMERG)
 704  *
 705  * To modify formatting options for the system logger, use ::sir_syslogopts.
 706  *
 707  * @see ::sir_syslogopts
 708  *
 709  * @param   levels New bitmask of ::sir_level to register for. If you wish to use
 710  *                 the default levels, pass ::SIRL_DEFAULT.
 711  * @returns bool   `true` if successfully updated, `false` otherwise. Use
 712  *                 ::sir_geterror to obtain information about any error that may
 713  *                 have occurred.
 714  */
 715 bool sir_sysloglevels(sir_levels levels);
 716 
 717 /**
 718  * @brief Set new formatting options for the system logger destination.
 719  *
 720  * By default, the system logger has the following formatting options:
 721  *
 722  * - ::SIRO_MSGONLY
 723  *
 724  * To modify level registrations for the system logger, use ::sir_sysloglevels.
 725  *
 726  * @see ::sir_sysloglevels
 727  *
 728  * @param   opts New bitmask of ::sir_option for the system logger. If you wish
 729  *               to use the default values, pass ::SIRO_DEFAULT.
 730  * @returns bool `true` if successfully updated, `false` otherwise. Use
 731  *               ::sir_geterror to obtain information about any error that may
 732  *               have occurred.
 733  */
 734 bool sir_syslogopts(sir_options opts);
 735 
 736 /**
 737  * @brief Set new system logger identity.
 738  *
 739  * In the context of the system logger (i.e., `syslog`/`os_log`/etc.), identity
 740  * refers to the `name` that appears in the log for the current process.
 741  *
 742  * Upon library initialization, the system logger identity is resolved as follows:
 743  *
 744  * 1. If the @ref sir_syslog_dest.identity "sirinit.d_syslog.identity" string is set,
 745  *    it will be used.
 746  * 2. If the ::sirinit.name string is set, it will be used.
 747  * 3. If the name of the current process is available, it will be used.
 748  * 4. If none of these are available, the string ::SIR_FALLBACK_SYSLOG_ID will
 749  *    be used.
 750  *
 751  * @remark If `SIR_NO_SYSTEM_LOGGERS` is defined when compiling libsir, this
 752  * function will immediately return false, and set the last error to
 753  * ::SIR_E_UNAVAIL.
 754  *
 755  * @param   identity The string to use as the system logger identity.
 756  * @returns bool     `true` if successfully updated, `false` otherwise. Use
 757  *                   ::sir_geterror to obtain information about any error that
 758  *                   may have occurred.
 759  */
 760 bool sir_syslogid(const char* identity);
 761 
 762 /**
 763  * @brief Set new system logger category.
 764  *
 765  * Some system logger facilities (e.g. `os_log`, the system logger on macOS), ask
 766  * for a category string when logging messages-to more easily group messages
 767  * together (which, as a byproduct, enhances searching).
 768  *
 769  * If you are not utilizing a system logger that requires a category string, you
 770  * do not need to call this function (or set @ref sir_syslog_dest.category
 771  * "sirinit.d_syslog.category").
 772  *
 773  * Upon library initialization, the system logger category is resolved as follows:
 774  *
 775  * 1. If the @ref sir_syslog_dest.category "sirinit.d_syslog.category" string is
 776  *    set, it will be used.
 777  * 2. The string ::SIR_FALLBACK_SYSLOG_CAT will be used.
 778  *
 779  * @remark If `SIR_NO_SYSTEM_LOGGERS` is defined when compiling libsir, this
 780  * function will immediately return false, and set the last error to
 781  * ::SIR_E_UNAVAIL.
 782  *
 783  * @param category The string to use as the system logger category.
 784  * @returns bool   `true` if successfully updated, `false` otherwise. Use
 785  *                 ::sir_geterror to obtain information about any error that
 786  *                 may have occurred.
 787  */
 788 bool sir_syslogcat(const char* category);
 789 
 790 /**
 791  * @brief Returns the current libsir version as a string.
 792  *
 793  * @note This may be helpful when using libsir as a shared library-it will always
 794  * return the value of the shared library, not the source version of libsir
 795  * that you built against.
 796  *
 797  * **Example:**
 798  *
 799  * ~~~
 800  * 2.2.5-dev
 801  * ~~~
 802  *
 803  * @returns const char* The current libsir version string.
 804  */
 805 const char* sir_getversionstring(void);
 806 
 807 /**
 808  * @brief Returns the current libsir version as a number.
 809  *
 810  * @note Can be formatted as a hexadecimal number with %08x.
 811  *
 812  * @returns uint32_t The current libsir version number.
 813  */
 814 uint32_t sir_getversionhex(void);
 815 
 816 /**
 817  * @brief Whether or not this is a pre-release version of libsir.
 818  *
 819  * @returns bool `true` if this is a pre-release version of libsir (i.e., not
 820  * a public release), `false` if this is a public release version.
 821  */
 822 bool sir_isprerelease(void);
 823 
 824 /**
 825  * @}
 826  * @}
 827  */
 828 
 829 # if defined(__cplusplus)
 830 }
 831 # endif
 832 
 833 #endif /* !_SIR_H_INCLUDED */

/* [previous][next][first][last][top][bottom][index][help] */