Update comments and function headers

3 files changed, 64 insertions, 1 deletions

diff --git a/nuttx/libc/syslog/lib_lowsyslog.c b/nuttx/libc/syslog/lib_lowsyslog.c
index ed0315f6b..79c4a99ff 100644
--- a/nuttx/libc/syslog/lib_lowsyslog.c
+++ b/nuttx/libc/syslog/lib_lowsyslog.c
@@ -86,6 +86,11 @@
 
 /****************************************************************************
  * Name: lowvsyslog_internal
+ *
+ * Description:
+ *   This is the internal implementation of lowvsyslog (see the description
+ *   of lowsyslog and lowvsyslog below)
+ *
  ****************************************************************************/
 
 static inline int lowvsyslog_internal(FAR const char *fmt, va_list ap)
@@ -108,6 +113,12 @@ static inline int lowvsyslog_internal(FAR const char *fmt, va_list ap)
 
 /****************************************************************************
  * Name: lowvsyslog
+ *
+ * Description:
+ *   The function lowvsyslog() performs the same task as lowsyslog() with
+ *   the difference that it takes a set of arguments which have been
+ *   obtained using the stdarg variable argument list macros.
+ *
  ****************************************************************************/
 
 int lowvsyslog(int priority, FAR const char *fmt, va_list ap)
@@ -128,6 +139,19 @@ int lowvsyslog(int priority, FAR const char *fmt, va_list ap)
 
 /****************************************************************************
  * Name: lowsyslog
+ *
+ * Description:
+ *   syslog() generates a log message. The priority argument is formed by
+ *   ORing the facility and the level values (see include/syslog.h). The
+ *   remaining arguments are a format, as in printf and any arguments to the
+ *   format.
+ *
+ *   This is a non-standard, low-level system logging interface.  The
+ *   difference between syslog() and lowsyslog() is that the syslog()
+ *   interface writes to the syslog device (usually fd=1, stdout) whereas
+ *   lowsyslog() uses a lower level interface that works even from interrupt
+ *   handlers.
+ *
  ****************************************************************************/
 
 int lowsyslog(int priority, FAR const char *fmt, ...)
diff --git a/nuttx/libc/syslog/lib_setlogmask.c b/nuttx/libc/syslog/lib_setlogmask.c
index 3645dceed..f51572e40 100644
--- a/nuttx/libc/syslog/lib_setlogmask.c
+++ b/nuttx/libc/syslog/lib_setlogmask.c
@@ -66,7 +66,25 @@ uint8_t g_syslog_mask = LOG_ALL;
  * Name: setlogmask
  *
  * Description:
- *  Enable or disable debug output.
+ *   The setlogmask() function sets the logmask and returns the previous
+ *   mask. If the mask argument is 0, the current logmask is not modified.
+ *
+ *   The SYSLOG priorities are: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
+ *   LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG.  The bit corresponding
+ *   to a priority p is LOG_MASK(p); LOG_UPTO(p) provides the mask of all
+ *   priorities in the above list up to and including p.
+ *
+ *   REVISIT: Per POSIX the syslog mask should be a per-process value but in
+ *   NuttX, the scope of the mask is dependent on the nature of the build.
+ *
+ *   Flat Build:  There is one, global SYSLOG mask that controls all output.
+ *   Protected Build:  There are two SYSLOG masks.  One within the kernel
+ *     that controls only kernel output.  And one in user-space that controls
+ *     only user SYSLOG output.
+ *   Kernel Build:  The kernel build is compliant with the POSIX requirement:
+ *     There will be one mask for for each user process, controlling the
+ *     SYSLOG output only form that process.  There will be a separate mask
+ *     accessable only in the kernel code to control kernel SYSLOG output.
  *
  ****************************************************************************/
 
diff --git a/nuttx/libc/syslog/lib_syslog.c b/nuttx/libc/syslog/lib_syslog.c
index 05cfe60ea..63441fd9e 100644
--- a/nuttx/libc/syslog/lib_syslog.c
+++ b/nuttx/libc/syslog/lib_syslog.c
@@ -84,6 +84,11 @@
 
 /****************************************************************************
  * Name: vsyslog_internal
+ *
+ * Description:
+ *   This is the internal implementation of vsyslog (see the description of
+ *   syslog and vsyslog below)
+ *
  ****************************************************************************/
 
 static inline int vsyslog_internal(FAR const char *fmt, va_list ap)
@@ -132,6 +137,12 @@ static inline int vsyslog_internal(FAR const char *fmt, va_list ap)
 
 /****************************************************************************
  * Name: vsyslog
+ *
+ * Description:
+ *   The function vsyslog() performs the same task as syslog() with the
+ *   difference that it takes a set of arguments which have been obtained
+ *   using the stdarg variable argument list macros.
+ *
  ****************************************************************************/
 
 int vsyslog(int priority, FAR const char *fmt, va_list ap)
@@ -152,6 +163,16 @@ int vsyslog(int priority, FAR const char *fmt, va_list ap)
 
 /****************************************************************************
  * Name: syslog
+ *
+ * Description:
+ *   syslog() generates a log message. The priority argument is formed by
+ *   ORing the facility and the level values (see include/syslog.h). The
+ *   remaining arguments are a format, as in printf and any arguments to the
+ *   format.
+ *
+ *   The NuttX implementation does not support any special formatting
+ *   characters beyond those supported by printf.
+ *
  ****************************************************************************/
 
 int syslog(int priority, FAR const char *fmt, ...)