summaryrefslogtreecommitdiff
path: root/libsyslog/src/lib.rs
blob: 7c253ae13e98b7c6c43fd63d36e5907fa62c174b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
//! This crate provides an API implementing the standard Rust logging facade
//! to the system's syslog. That is, it implements the [Log][log::Log] trait
//! of the [log] crate for native syslog (the one typically implemented in C
//! and residing in libc).
//!
//! Syslog needs to be initialized prior to any [logging macros][log#macros]
//! being called. That is usally done through a single chained call of its
//! [builder][Syslog::builder], with optional
//! [methods][SyslogBuilder#implementations] to customize the logger before
//! finalizing the setup by calling [build][SyslogBuilder::build] and
//! [init][Syslog::init].
//!
//! Typical use: (A.k.a. recommended snippet to copy'n'paste to the start of
//! `main()` of your daemon.)
//! ```
//! # fn main() -> Result<()> {
//! libsyslog::Syslog::builder()
//!     .module_level(std::module_path!(), log::LevelFilter::Info)
//!     .level(log::LevelFilter::Off)
//!     .build()
//!     .init()?;
//!
//! error!("Hello libsyslog. I've failed you.");
//! # }
//! ```
//!
//! It is likely reasonable for most users to configure the
//! [module_level][SyslogBuilder::module_level] and
//! [level][SyslogBuilder::level] filters to only have the application's own
//! log messages sent to syslog (ignoring potentially chatty libraries), as in
//! the above example.
//!
//! The scope of this crate is limited as described by the very first paragraph
//! above. Its intended use is during normal operation, in software with modest
//! requirements on low frequency logging. Note that syslog risks killing
//! performance. Consider using another additional facade, in combination with
//! a `--no-daemon` option, for when developing and debugging. And please
//! remember, if [libsyslog][`crate`] does not meet your requirements, there
//! are plenty of other crates for logging around.

// According to [doc][], syslog() and friends are not thread safe on AIX. It
// appears there is a family or related functions with an _r suffix which
// should likely be used instead. Patches for adding AIX support are welcome.
//
// It should of course possible to locally disable the check below, but then
// it's up to you to ensure your application is single threaded.
//
#[cfg(target_os = "aix")]
compile_error!("AIX user, please help with the code comment above this error.");
//
// [doc]: https://www.ibm.com/docs/en/aix/latest?topic=s-syslog-openlog-closelog-setlogmask-subroutine

mod builder;
mod facility;
// TODO Deprecate feature once the bitflags crate reaches 2.0.0.
#[cfg(feature = "bitflags")]
mod logopt;
mod syslog;

#[cfg(feature = "bitflags")]
pub use logopt::*;

pub use {
    builder::*,
    facility::*,
    syslog::*,
};