<!--
 Documentation/_templates/layout.html

 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.  The
 ASF licenses this file to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance with the
 License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 License for the specific language governing permissions and limitations
 under the License.
-->

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>SYSLOG &mdash; NuttX latest documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="../_static/tabs.css" type="text/css" />
      <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/sphinx_highlight.js"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Binary Loader" href="binfmt.html" />
    <link rel="prev" title="SocketCAN Device Drivers" href="socketcan.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
  
    <a href="../index.html" class="icon icon-home"> NuttX
  

  </a>
  
  <!-- this version selector is quite ugly, should be probably replaced by something
       more modern -->
       
  <div class="version-selector">
    <select onchange="javascript:location.href = this.value;">
    
    <option value="../../latest" selected="selected">latest</option>
    
    <option value="../../10.0.0" >10.0.0</option>
    
    <option value="../../10.0.1" >10.0.1</option>
    
    <option value="../../10.1.0" >10.1.0</option>
    
    <option value="../../10.2.0" >10.2.0</option>
    
    <option value="../../10.3.0" >10.3.0</option>
    
    <option value="../../11.0.0" >11.0.0</option>
    
    <option value="../../12.0.0" >12.0.0</option>
    
    <option value="../../12.1.0" >12.1.0</option>
    
    <option value="../../12.2.0" >12.2.0</option>
    
    <option value="../../12.2.1" >12.2.1</option>
    
    <option value="../../12.3.0" >12.3.0</option>
    
    <option value="../../12.4.0" >12.4.0</option>
    
    <option value="../../12.5.0" >12.5.0</option>
    
    <option value="../../12.5.1" >12.5.1</option>
    
    </select>
  </div>
  
  
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">OS Components</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="nsh/index.html">NuttShell (NSH)</a></li>
<li class="toctree-l2"><a class="reference internal" href="power.html">Power Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="socketcan.html">SocketCAN Device Drivers</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">SYSLOG</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#syslog-interfaces">SYSLOG Interfaces</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#standard-syslog-interfaces">Standard SYSLOG Interfaces</a></li>
<li class="toctree-l4"><a class="reference internal" href="#debug-interfaces">Debug Interfaces</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#syslog-channels">SYSLOG Channels</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#syslog-channel-interfaces">SYSLOG Channel Interfaces</a></li>
<li class="toctree-l4"><a class="reference internal" href="#syslog-channel-initialization">SYSLOG Channel Initialization</a></li>
<li class="toctree-l4"><a class="reference internal" href="#interrupt-level-syslog-output">Interrupt Level SYSLOG Output</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#syslog-channel-options">SYSLOG Channel Options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#syslog-console-device">SYSLOG Console Device</a></li>
<li class="toctree-l4"><a class="reference internal" href="#syslog-character-device">SYSLOG Character Device</a></li>
<li class="toctree-l4"><a class="reference internal" href="#syslog-file-device">SYSLOG File Device</a></li>
<li class="toctree-l4"><a class="reference internal" href="#syslog-ramlog-device">SYSLOG RAMLOG Device</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#ram-logging-device">RAM Logging Device</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#dmesg-command"><code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command</a></li>
<li class="toctree-l4"><a class="reference internal" href="#ramlog-configuration-options">RAMLOG Configuration options</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="binfmt.html">Binary Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="drivers/index.html">Device Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="filesystem.html">NuttX File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="nxflat.html">NXFLAT</a></li>
<li class="toctree-l2"><a class="reference internal" href="nxgraphics/index.html">NX Graphics Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="nxwidgets.html">NxWidgets</a></li>
<li class="toctree-l2"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">NuttX</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">OS Components</a></li>
      <li class="breadcrumb-item active">SYSLOG</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/components/syslog.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="syslog">
<h1>SYSLOG<a class="headerlink" href="#syslog" title="Permalink to this heading"></a></h1>
<section id="syslog-interfaces">
<h2>SYSLOG Interfaces<a class="headerlink" href="#syslog-interfaces" title="Permalink to this heading"></a></h2>
<section id="standard-syslog-interfaces">
<h3>Standard SYSLOG Interfaces<a class="headerlink" href="#standard-syslog-interfaces" title="Permalink to this heading"></a></h3>
<p>The NuttX SYSLOG is an architecture for getting debug and status
information from the system. The syslogging interfaces are defined
in the header file <code class="docutils literal notranslate"><span class="pre">include/syslog.h</span></code>. The primary interface to
SYSLOG sub-system is the function <code class="docutils literal notranslate"><span class="pre">syslog()</span></code> and, to a lesser
extent, its companion <code class="docutils literal notranslate"><span class="pre">vsyslog()</span></code>:</p>
<p>The above are all standard interfaces as defined at
<a class="reference external" href="http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html">OpenGroup.org</a>.
Those interfaces are available for use by application software.
The remaining interfaces discussed in this section are non-standard, OS-internal interfaces.</p>
</section>
<section id="debug-interfaces">
<h3>Debug Interfaces<a class="headerlink" href="#debug-interfaces" title="Permalink to this heading"></a></h3>
<p>In NuttX, syslog output is really synonymous to debug output and,
therefore, the debugging interface macros defined in the header
file <code class="docutils literal notranslate"><span class="pre">include/debug.h</span></code> are also syslogging interfaces. Those
macros are simply wrappers around <code class="docutils literal notranslate"><span class="pre">syslog()</span></code>. The debugging
interfaces differ from the syslog interfaces in that:</p>
<blockquote>
<div><ul class="simple">
<li><p>They do not take a priority parameter; the priority is inherent
in the debug macro name.</p></li>
<li><p>They decorate the output stream with information such as the
file name</p></li>
<li><p>They can each be disabled via configuration options.</p></li>
</ul>
</div></blockquote>
<p>Each debug macro has a base name that represents the priority and
a prefix that represents the sub-system. Each macro is
individually initialized by both priority and sub-system. For
example, <code class="docutils literal notranslate"><span class="pre">uerr()</span></code> is the macro used for error level messages
from the USB subsystem and is enabled with
<code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_USB_ERROR</span></code>.</p>
<p>The base debug macro names, their priority, and configuration
variable are summarized below:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">info()</span></code>. The <code class="docutils literal notranslate"><span class="pre">info()</span></code> macro is the lowest priority
(<code class="docutils literal notranslate"><span class="pre">LOG_INFO</span></code>) and is intended to provide general information
about the flow of program execution so that you can get an
overview of the behavior of the program. <code class="docutils literal notranslate"><span class="pre">info()</span></code> is often
very chatty and voluminous and usually more information than
you may want to see. The <code class="docutils literal notranslate"><span class="pre">info()</span></code> macro is controlled via
CONFIG_DEBUG_subsystem_INFO</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">warn()</span></code>. The <code class="docutils literal notranslate"><span class="pre">warn()</span></code> macro has medium priority
(<code class="docutils literal notranslate"><span class="pre">LOG_WARN</span></code>) and is controlled by
<code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_subsystem_WARN</span></code>. The <code class="docutils literal notranslate"><span class="pre">warn()</span></code> is intended to
note exceptional or unexpected conditions that might be
potential errors or, perhaps, minor errors that easily
recovered.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">err()</span></code>. This is a high priority debug macro (<code class="docutils literal notranslate"><span class="pre">LOG_ERROR</span></code>)
and controlled by <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_subsystem_ERROR</span></code>. The
<code class="docutils literal notranslate"><span class="pre">err()</span></code> is reserved to indicate important error conditions.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">alert()</span></code>. The highest priority debug macro (<code class="docutils literal notranslate"><span class="pre">LOG_EMERG</span></code>)
and is controlled by <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_ALERT</span></code>. The <code class="docutils literal notranslate"><span class="pre">alert()</span></code>
macro is reserved for use solely by assertion and crash
handling logic. It also differs from the other macros in that
it cannot be enabled or disabled per subsystem.</p></li>
</ul>
</section>
</section>
<section id="syslog-channels">
<h2>SYSLOG Channels<a class="headerlink" href="#syslog-channels" title="Permalink to this heading"></a></h2>
<section id="syslog-channel-interfaces">
<h3>SYSLOG Channel Interfaces<a class="headerlink" href="#syslog-channel-interfaces" title="Permalink to this heading"></a></h3>
<p>In the NuttX SYSLOG implementation, the underlying device logic
the supports the SYSLOG output is referred to as a SYSLOG
<em>channel</em>. Each SYSLOG channel is represented by an interface
defined in <code class="docutils literal notranslate"><span class="pre">include/nuttx/syslog/syslog.h</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* This structure provides the interface to a SYSLOG device */</span>

<span class="k">typedef</span><span class="w"> </span><span class="n">CODE</span><span class="w"> </span><span class="nf">int</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">syslog_putc_t</span><span class="p">)(</span><span class="kt">int</span><span class="w"> </span><span class="n">ch</span><span class="p">);</span>
<span class="k">typedef</span><span class="w"> </span><span class="n">CODE</span><span class="w"> </span><span class="nf">int</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">syslog_flush_t</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>

<span class="k">struct</span><span class="w"> </span><span class="nc">syslog_channel_s</span>
<span class="p">{</span>
<span class="w">  </span><span class="cm">/* I/O redirection methods */</span>

<span class="w">  </span><span class="n">syslog_putc_t</span><span class="w"> </span><span class="n">sc_putc</span><span class="p">;</span><span class="w">    </span><span class="cm">/* Normal buffered output */</span>
<span class="w">  </span><span class="n">syslog_putc_t</span><span class="w"> </span><span class="n">sc_force</span><span class="p">;</span><span class="w">   </span><span class="cm">/* Low-level output for interrupt handlers */</span>
<span class="w">  </span><span class="n">syslog_flush_t</span><span class="w"> </span><span class="n">sc_flush</span><span class="p">;</span><span class="w">  </span><span class="cm">/* Flush buffered output (on crash) */</span>

<span class="w">  </span><span class="cm">/* Implementation specific logic may follow */</span>
<span class="p">};</span>
</pre></div>
</div>
<p>The channel interface is instantiated by calling
<a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a>.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.syslog_channel">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">syslog_channel</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">syslog_channel_s</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">channel</span></span><span class="sig-paren">)</span><span class="p"><span class="pre">;</span></span><a class="headerlink" href="#c.syslog_channel" title="Permalink to this definition"></a><br /></dt>
<dd><p>Configure the SYSLOG function to use the provided
channel to generate SYSLOG output.</p>
<p><code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code> is a non-standard, internal OS interface and
is not available to applications. It may be called numerous times
as necessary to change channel interfaces. By default, all system
log output goes to console (<code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>channel</strong> – Describes the interface to the channel to be used.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Zero (OK)is returned on success. A negated errno value is
returned on any failure.</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="syslog-channel-initialization">
<h3>SYSLOG Channel Initialization<a class="headerlink" href="#syslog-channel-initialization" title="Permalink to this heading"></a></h3>
<p>The initial, default SYSLOG channel is established with statically
initialized global variables so that some level of SYSLOG output
may be available immediately upon reset. This initialized data is
in the file <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_channel.c</span></code>. The initial
SYSLOG capability is determined by the selected SYSLOG channel:</p>
<ul class="simple">
<li><p><em>In-Memory Buffer (RAMLOG)</em>. Full SYSLOG capability as
available at reset.</p></li>
<li><p><em>Serial Console</em>. If the serial implementation provides the
low-level character output function <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code>, then that
low level serial output is available as soon as the serial
device has been configured.</p></li>
<li><p>For all other SYSLOG channels, all SYSLOG output goes to the
bit- bucket until the SYSLOG channel device has been
initialized.</p></li>
</ul>
<p>The syslog channel device is initialized when the bring-up logic
calls <a class="reference internal" href="#c.syslog_initialize" title="syslog_initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_initialize()</span></code></a>.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.syslog_initialize">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">syslog_initialize</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.syslog_initialize" title="Permalink to this definition"></a><br /></dt>
<dd><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;nuttx/syslog/syslog.h&gt;</span>
<span class="cp">#ifndef CONFIG_ARCH_SYSLOG</span>
<span class="kt">int</span><span class="w"> </span><span class="nf">syslog_initialize</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="cp">#else</span>
<span class="cp">#  define syslog_initialize()</span>
<span class="cp">#endif</span>
</pre></div>
</div>
<p>One power up, the SYSLOG facility is non-existent
or limited to very low-level output. This function is called later
in the initialization sequence after full driver support has been
initialized. It installs the configured SYSLOG drivers and enables
full SYSLOG capability.</p>
<p>This function performs these basic operations:</p>
<ul class="simple">
<li><p>Initialize the SYSLOG device</p></li>
<li><p>Call <a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a> to begin using that device.</p></li>
<li><p>If <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_SYSLOG</span></code> is selected, then the
architecture-specific logic will provide its own SYSLOG device
initialize which must include as a minimum a call to
<a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a> to use the device.</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Zero (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) is returned on success; a
negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value is returned on any failure.</p>
</dd>
</dl>
</dd></dl>

<p>Different types of SYSLOG devices have different OS initialization
requirements. Some are available immediately at reset, some are
available after some basic OS initialization, and some only after
OS is fully initialized.</p>
<p>There are other types of SYSLOG channel devices that may require
even further initialization. For example, the file SYSLOG channel
(described below) cannot be initialized until the necessary file
systems have been mounted.</p>
</section>
<section id="interrupt-level-syslog-output">
<h3>Interrupt Level SYSLOG Output<a class="headerlink" href="#interrupt-level-syslog-output" title="Permalink to this heading"></a></h3>
<p>As a general statement, SYSLOG output only supports <em>normal</em>
output from NuttX tasks. However, for debugging purposes, it is
also useful to get SYSLOG output from interrupt level logic. In an
embedded system, that is often where the most critical operations
are performed.</p>
<p>There are three conditions under which SYSLOG output generated
from interrupt level processing can a included the SYSLOG output
stream:</p>
<blockquote>
<div><ol class="arabic">
<li><p><strong>Low-Level Serial Output</strong>. If you are using a SYSLOG console
channel (<code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CONSOLE</span></code>) and if the underlying
architecture supports the low-level <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code>
interface(<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_LOWPUTC</span></code>), then the SYSLOG logic
will direct the output to <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> which is capable of
generating the serial output within the context of an interrupt
handler.</p>
<p>There are a few issues in doing this however:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is able to generate debug output in any
context because it disables serial interrupts and polls the
hardware directly. These polls may take many milliseconds
and during that time, all interrupts are disable within the
interrupt handler. This, of course, interferes with the
real-time behavior of the RTOS.</p></li>
<li><p>The output generated by <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is immediate and in
real-time. The normal SYSLOG output, on the other hand, is
buffered in the serial driver and may be delayed with
respect to the immediate output by many lines. Therefore,
the interrupt level SYSLOG output provided through
<code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is grossly out of synchronization with other
debug output</p></li>
</ul>
</li>
<li><p><strong>In-Memory Buffering</strong>. If the RAMLOG SYSLOG channel is
supported, then all SYSLOG output is buffered in memory.
Interrupt level SYSLOG output is no different than normal
SYSLOG output in this case.</p></li>
<li><p><strong>Serialization Buffer</strong>. A final option is the use of an
<em>interrupt buffer</em> to buffer the interrupt level SYSLOG output.
In this case:</p>
<ul class="simple">
<li><p>SYSLOG output generated from interrupt level process in not
sent to the SYSLOG channel immediately. Rather, it is
buffered in the interrupt serialization buffer.</p></li>
<li><p>Later, when the next normal syslog output is generated, it
will first empty the content of the interrupt buffer to the
SYSLOG device in the proper context. It will then be
followed by the normal syslog output. In this case, the
interrupt level SYSLOG output will interrupt the normal
output stream and the interrupt level SYSLOG output will be
inserted into the correct position in the SYSLOG output when
the next normal SYSLOG output is generated.</p></li>
</ul>
</li>
</ol>
</div></blockquote>
<p>The SYSLOG interrupt buffer is enabled with
<code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_INTBUFFER</span></code>. When the interrupt buffer is
enabled, you must also provide the size of the interrupt buffer
with <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_INTBUFSIZE</span></code>.</p>
</section>
</section>
<section id="syslog-channel-options">
<h2>SYSLOG Channel Options<a class="headerlink" href="#syslog-channel-options" title="Permalink to this heading"></a></h2>
<section id="syslog-console-device">
<h3>SYSLOG Console Device<a class="headerlink" href="#syslog-console-device" title="Permalink to this heading"></a></h3>
<p>The typical SYSLOG device is the system console. If you are using
a serial console, for example, then the SYSLOG output will appear
on that serial port.</p>
<p>This SYSLOG channel is automatically selected by
<code class="docutils literal notranslate"><span class="pre">syslog_initialize()</span></code> in the LATE initialization phase based on
configuration options. The configuration options that affect this
channel selection include:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_DEV_CONSOLE</span></code>. This setting indicates that the system
supports a console device, i.e., that the character device
<code class="docutils literal notranslate"><span class="pre">/dev/console</span></code> exists.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SERIAL_CONSOLE</span></code>. This configuration option is
automatically selected when a UART or USART is configured as
the system console. There is no user selection.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CONSOLE</span></code>. This configuration option is
manually selected from the SYSLOG menu. This is the option that
actually enables the SYSLOG console device. It depends on
<code class="docutils literal notranslate"><span class="pre">CONFIG_DEV_CONSOLE</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_LOWPUTC</span></code>. This is an indication from the
architecture configuration that the platform supports the
<code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> interface. <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is a very low level UART
interface that can even be used from interrupt handling.</p></li>
</ul>
</div></blockquote>
<p>Interrupt level SYSLOG output will be lost unless: (1) the
interrupt buffer is enabled to support serialization, or (2) a
serial console is used and <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is supported.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The console channel uses the fixed character device at
<code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>. The console channel is not synonymous with
<code class="docutils literal notranslate"><span class="pre">stdout</span></code> (or file descriptor 1). <code class="docutils literal notranslate"><span class="pre">stdout</span></code> is the current
output from a task when, say, <code class="docutils literal notranslate"><span class="pre">printf()</span></code> if used. Initially,
<code class="docutils literal notranslate"><span class="pre">stdout</span></code> does, indeed, use the <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code> device. However,
<code class="docutils literal notranslate"><span class="pre">stdout</span></code> may subsequently be redirected to some other device or
file. This is always the case, for example, when a transient
device is used for a console – such as a USB console or a Telnet
console. The SYSLOG channel is not redirected as <code class="docutils literal notranslate"><span class="pre">stdout</span></code> is;
the SYSLOG channel will stayed fixed (unless it is explicitly
changed via <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code>).</p>
</div>
<p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_consolechannel.c</span></code> and
<code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code></p>
</section>
<section id="syslog-character-device">
<h3>SYSLOG Character Device<a class="headerlink" href="#syslog-character-device" title="Permalink to this heading"></a></h3>
<p>The system console device, <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>, is a character driver
with some special properties. However, any character driver may be
used as the SYSLOG output channel. For example, suppose you have a
serial console on <code class="docutils literal notranslate"><span class="pre">/dev/ttyS0</span></code> and you want SYSLOG output on
<code class="docutils literal notranslate"><span class="pre">/dev/ttyS1</span></code>. Or suppose you support only a Telnet console but
want to capture debug output <code class="docutils literal notranslate"><span class="pre">/dev/ttyS0</span></code>.</p>
<p>This SYSLOG device channel is selected with <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR</span></code>
and has no other dependencies. Differences from the SYSLOG console
channel include:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_DEVPATH</span></code>. This configuration option string
must be set provide the full path to the character device to be
used.</p></li>
<li><p>The forced SYSLOG output always goes to the bit-bucket. This
means that interrupt level SYSLOG output will be lost unless
the interrupt buffer is enabled to support serialization.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR_CRLF</span></code>. If <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR_CRLF</span></code> is
selected, then linefeeds in the SYSLOG output will be expanded
to Carriage Return plus Linefeed. Since the character device is
not a console device, the addition of carriage returns to line
feeds would not be performed otherwise. You would probably want
this expansion if you use a serial terminal program with the
character device output.</p></li>
</ul>
</div></blockquote>
<p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_devchannel.c</span></code> and
<code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code></p>
</section>
<section id="syslog-file-device">
<h3>SYSLOG File Device<a class="headerlink" href="#syslog-file-device" title="Permalink to this heading"></a></h3>
<p>Files can also be used as the sink for SYSLOG output. There is,
however, a very fundamental difference in using a file as opposed
the system console, a RAM buffer, or character device: You must
first mount the file system that supports the SYSLOG file. That
difference means that the file SYSLOG channel cannot be supported
during the boot-up phase but can be instantiated later when board
level logic configures the application environment, including
mounting of the file systems.</p>
<p>The interface <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> is used to configure the
SYSLOG file channel:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.syslog_file_channel">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">syslog_file_channel</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">devpath</span></span><span class="sig-paren">)</span><span class="p"><span class="pre">;</span></span><a class="headerlink" href="#c.syslog_file_channel" title="Permalink to this definition"></a><br /></dt>
<dd><p>Configure to use a file in a mounted file system
at <code class="docutils literal notranslate"><span class="pre">devpath</span></code> as the SYSLOG channel.</p>
<p>This tiny function is simply a wrapper around
<code class="docutils literal notranslate"><span class="pre">syslog_dev_initialize()</span></code> and <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code>. It calls
<code class="docutils literal notranslate"><span class="pre">syslog_dev_initialize()</span></code> to configure the character file at
<code class="docutils literal notranslate"><span class="pre">devpath</span></code> then calls <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code> to use that device as
the SYSLOG output channel.</p>
<p>File SYSLOG channels differ from other SYSLOG channels in that
they cannot be established until after fully booting and mounting
the target file system. This function would need to be called from
board-specific bring-up logic AFTER mounting the file system
containing <code class="docutils literal notranslate"><span class="pre">devpath</span></code>.</p>
<p>SYSLOG data generated prior to calling <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code>
will, of course, not be included in the file.</p>
<p>NOTE interrupt level SYSLOG output will be lost in this case
unless the interrupt buffer is used.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>devpath</strong> – The full path to the file to be used for SYSLOG
output. This may be an existing file or not. If the file
exists, <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> will append new SYSLOG data
to the end of the file. If it does not, then
<code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> will create the file.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Zero (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) is returned on success; a
negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value is returned on any failure.</p>
</dd>
</dl>
<p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_filechannel.c</span></code>,
<code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code>, and
<code class="docutils literal notranslate"><span class="pre">include/nuttx/syslog/syslog.h</span></code>.</p>
</dd></dl>

</section>
<section id="syslog-ramlog-device">
<h3>SYSLOG RAMLOG Device<a class="headerlink" href="#syslog-ramlog-device" title="Permalink to this heading"></a></h3>
<p>The RAMLOG is a standalone feature that can be used to buffer any
character data in memory. There are, however, special
configurations that can be used to configure the RAMLOG as a
SYSLOG channel. The RAMLOG functionality is described in a more
general way in the following paragraphs.</p>
</section>
</section>
<section id="ram-logging-device">
<h2>RAM Logging Device<a class="headerlink" href="#ram-logging-device" title="Permalink to this heading"></a></h2>
<p>The RAM logging driver is a driver that was intended to support
debugging output (SYSLOG) when the normal serial output is not
available. For example, if you are using a Telnet or USB serial
console, the debug output will get lost – or worse. For example,
what if you want to debug the network over Telnet?
The RAM logging driver can also accept debug output data from
interrupt handler with no special serialization buffering. As an
added benefit, the RAM logging driver is much less invasive. Since
no actual I/O is performed with the debug output is generated, the
RAM logger tends to be much faster and will interfere much less
when used with time critical drivers.</p>
<p>The RAM logging driver is similar to a pipe in that it saves the
debugging output in a circular buffer in RAM. It differs from a
pipe in numerous details as needed to support logging.</p>
<p>This driver is built when <code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG</span></code> is defined in the
Nuttx configuration.</p>
<section id="dmesg-command">
<h3><code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command<a class="headerlink" href="#dmesg-command" title="Permalink to this heading"></a></h3>
<p>When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH)
command will appear: <code class="docutils literal notranslate"><span class="pre">dmesg</span></code>. The <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command will dump
the contents of the circular buffer to the console (and also clear
the circular buffer).</p>
</section>
<section id="ramlog-configuration-options">
<h3>RAMLOG Configuration options<a class="headerlink" href="#ramlog-configuration-options" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG</span></code>: Enables the RAM logging feature</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_SYSLOG</span></code>: Use the RAM logging device for the
SYSLOG interface. If this feature is enabled, then all debug
output will be re-directed to the circular buffer in RAM. This
RAM log can be viewed from NSH using the <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command.
NOTE: Unlike the limited, generic character driver SYSLOG
device, the RAMLOG <em>can</em> be used to capture debug output from
interrupt level handlers.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NPOLLWAITERS</span></code>: The number of threads than can
be waiting for this driver on <code class="docutils literal notranslate"><span class="pre">poll()</span></code>. Default: 4</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_BUFSIZE</span></code>: The size of the circular buffer to
use. Default: 1024 bytes.</p></li>
</ul>
<p>Other miscellaneous settings</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_CRLF</span></code>: Pre-pend a carriage return before every
linefeed that goes into the RAM log.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NONBLOCKING</span></code>: Reading from the RAMLOG will
never block if the RAMLOG is empty. If the RAMLOG is empty,
then zero is returned (usually interpreted as end-of-file). If
you do not define this, the NSH <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command will lock up
when called! So you probably do want this!</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NPOLLWAITERS</span></code>: The maximum number of threads
that may be waiting on the poll method.</p></li>
</ul>
</section>
</section>
</section>


           </div>
          </div>
          <footer>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020, The Apache Software Foundation.</p>
  </div>

   
</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>