~ubuntu-branches/ubuntu/trusty/systemd/trusty

<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.77.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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 202</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="idp27120"></a><h2>Description</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>

<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

100

guaranteeing chronological ordering with structured

101

log entries that are generated via

102

<code class="function">sd_journal_send()</code>. Using

103

<code class="function">syslog()</code> has the benefit of being

104

more portable.</p></div><div class="refsect1"><a name="idp70144"></a><h2>Return Value</h2><p>The four calls return 0 on success or a negative

105

errno-style error code. The

106

<a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>

107

variable itself is not altered.</p></div><div class="refsect1"><a name="idp5036240"></a><h2>Notes</h2><p>The <code class="function">sd_journal_print()</code>,

108

<code class="function">sd_journal_printv()</code>,

109

<code class="function">sd_journal_send()</code> and

110

<code class="function">sd_journal_sendv()</code> interfaces

111

are available as shared library, which can be compiled

112

and linked to with the

113

<code class="literal">libsystemd-journal</code>

114

<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>

115

file.</p></div><div class="refsect1"><a name="idp5041440"></a><h2>See Also</h2><p>

116

<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,

117

<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,

118

<a href="sd_journal_stream_fd.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_stream_fd</span>(3)</span></a>,

119

<a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>,

120

<a href="perror.html"><span class="citerefentry"><span class="refentrytitle">perror</span>(3)</span></a>,

121

<a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>,

122

<a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>

123

</p></div></div></body></html>

Older »