docs/user: Import syslog documentation from an old Haiku newsletter article.

docs/user/posix/syslog.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2007 Haiku, Inc. All rights reserved.
+ * Copyright 2007-2022 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -16,15 +16,25 @@
 	\ingroup libroot
 	\brief System logging capabilities
 
-	The functions described here are interacting with the syslog_daemon, a server
-	that provides the system logging capabilities.
-	The log can be found in /var/log/syslog.
+	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 current log session
+	\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.
 */
 
 
@@ -51,7 +61,9 @@
 
 /*!
 	\fn void closelog_team(void)
-	\brief Closes the log
+	\brief Closes the current session
+
+	This has currently no effect for the team logging functions.
 */
 
 
@@ -62,18 +74,32 @@
 	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 to the system log
+	\brief Sends a message of the specified priority to the syslog daemon.
 */
 
 
 /*!
 	\fn int setlogmask_team(int priorityMask)
-	\brief sets the logging priority mask
+	\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
 */
 
 
@@ -111,25 +137,25 @@
 
 /*!
 	\def LOG_PID
-	\brief Log the process (thread/team) ID with each message 
+	\brief Log the process (thread/team) ID with each message
 */
 
 
 /*!
 	\def LOG_CONS
-	\brief Log to the system console on error
+	\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 
+	\brief Delay open until syslog() is called
 */
 
 
 /*!
 	\def LOG_NDELAY
-	\brief Connect to the syslog daemon immediately 
+	\brief Connect to the syslog daemon immediately
 */
 
 
@@ -142,7 +168,7 @@
 
 /*!
 	\def LOG_PERROR
-	\brief Dump to stderr as well
+	\brief The message will not only be sent to the syslog daemon, it will also be written to the application's stderr (unconditionally).
 */
 
 
@@ -198,7 +224,7 @@
 */
 
 
-/*! 
+/*!
 	\def LOG_LPR
 	\brief Reserved for messages generated by the UNIX lpr printing tool.
 */
@@ -264,13 +290,13 @@
 */
 
 
-/*! 
+/*!
 	\def LOG_LOCAL6
 	\brief For local use.
 */
 
 
-/*! 
+/*!
 	\def LOG_LOCAL7
 	\brief For local use.
 */
@@ -311,7 +337,7 @@
 */
 
 
-/*! 
+/*!
 	\def LOG_ERR
 	\brief Errors
 */