[haiku-doc] System logging
- From: "Alan Smale" <ajsmale@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Mon, 4 Jun 2007 20:16:56 +0100
Hi guys,
I have performed some changes/proofreading to the system logging
documentation.
Can you check through and see whether it's acceptable.
Changes:
- Added system logging overview (Reworked from Axel's Haiku article)
- Added parameter lists to functions
- Reworked text to fit into the Doxygen structure
I'm not sure if ultimately the file names need renaming, so I've not done
that.
Cheers
Alan
Index: support_intro.dox
===================================================================
--- support_intro.dox (revision 21323)
+++ support_intro.dox (working copy)
@@ -33,6 +33,7 @@
- BStopWatch
- \ref support_globals "Global functions"
- \ref TypeConstants.h "Common types and constants"
+ - \ref support_system-logging "System logging"
- Error codes for all kits
*/
Index: syslog.dox
===================================================================
--- syslog.dox (revision 21323)
+++ syslog.dox (working copy)
@@ -1,12 +1,14 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
- * Documentation written by:
+ * Authors:
* Axel Dörfler
* Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
+ * Proofreaders:
+ * Alan Smale <ajsmale@xxxxxxxxx>
* Corresponds to:
- * /trunk/headers/posix/syslog.h rev 6684
+ * /trunk/headers/posix/syslog.h rev 11769
*/
/*!
@@ -15,76 +17,115 @@
\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 functions described here interact with the syslog_daemon, a server that
+ provides the system logging capabilities. The log output can be found in
+ /var/log/syslog.
*/
-/*!
+/*!
\fn void closelog(void)
- \brief Closes the current log session
+ \brief Closes the current log thread session
+
+ 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
+ \brief Starts a log session, and sets the 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.
+ 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.
+
+ \param ident The identification string that prepends every message from your
+ team.
+ \param options Allows you to set several logging options.
+ \param facility Determines from what facility your message has been sent.
*/
-/*!
+/*!
\fn int setlogmask(int priorityMask)
- \brief sets the logging priority mask
+ \brief Sets the log priority mask
+
+ \param priorityMask Mask of message priorities.
+ \return Previous log priority mask
*/
-/*!
+/*!
\fn void syslog(int priority, const char *message, ...)
- \brief sends a message to the system log
+ \brief Sends a message to the system log
+
+ \param priority Priority of message.
+ \param message Message to display.
*/
-/*!
+/*!
\fn void closelog_team(void)
\brief Closes the log
*/
-/*!
+/*!
\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 prepends every message from your
+ team.
+ \param logopt Allows you to set several logging options.
+ \param facility Determines from what facility your message has been sent.
*/
-/*!
+/*!
\fn void log_team(int priority, const char *message, ...)
- \brief sends a message to the system log
+ \brief Sends a message to the system log
+
+ \param priority Priority of message.
+ \param message Message to display.
*/
-/*!
+/*!
\fn int setlogmask_team(int priorityMask)
- \brief sets the logging priority mask
+ \brief Sets the log priority mask
+
+ \param priorityMask Mask of message priorities.
+ \return Previous log priority mask
*/
-/*!
+/*!
\fn void closelog_thread(void)
- \brief Closes the log
+ \brief Closes the current log thread session
+
+ 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_thread(const char *ident, int logopt, int facility)
- \brief Starts a log session, and sets some output options
+ \brief Starts a log session, and sets the output options
+
+ \param ident The identification string that prepends every message from your
+ team.
+ \param logopt Allows you to set several logging options.
+ \param facility Determines from what facility your message has been sent.
*/
-/*!
+/*!
\fn void log_thread(int priority, const char *message, ...)
- \brief sends a message to the system log
+ \brief Sends a message to the system log
+
+ \param priority Priority of message.
+ \param message Message to display.
*/
-/*!
+/*!
\fn int setlogmask_thread(int priorityMask)
- \brief sets the logging priority mask
+ \brief Sets the log priority mask
+
+ \param priorityMask Mask of message priorities.
+ \return Previous log priority mask
*/
/*!
@@ -93,38 +134,38 @@
//! @{
-/*!
+/*!
\def LOG_PID
\brief Log the process (thread/team) ID with each message
*/
-/*!
+/*!
\def LOG_CONS
\brief Log to the system console on error
*/
-/*!
+/*!
\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 Dump to stderr as well
*/
-/*!
+/*!
\def LOG_NOWAIT
\brief Do not wait for child processes
*/
@@ -137,44 +178,44 @@
//! @{
-/*!
+/*!
\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.
+ \brief Standard POSIX facility for messages by the mailing daemon.
*/
-/*!
+/*!
\def LOG_DAEMON
- \brief Standard POSIX (?) facility for messages by daemons (and Haiku
servers).
+ \brief Standard POSIX facility for messages by daemons (and Haiku servers).
*/
-/*!
+/*!
\def LOG_AUTH
- \brief Standard POSIX facility(?) for messages by the authentication
services.
+ \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.
+ \brief Reserved for messages generated by the UNIX news system.
*/
/*!
@@ -187,49 +228,49 @@
\brief Reserved for messages generated by the CRON daemon.
*/
-/*!
+/*!
\def LOG_AUTHPRIV
- \brief Reserved for private (?) messages that relate to authentication.
+ \brief Reserved for private messages that relate to authentication.
*/
/*!
\def LOG_LOCAL0
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
/*!
\def LOG_LOCAL1
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL2
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL3
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL4
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL5
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL6
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
-/*!
+/*!
\def LOG_LOCAL7
- \brief Use this for local use.
+ \brief Reserved for local use.
*/
//! @}
@@ -240,54 +281,54 @@
//! @{
-/*!
+/*!
\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
+ \brief Critical conditions such as 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.
+ \brief Informational messages.
*/
-/*!
+/*!
\def LOG_DEBUG
\brief Debug information.
*/\
//! @}
-/*!
+/*!
\def LOG_MASK
- \brief Converts a priority definition for use in setlogmask()
-*/
\ No newline at end of file
+ \brief Converts a priority definition into a mask for use with setlogmask()
+*/
Other related posts:
