1/* 2 * Copyright 2007-2022 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel D�rfler 7 * Niels Sascha Reedijk, niels.reedijk@gmail.com 8 * 9 * Corresponds to: 10 * headers/posix/syslog.h rev 6684 11 */ 12 13 14/*! 15 \file syslog.h 16 \ingroup libroot 17 \brief System logging capabilities 18 19 The syslog service is provided by a server in the background, the syslog_daemon. 20 21 After it has been started during the system's boot process, it will just sit there and wait for messages. Every call to syslog() or log_thread/team() will pass a message to the server containing information about what should be written to the log and with what options. The message is not a BMessage, but a plain data structure that can be created without any knowledge about BMessages. That is needed, because the service is used by the kernel as well. 22 23 The server then just passes on that message to its internal handlers. It has two built-in handlers. One of them just processes the message and dumps a formatted text to the syslog file at /var/log/syslog. The other one creates a standard BMessage out of the message and broadcasts it to all of its listeners. 24 25 If the syslog file reaches a certain size (by default 512 kB), it will be renamed to syslog.old, and a new syslog file is created. 26 27 The first call of a function that will connect to the syslog service will create a syslog session. It's important to know that there is one session for each thread that uses the service, as well as one extra session for all team-wide logging functions. 28 29 The original POSIX API as well as part of the additional BeOS API both use thread specific sessions. When a session is started, it will inherit the options defined for the team session. That means you can set logging options that every thread in your application will respect (if you don't overwrite them locally). But in order to define team wide options, you have to specifically use the BeOS-specific team API. 30*/ 31 32 33/*! 34 \fn void closelog(void) 35 \brief Closes the thread session, and frees all associated data 36 37 The next call to the syslog service will start a new session, and will inherit the team log options at that point again. 38*/ 39 40 41/*! 42 \fn void openlog(const char *ident, int options, int facility) 43 \brief Starts a log session, and sets some output options 44 45 Like openlog_thread() this function defines the log session in thread context; the 46 global options set by openlog_team() are not affected by this function. 47*/ 48 49 50/*! 51 \fn int setlogmask(int priorityMask) 52 \brief sets the logging priority mask 53*/ 54 55 56/*! 57 \fn void syslog(int priority, const char *message, ...) 58 \brief sends a message to the system log 59*/ 60 61 62/*! 63 \fn void closelog_team(void) 64 \brief Closes the current session 65 66 This has currently no effect for the team logging functions. 67*/ 68 69 70/*! 71 \fn void openlog_team(const char *ident, int logopt, int facility) 72 \brief Starts a log session, and sets some output options 73 74 This function defines the team-wide logging options. Thread local sessions 75 started with openlog() or openlog_thread() will inherit the options of the 76 global session. 77 78 \param ident The identification string that is prepended to every message from your team. 79 \param logopt Logging option(s). 80 \param facility Specifies from what facility your message has been sent; for most cases this should just be LOG_USER. 81*/ 82 83 84/*! 85 \fn void log_team(int priority, const char *message, ...) 86 \brief Sends a message of the specified priority to the syslog daemon. 87*/ 88 89 90/*! 91 \fn int setlogmask_team(int priorityMask) 92 \brief Sets the logging priority mask 93 94 Use the LOG_MASK() macro to build a mask of priorities to show. All messages of other priorities will be discarded. Example uses: 95 96\code 97setlogmask_team(LOG_MASK(LOG_WARNING)); 98 // all messages of priority LOG_WARNING will be shown 99 100setlogmask_team(LOG_MASK(LOG_ERR + 1) - 1); 101 // all messages with a priority level higher than LOG_ERR will be shown 102\endcode 103*/ 104 105 106/*! 107 \fn void closelog_thread(void) 108 \brief Closes the log 109*/ 110 111 112/*! 113 \fn void openlog_thread(const char *ident, int logopt, int facility) 114 \brief Starts a log session, and sets some output options 115*/ 116 117 118/*! 119 \fn void log_thread(int priority, const char *message, ...) 120 \brief sends a message to the system log 121*/ 122 123 124/*! 125 \fn int setlogmask_thread(int priorityMask) 126 \brief sets the logging priority mask 127*/ 128 129 130/*! 131 \name Options for openlog() 132*/ 133 134 135//! @{ 136 137 138/*! 139 \def LOG_PID 140 \brief Log the process (thread/team) ID with each message 141*/ 142 143 144/*! 145 \def LOG_CONS 146 \brief If the message cannot be delivered to the syslog daemon, it will be directly dumped to stderr. 147*/ 148 149 150/*! 151 \def LOG_ODELAY 152 \brief Delay open until syslog() is called 153*/ 154 155 156/*! 157 \def LOG_NDELAY 158 \brief Connect to the syslog daemon immediately 159*/ 160 161 162/*! 163 \def LOG_SERIAL 164 \brief Dump to serial output as well. 165 \attention This is not yet implemented 166*/ 167 168 169/*! 170 \def LOG_PERROR 171 \brief The message will not only be sent to the syslog daemon, it will also be written to the application's stderr (unconditionally). 172*/ 173 174 175/*! 176 \def LOG_NOWAIT 177 \brief Do not wait for child processes 178*/ 179 180 181//! @} 182 183 184/*! \name Facilities for openlog() 185*/ 186 187 188//! @{ 189 190 191/*! 192 \def LOG_KERN 193 \brief Reserved for messages generated by the kernel. 194*/ 195 196 197/*! 198 \def LOG_USER 199 \brief Reserved for messages generated by user processes. 200*/ 201 202 203/*! 204 \def LOG_MAIL 205 \brief Standard (?) POSIX facility for messages by the mailing daemon. 206*/ 207 208 209/*! 210 \def LOG_DAEMON 211 \brief Standard POSIX (?) facility for messages by daemons (and Haiku servers). 212*/ 213 214 215/*! 216 \def LOG_AUTH 217 \brief Standard POSIX facility(?) for messages by the authentication services. 218*/ 219 220 221/*! 222 \def LOG_SYSLOG 223 \brief Reserved for messages generated by the syslog daemon. 224*/ 225 226 227/*! 228 \def LOG_LPR 229 \brief Reserved for messages generated by the UNIX lpr printing tool. 230*/ 231 232 233/*! 234 \def LOG_NEWS 235 \brief Reserved for messages generated by something UNIXy that does something with NEWS. 236*/ 237 238 239/*! 240 \def LOG_UUCP 241 \brief Reserved for messages generated by UUCP 242*/ 243 244 245/*! 246 \def LOG_CRON 247 \brief Reserved for messages generated by the CRON daemon. 248*/ 249 250 251/*! 252 \def LOG_AUTHPRIV 253 \brief Reserved for private (?) messages that relate to authentication. 254*/ 255 256 257/*! 258 \def LOG_LOCAL0 259 \brief For local use. 260*/ 261 262 263/*! 264 \def LOG_LOCAL1 265 \brief For local use. 266*/ 267 268 269/*! 270 \def LOG_LOCAL2 271 \brief For local use. 272*/ 273 274 275/*! 276 \def LOG_LOCAL3 277 \brief For local use. 278*/ 279 280 281/*! 282 \def LOG_LOCAL4 283 \brief For local use. 284*/ 285 286 287/*! 288 \def LOG_LOCAL5 289 \brief For local use. 290*/ 291 292 293/*! 294 \def LOG_LOCAL6 295 \brief For local use. 296*/ 297 298 299/*! 300 \def LOG_LOCAL7 301 \brief For local use. 302*/ 303 304 305//! @} 306 307 308/*! 309 \name Priorities for syslog(), log_team() and log_thread() 310*/ 311 312 313//! @{ 314 315 316/*! 317 \def LOG_EMERG 318 \brief A panic condition 319*/ 320 321 322/*! 323 \def LOG_PANIC 324 \brief An alias for LOG_EMERG 325*/ 326 327 328/*! 329 \def LOG_ALERT 330 \brief A condition to that should be corrected immediately 331*/ 332 333 334/*! 335 \def LOG_CRIT 336 \brief Critical conditions like hard drive errors 337*/ 338 339 340/*! 341 \def LOG_ERR 342 \brief Errors 343*/ 344 345 346/*! 347 \def LOG_WARNING 348 \brief Warnings 349*/ 350 351 352/*! 353 \def LOG_NOTICE 354 \brief Notices, instructions on how to use certain configuration options. 355*/ 356 357 358/*! 359 \def LOG_INFO 360 \brief Information, like versions and so. 361*/ 362 363 364/*! 365 \def LOG_DEBUG 366 \brief Debug information. 367*/ 368 369 370//! @} 371 372 373/*! 374 \def LOG_MASK 375 \brief Converts a priority definition for use in setlogmask() 376*/ 377