This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 3fdd9266ec10a479e9dc4049860ce83094b4986f Author: Matias N <[email protected]> AuthorDate: Fri Mar 26 14:49:15 2021 -0300 doc: add user API syslog description --- Documentation/reference/user/13_logging.rst | 95 +++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/Documentation/reference/user/13_logging.rst b/Documentation/reference/user/13_logging.rst new file mode 100644 index 0000000..ad73493 --- /dev/null +++ b/Documentation/reference/user/13_logging.rst @@ -0,0 +1,95 @@ +======= +Logging +======= + +NuttX provides the SYSLOG for application and OS logging, which can be +configured in various ways to select how these messages are displayed +(see details :doc:`here </components/drivers/special/syslog>`). + +Applications can emit logging messages using the standard :c:func:`syslog` +interface. + +.. note:: The standard :c:func:`openlog` and :c:func:`closelog` + are not currently supported. + +.. c:function:: void syslog(int priority, const char *fmt, ...) + + This interface allows to send messages to SYSLOG using standard + :c:func:`printf` formatting. + + Each message sent to SYSLOG is assigned a priority. Depending + on system configuration this message may or not appear in the + output. + + :param priority: A priority given by ``LOG_*`` family of + definitions. + + :param fmt: The format string + +.. c:function:: void vsyslog(int priority, const char *fmt, va_list ap) + + Performs the same task as :c:func:`syslog` with the + difference that it takes a set of arguments which have been obtained + using the :file:`include/stdarg.h` variable argument list macros. + +.. c:function:: int setlogmask(int mask) + + Sets the logging mask which controls which messages appear on SYSLOG + output. :c:func:`setlogmask` is not a thread-safe, re-entrant function. + Concurrent use will have undefined behavior. + + :param mask: The new mask to set. + See :c:macro:`LOG_MASK` and :c:macro:`LOG_UPTO`. + Per OpenGroup.org "If the maskpri argument is 0, the current log mask + is not modified." In this implementation, the value zero is permitted + in order to disable all syslog levels. + + :returns: The previous mask. + + .. warning:: 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 each user process, controlling the SYSLOG + output only form that process. There will be a separate mask + accessible only in the kernel code to control kernel SYSLOG output. + +Priority Levels +=============== + +The following levels are defined: + +================ =========== +Priority (macro) Description +================ =========== +``LOG_EMERG`` System is unusable +``LOG_ALERT`` Action must be taken immediately +``LOG_CRIT`` Critical conditions +``LOG_ERR`` Error conditions +``LOG_WARNING`` Warning conditions +``LOG_NOTICE`` Normal, but significant, condition +``LOG_INFO`` Informational message +``LOG_DEBUG`` Debug-level message +================ =========== + +Priority mask +============= + +The following macros can be used with :c:func:`setlogmask`: + +.. c:macro:: LOG_MASK(p) + + Returns the logmask corresponding priority ``p`` + +.. c:macro:: LOG_UPTO(p) + + Returns the logmask of all SYSLOG priorities + up to and including ``p``. + +.. c:macro:: LOG_ALL + + Mask corresponding to all priorities enabled \ No newline at end of file
