man/sd_journal_print.html

   1 <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>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 214</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 &lt;systemd/sd-journal.h&gt;</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="idm214171911712"></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
  23                 used to submit simple, plain text log entries to the
  24                 system journal. The first argument is a priority
  25                 value. This is followed by a format string and its
  26                 parameters, similar to
  27                 <a href="printf.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
  28                 or
  29                 <a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>. The
  30                 priority value is one of
  31                 <code class="constant">LOG_EMERG</code>,
  32                 <code class="constant">LOG_ALERT</code>,
  33                 <code class="constant">LOG_CRIT</code>,
  34                 <code class="constant">LOG_ERR</code>,
  35                 <code class="constant">LOG_WARNING</code>,
  36                 <code class="constant">LOG_NOTICE</code>,
  37                 <code class="constant">LOG_INFO</code>,
  38                 <code class="constant">LOG_DEBUG</code>, as defined in
  39                 <code class="filename">syslog.h</code>, see
  40                 <a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
  41                 for details. It is recommended to use this call to
  42                 submit log messages in the application locale or system
  43                 locale and in UTF-8 format, but no such restrictions
  44                 are enforced.</p><p><code class="function">sd_journal_printv()</code> is
  45                 similar to <code class="function">sd_journal_print()</code> but
  46                 takes a variable argument list encapsulated in an
  47                 object of type <code class="varname">va_list</code> (see
  48                 <a href="stdarg.html"><span class="citerefentry"><span class="refentrytitle">stdarg</span>(3)</span></a>
  49                 for more information) instead of the format string. It
  50                 is otherwise equivalent in behavior.</p><p><code class="function">sd_journal_send()</code> may be
  51                 used to submit structured log entries to the system
  52                 journal. It takes a series of format strings, each
  53                 immediately followed by their associated parameters,
  54                 terminated by <code class="constant">NULL</code>. The strings passed should be of
  55                 the format "<code class="literal">VARIABLE=value</code>". The
  56                 variable name must be in uppercase and consist only of
  57                 characters, numbers and underscores, and may not begin
  58                 with an underscore. (All assignments that do not
  59                 follow this syntax will be ignored.) The value can be
  60                 of any size and format. It is highly recommended to
  61                 submit text strings formatted in the UTF-8 character
  62                 encoding only, and submit binary fields only when
  63                 formatting in UTF-8 strings is not sensible. A number
  64                 of well known fields are defined, see
  65                 <a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>
  66                 for details, but additional application defined fields
  67                 may be used. A variable may be assigned more than one
  68                 value per entry.</p><p><code class="function">sd_journal_sendv()</code> is
  69                 similar to <code class="function">sd_journal_send()</code> but
  70                 takes an array of <code class="varname">struct iovec</code> (as
  71                 defined in <code class="filename">uio.h</code>, see
  72                 <a href="readv.html"><span class="citerefentry"><span class="refentrytitle">readv</span>(3)</span></a>
  73                 for details) instead of the format string. Each
  74                 structure should reference one field of the entry to
  75                 submit. The second argument specifies the number of
  76                 structures in the array.
  77                 <code class="function">sd_journal_sendv()</code> is
  78                 particularly useful to submit binary objects to the
  79                 journal where that is necessary.</p><p><code class="function">sd_journal_perror()</code> is a
  80                 similar to
  81                 <a href="perror.html"><span class="citerefentry"><span class="refentrytitle">perror</span>(3)</span></a>
  82                 and writes a message to the journal that consists of
  83                 the passed string, suffixed with ": " and a human
  84                 readable representation of the current error code
  85                 stored in
  86                 <a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>. If
  87                 the message string is passed as <code class="constant">NULL</code> or empty string,
  88                 only the error string representation will be written,
  89                 prefixed with nothing. An additional journal field
  90                 ERRNO= is included in the entry containing the numeric
  91                 error code formatted as decimal string. The log
  92                 priority used is <code class="constant">LOG_ERR</code> (3).</p><p>Note that <code class="function">sd_journal_send()</code>
  93                 is a wrapper around
  94                 <code class="function">sd_journal_sendv()</code> to make it
  95                 easier to use when only text strings shall be
  96                 submitted. Also, the following two calls are
  97                 mostly equivalent:</p><pre class="programlisting">sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
  98
  99 sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
 100                 "PRIORITY=%i", LOG_INFO,
 101                 NULL);</pre><p>Note that these calls implicitly add fields for
 102                 the source file, function name and code line where
 103                 invoked. This is implemented with macros. If this is
 104                 not desired, it can be turned off by defining
 105                 SD_JOURNAL_SUPPRESS_LOCATION before including
 106                 <code class="filename">sd-journal.h</code>.</p><p><a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
 107                 and <code class="function">sd_journal_print()</code> may
 108                 largely be used interchangeably
 109                 functionality-wise. However, note that log messages
 110                 logged via the former take a different path to the
 111                 journal server than the later, and hence global
 112                 chronological ordering between the two streams cannot
 113                 be guaranteed. Using
 114                 <code class="function">sd_journal_print()</code> has the
 115                 benefit of logging source code line, filenames, and
 116                 functions as metadata along all entries, and
 117                 guaranteeing chronological ordering with structured
 118                 log entries that are generated via
 119                 <code class="function">sd_journal_send()</code>. Using
 120                 <code class="function">syslog()</code> has the benefit of being
 121                 more portable.</p></div><div class="refsect1"><a name="idm214171870448"></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
 122                 errno-style error code. The
 123                 <a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>
 124                 variable itself is not altered.</p><p>If
 125                 <a href="systemd-journald.html"><span class="citerefentry"><span class="refentrytitle">systemd-journald</span>(8)</span></a>
 126                 is not running (the socket is not present), those
 127                 functions do nothing, and also return 0.</p></div><div class="refsect1"><a name="idm214166952576"></a><h2 id="Async signal safety">Async signal safety<a class="headerlink" title="Permalink to this headline" href="#Async%20signal%20safety">¶</a></h2><p><code class="function">sd_journal_sendv()</code> is "async signal
 128                 safe" in the meaning of <a href="signal.html"><span class="citerefentry"><span class="refentrytitle">signal</span>(7)</span></a>.
 129                 </p><p><code class="function">sd_journal_print</code>,
 130                 <code class="function">sd_journal_printv</code>,
 131                 <code class="function">sd_journal_send</code>, and
 132                 <code class="function">sd_journal_perror</code> are
 133                 not async signal safe.</p></div><div class="refsect1"><a name="idm214166947408"></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>,
 134                 <code class="function">sd_journal_printv()</code>,
 135                 <code class="function">sd_journal_send()</code> and
 136                 <code class="function">sd_journal_sendv()</code> interfaces
 137                 are available as a shared library, which can be compiled
 138                 and linked to with the
 139                 <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
 140                 file.</p></div><div class="refsect1"><a name="idm214166942448"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 141                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 142                         <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
 143                         <a href="sd_journal_stream_fd.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_stream_fd</span>(3)</span></a>,
 144                         <a href="syslog.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>,
 145                         <a href="perror.html"><span class="citerefentry"><span class="refentrytitle">perror</span>(3)</span></a>,
 146                         <a href="errno.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>,
 147                         <a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>,
 148                         <a href="signal.html"><span class="citerefentry"><span class="refentrytitle">signal</span>(7)</span></a>,
 149                         <a href="socket.html"><span class="citerefentry"><span class="refentrytitle">socket</span>(7)</span></a>
 150                 </p></div></div></body></html>