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 */