mirror of
https://git.proxmox.com/git/systemd
synced 2026-01-07 00:42:24 +00:00
ba573a3afc
Instead of tracking git upstream directly, the upstream branch now contains the contents of the orig tarball available at http://www.freedesktop.org/software/systemd/
141 lines
13 KiB
HTML
141 lines
13 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_print</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
|
||
a.headerlink {
|
||
color: #c60f0f;
|
||
font-size: 0.8em;
|
||
padding: 0 4px 0 4px;
|
||
text-decoration: none;
|
||
visibility: hidden;
|
||
}
|
||
|
||
a.headerlink:hover {
|
||
background-color: #c60f0f;
|
||
color: white;
|
||
}
|
||
|
||
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
|
||
visibility: visible;
|
||
}
|
||
</style><a href="index.html">Index </a>·
|
||
<a href="systemd.directives.html">Directives </a>·
|
||
<a href="../python-systemd/index.html">Python </a>·
|
||
<a href="../libudev/index.html">libudev </a>·
|
||
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 204</span><hr><div class="refentry"><a name="sd_journal_print"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_print, sd_journal_printv, sd_journal_send, sd_journal_sendv, sd_journal_perror, SD_JOURNAL_SUPPRESS_LOCATION — Submit log entries to the journal</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-journal.h></pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_print</b>(</code></td><td>int <var class="pdparam">priority</var>, </td></tr><tr><td> </td><td>const char* <var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_printv</b>(</code></td><td>int <var class="pdparam">priority</var>, </td></tr><tr><td> </td><td>const char* <var class="pdparam">format</var>, </td></tr><tr><td> </td><td>va_list <var class="pdparam">ap</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_send</b>(</code></td><td>const char* <var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_sendv</b>(</code></td><td>const struct iovec *<var class="pdparam">iov</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">n</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_perror</b>(</code></td><td>const char* <var class="pdparam">message</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm259774278688"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_journal_print()</code> may be
|
||
used to submit simple, plain text log entries to the
|
||
system journal. The first argument is a priority
|
||
value. This is followed by a format string and its
|
||
parameters, similar to
|
||
<a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
|
||
or
|
||
<a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>. The
|
||
priority value is one of
|
||
<code class="literal">LOG_EMERG</code>,
|
||
<code class="literal">LOG_ALERT</code>,
|
||
<code class="literal">LOG_CRIT</code>,
|
||
<code class="literal">LOG_ERR</code>,
|
||
<code class="literal">LOG_WARNING</code>,
|
||
<code class="literal">LOG_NOTICE</code>,
|
||
<code class="literal">LOG_INFO</code>,
|
||
<code class="literal">LOG_DEBUG</code>, as defined in
|
||
<code class="filename">syslog.h</code>, see
|
||
<a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
|
||
for details. It is recommended to use this call to
|
||
submit log messages in the application locale or system
|
||
locale and in UTF-8 format, but no such restrictions
|
||
are enforced.</p><p><code class="function">sd_journal_printv()</code> is
|
||
similar to <code class="function">sd_journal_print()</code> but
|
||
takes a variable argument list encapsulated in an
|
||
object of type <code class="literal">va_list</code> (see
|
||
<a href="stdarg.html"><span class="citerefentry"><span class="refentrytitle">stdarg</span>(3)</span></a>
|
||
for more information) instead of the format string. It
|
||
is otherwise equivalent in behavior.</p><p><code class="function">sd_journal_send()</code> may be
|
||
used to submit structured log entries to the system
|
||
journal. It takes a series of format strings, each
|
||
immediately followed by their associated parameters,
|
||
terminated by NULL. The strings passed should be of
|
||
the format <code class="literal">VARIABLE=value</code>. The
|
||
variable name must be in uppercase and consist only of
|
||
characters, numbers and underscores, and may not begin
|
||
with an underscore. (All assignments that do not
|
||
follow this syntax will be ignored.) The value can be
|
||
of any size and format. It is highly recommended to
|
||
submit text strings formatted in the UTF-8 character
|
||
encoding only, and submit binary fields only when
|
||
formatting in UTf-8 strings is not sensible. A number
|
||
of well known fields are defined, see
|
||
<a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>
|
||
for details, but additional application defined fields
|
||
may be used. A variable may be assigned more than one
|
||
value per entry.</p><p><code class="function">sd_journal_sendv()</code> is
|
||
similar to <code class="function">sd_journal_send()</code> but
|
||
takes an array of <code class="literal">struct iovec</code> (as
|
||
defined in <code class="filename">uio.h</code>, see
|
||
<a href="readv.html"><span class="citerefentry"><span class="refentrytitle">readv</span>(3)</span></a>
|
||
for details) instead of the format string. Each
|
||
structure should reference one field of the entry to
|
||
submit. The second argument specifies the number of
|
||
structures in the
|
||
array. <code class="function">sd_journal_sendv()</code> is
|
||
particularly useful to submit binary objects to the
|
||
journal where that is necessary.</p><p><code class="function">sd_journal_perror()</code> is a
|
||
similar to
|
||
<a href="perror.html"><span class="citerefentry"><span class="refentrytitle">perror</span>(3)</span></a>
|
||
and writes a message to the journal that consists of
|
||
the passed string, suffixed with ": " and a human
|
||
readable representation of the current error code
|
||
stored in
|
||
<a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>. If
|
||
the message string is passed as NULL or empty string
|
||
only the error string representation will be written,
|
||
prefixed with nothing. An additional journal field
|
||
ERRNO= is included in the entry containing the numeric
|
||
error code formatted as decimal string. The log
|
||
priority used is <code class="literal">LOG_ERR</code> (3).</p><p>Note that <code class="function">sd_journal_send()</code>
|
||
is a wrapper around
|
||
<code class="function">sd_journal_sendv()</code> to make it
|
||
easier to use when only text strings shall be
|
||
submitted. Also, the following two calls are
|
||
mostly equivalent:</p><pre class="programlisting">sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
|
||
|
||
sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
|
||
"PRIORITY=%i", LOG_INFO,
|
||
NULL);</pre><p>Note that these calls implicitly add fields for
|
||
the source file, function name and code line where
|
||
invoked. This is implemented with macros. If this is
|
||
not desired it can be turned off by defining
|
||
SD_JOURNAL_SUPPRESS_LOCATION before including
|
||
<code class="filename">sd-journal.h</code>.</p><p><a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
|
||
and <code class="function">sd_journal_print()</code> may
|
||
largely be used interchangeably
|
||
functionality-wise. However, note that log messages
|
||
logged via the former take a different path to the
|
||
journal server than the later, and hence global
|
||
chronological ordering between the two streams cannot
|
||
be guaranteed. Using
|
||
<code class="function">sd_journal_print()</code> has the
|
||
benefit of logging source code line, file names, and
|
||
functions as meta data along all entries, and
|
||
guaranteeing chronological ordering with structured
|
||
log entries that are generated via
|
||
<code class="function">sd_journal_send()</code>. Using
|
||
<code class="function">syslog()</code> has the benefit of being
|
||
more portable.</p></div><div class="refsect1"><a name="idm259774235216"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>The four calls return 0 on success or a negative
|
||
errno-style error code. The
|
||
<a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>
|
||
variable itself is not altered.</p></div><div class="refsect1"><a name="idm259769322816"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>The <code class="function">sd_journal_print()</code>,
|
||
<code class="function">sd_journal_printv()</code>,
|
||
<code class="function">sd_journal_send()</code> and
|
||
<code class="function">sd_journal_sendv()</code> interfaces
|
||
are available as shared library, which can be compiled
|
||
and linked to with the
|
||
<code class="literal">libsystemd-journal</code>
|
||
<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
|
||
file.</p></div><div class="refsect1"><a name="idm259769317616"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
|
||
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
|
||
<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
|
||
<a href="sd_journal_stream_fd.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_stream_fd</span>(3)</span></a>,
|
||
<a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>,
|
||
<a href="perror.html"><span class="citerefentry"><span class="refentrytitle">perror</span>(3)</span></a>,
|
||
<a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>,
|
||
<a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>
|
||
</p></div></div></body></html>
|