![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
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.6
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.6-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 */
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/