xref: /haiku/docs/user/posix/syslog.dox (revision 6fa3716c79e01303ae9b712a2d3c3659cae55730)

/*
 * Copyright 2007-2022 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel D�rfler
 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
 *
 * Corresponds to:
 *		headers/posix/syslog.h	rev 6684
 */


/*!
	\file syslog.h
	\ingroup libroot
	\brief System logging capabilities

	The syslog service is provided by a server in the background, the syslog_daemon.

	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.

	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.

	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.

	 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.

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


/*!
	\fn void closelog(void)
	\brief Closes the thread session, and frees all associated data

	The next call to the syslog service will start a new session, and will inherit the team log options at that point again.
*/


/*!
	\fn void openlog(const char *ident, int options, int facility)
	\brief Starts a log session, and sets some output options

	Like openlog_thread() this function defines the log session in thread context; the
	global options set by openlog_team() are not affected by this function.
*/


/*!
	\fn int setlogmask(int priorityMask)
	\brief sets the logging priority mask
*/


/*!
	\fn void syslog(int priority, const char *message, ...)
	\brief sends a message to the system log
*/


/*!
	\fn void closelog_team(void)
	\brief Closes the current session

	This has currently no effect for the team logging functions.
*/


/*!
	\fn void openlog_team(const char *ident, int logopt, int facility)
	\brief Starts a log session, and sets some output options

	This function defines the team-wide logging options. Thread local sessions
	started with openlog() or openlog_thread() will inherit the options of the
	global session.

	\param ident The identification string that is prepended to every message from your team.
	\param logopt Logging option(s).
	\param facility Specifies from what facility your message has been sent; for most cases this should just be LOG_USER.
*/


/*!
	\fn void log_team(int priority, const char *message, ...)
	\brief Sends a message of the specified priority to the syslog daemon.
*/


/*!
	\fn int setlogmask_team(int priorityMask)
	\brief Sets the logging priority mask

	Use the LOG_MASK() macro to build a mask of priorities to show. All messages of other priorities will be discarded. Example uses:

\code
setlogmask_team(LOG_MASK(LOG_WARNING));
	// all messages of priority LOG_WARNING will be shown

setlogmask_team(LOG_MASK(LOG_ERR + 1) - 1);
	// all messages with a priority level higher than LOG_ERR will be shown
\endcode
*/


/*!
	\fn void closelog_thread(void)
	\brief Closes the log
*/


/*!
	\fn void openlog_thread(const char *ident, int logopt, int facility)
	\brief Starts a log session, and sets some output options
*/


/*!
	\fn void log_thread(int priority, const char *message, ...)
	\brief sends a message to the system log
*/


/*!
	\fn int setlogmask_thread(int priorityMask)
	\brief sets the logging priority mask
*/


/*!
	\name Options for openlog()
*/


//! @{


/*!
	\def LOG_PID
	\brief Log the process (thread/team) ID with each message
*/


/*!
	\def LOG_CONS
	\brief If the message cannot be delivered to the syslog daemon, it will be directly dumped to stderr.
*/


/*!
	\def LOG_ODELAY
	\brief Delay open until syslog() is called
*/


/*!
	\def LOG_NDELAY
	\brief Connect to the syslog daemon immediately
*/


/*!
	\def LOG_SERIAL
	\brief Dump to serial output as well.
	\attention This is not yet implemented
*/


/*!
	\def LOG_PERROR
	\brief The message will not only be sent to the syslog daemon, it will also be written to the application's stderr (unconditionally).
*/


/*!
	\def LOG_NOWAIT
	\brief Do not wait for child processes
*/


//! @}


/*!	\name Facilities for openlog()
*/


//! @{


/*!
	\def LOG_KERN
	\brief Reserved for messages generated by the kernel.
*/


/*!
	\def LOG_USER
	\brief Reserved for messages generated by user processes.
*/


/*!
	\def LOG_MAIL
	\brief Standard (?) POSIX facility for messages by the mailing daemon.
*/


/*!
	\def LOG_DAEMON
	\brief Standard POSIX (?) facility for messages by daemons (and Haiku servers).
*/


/*!
	\def LOG_AUTH
	\brief Standard POSIX facility(?) for messages by the authentication services.
*/


/*!
	\def LOG_SYSLOG
	\brief Reserved for messages generated by the syslog daemon.
*/


/*!
	\def LOG_LPR
	\brief Reserved for messages generated by the UNIX lpr printing tool.
*/


/*!
	\def LOG_NEWS
	\brief Reserved for messages generated by something UNIXy that does something with NEWS.
*/


/*!
	\def LOG_UUCP
	\brief Reserved for messages generated by UUCP
*/


/*!
	\def LOG_CRON
	\brief Reserved for messages generated by the CRON daemon.
*/


/*!
	\def LOG_AUTHPRIV
	\brief Reserved for private (?) messages that relate to authentication.
*/


/*!
	\def LOG_LOCAL0
	\brief For local use.
*/


/*!
	\def LOG_LOCAL1
	\brief For local use.
*/


/*!
	\def LOG_LOCAL2
	\brief For local use.
*/


/*!
	\def LOG_LOCAL3
	\brief For local use.
*/


/*!
	\def LOG_LOCAL4
	\brief For local use.
*/


/*!
	\def LOG_LOCAL5
	\brief For local use.
*/


/*!
	\def LOG_LOCAL6
	\brief For local use.
*/


/*!
	\def LOG_LOCAL7
	\brief For local use.
*/


//! @}


/*!
	\name Priorities for syslog(), log_team() and log_thread()
*/


//! @{


/*!
	\def LOG_EMERG
	\brief A panic condition
*/


/*!
	\def LOG_PANIC
	\brief An alias for LOG_EMERG
*/


/*!
	\def LOG_ALERT
	\brief A condition to that should be corrected immediately
*/


/*!
	\def LOG_CRIT
	\brief Critical conditions like hard drive errors
*/


/*!
	\def LOG_ERR
	\brief Errors
*/


/*!
	\def LOG_WARNING
	\brief Warnings
*/


/*!
	\def LOG_NOTICE
	\brief Notices, instructions on how to use certain configuration options.
*/


/*!
	\def LOG_INFO
	\brief Information, like versions and so.
*/


/*!
	\def LOG_DEBUG
	\brief Debug information.
*/


//! @}


/*!
	\def LOG_MASK
	\brief Converts a priority definition for use in setlogmask()
*/