You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by xi...@apache.org on 2021/03/27 04:41:54 UTC
[incubator-nuttx] 03/03: doc: add user API syslog description
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 <ma...@protobits.dev>
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