man/sd_journal_print.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2012 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_journal_print">
  25
  26   <refentryinfo>
  27     <title>sd_journal_print</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_journal_print</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_journal_print</refname>
  47     <refname>sd_journal_printv</refname>
  48     <refname>sd_journal_send</refname>
  49     <refname>sd_journal_sendv</refname>
  50     <refname>sd_journal_perror</refname>
  51     <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname>
  52     <refpurpose>Submit log entries to the journal</refpurpose>
  53   </refnamediv>
  54
  55   <refsynopsisdiv>
  56     <funcsynopsis>
  57       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_journal_print</function></funcdef>
  61         <paramdef>int <parameter>priority</parameter></paramdef>
  62         <paramdef>const char *<parameter>format</parameter></paramdef>
  63         <paramdef>...</paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_journal_printv</function></funcdef>
  68         <paramdef>int <parameter>priority</parameter></paramdef>
  69         <paramdef>const char *<parameter>format</parameter></paramdef>
  70         <paramdef>va_list <parameter>ap</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>int <function>sd_journal_send</function></funcdef>
  75         <paramdef>const char *<parameter>format</parameter></paramdef>
  76         <paramdef>...</paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_journal_sendv</function></funcdef>
  81         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  82         <paramdef>int <parameter>n</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_journal_perror</function></funcdef>
  87         <paramdef>const char *<parameter>message</parameter></paramdef>
  88       </funcprototype>
  89
  90     </funcsynopsis>
  91   </refsynopsisdiv>
  92
  93   <refsect1>
  94     <title>Description</title>
  95
  96     <para><function>sd_journal_print()</function> may be used to
  97     submit simple, plain text log entries to the system journal. The
  98     first argument is a priority value. This is followed by a format
  99     string and its parameters, similar to
 100     <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 101     or
 102     <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 103     The priority value is one of
 104     <constant>LOG_EMERG</constant>,
 105     <constant>LOG_ALERT</constant>,
 106     <constant>LOG_CRIT</constant>,
 107     <constant>LOG_ERR</constant>,
 108     <constant>LOG_WARNING</constant>,
 109     <constant>LOG_NOTICE</constant>,
 110     <constant>LOG_INFO</constant>,
 111     <constant>LOG_DEBUG</constant>, as defined in
 112     <filename>syslog.h</filename>, see
 113     <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114     for details. It is recommended to use this call to submit log
 115     messages in the application locale or system locale and in UTF-8
 116     format, but no such restrictions are enforced.</para>
 117
 118     <para><function>sd_journal_printv()</function> is similar to
 119     <function>sd_journal_print()</function> but takes a variable
 120     argument list encapsulated in an object of type
 121     <varname>va_list</varname> (see
 122     <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 123     for more information) instead of the format string. It is
 124     otherwise equivalent in behavior.</para>
 125
 126     <para><function>sd_journal_send()</function> may be used to submit
 127     structured log entries to the system journal. It takes a series of
 128     format strings, each immediately followed by their associated
 129     parameters, terminated by <constant>NULL</constant>. The strings
 130     passed should be of the format <literal>VARIABLE=value</literal>.
 131     The variable name must be in uppercase and consist only of
 132     characters, numbers and underscores, and may not begin with an
 133     underscore. (All assignments that do not follow this syntax will
 134     be ignored.) The value can be of any size and format. It is highly
 135     recommended to submit text strings formatted in the UTF-8
 136     character encoding only, and submit binary fields only when
 137     formatting in UTF-8 strings is not sensible. A number of well
 138     known fields are defined, see
 139     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 140     for details, but additional application defined fields may be
 141     used. A variable may be assigned more than one value per
 142     entry.</para>
 143
 144     <para><function>sd_journal_sendv()</function> is similar to
 145     <function>sd_journal_send()</function> but takes an array of
 146     <varname>struct iovec</varname> (as defined in
 147     <filename>uio.h</filename>, see
 148     <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149     for details) instead of the format string. Each structure should
 150     reference one field of the entry to submit. The second argument
 151     specifies the number of structures in the array.
 152     <function>sd_journal_sendv()</function> is particularly useful to
 153     submit binary objects to the journal where that is
 154     necessary.</para>
 155
 156     <para><function>sd_journal_perror()</function> is a similar to
 157     <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 158     and writes a message to the journal that consists of the passed
 159     string, suffixed with ": " and a human readable representation of
 160     the current error code stored in
 161     <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 162     If the message string is passed as <constant>NULL</constant> or
 163     empty string, only the error string representation will be
 164     written, prefixed with nothing. An additional journal field ERRNO=
 165     is included in the entry containing the numeric error code
 166     formatted as decimal string. The log priority used is
 167     <constant>LOG_ERR</constant> (3).</para>
 168
 169     <para>Note that <function>sd_journal_send()</function> is a
 170     wrapper around <function>sd_journal_sendv()</function> to make it
 171     easier to use when only text strings shall be submitted. Also, the
 172     following two calls are mostly equivalent:</para>
 173
 174     <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
 175
 176 sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
 177     "PRIORITY=%i", LOG_INFO,
 178     NULL);</programlisting>
 179
 180     <para>Note that these calls implicitly add fields for the source
 181     file, function name and code line where invoked. This is
 182     implemented with macros. If this is not desired, it can be turned
 183     off by defining SD_JOURNAL_SUPPRESS_LOCATION before including
 184     <filename>sd-journal.h</filename>.</para>
 185
 186     <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 187     and <function>sd_journal_print()</function> may
 188     largely be used interchangeably
 189     functionality-wise. However, note that log messages
 190     logged via the former take a different path to the
 191     journal server than the later, and hence global
 192     chronological ordering between the two streams cannot
 193     be guaranteed. Using
 194     <function>sd_journal_print()</function> has the
 195     benefit of logging source code line, filenames, and
 196     functions as metadata along all entries, and
 197     guaranteeing chronological ordering with structured
 198     log entries that are generated via
 199     <function>sd_journal_send()</function>. Using
 200     <function>syslog()</function> has the benefit of being
 201     more portable.</para>
 202   </refsect1>
 203
 204   <refsect1>
 205     <title>Return Value</title>
 206
 207     <para>The four calls return 0 on success or a negative errno-style
 208     error code. The
 209     <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 210     variable itself is not altered.</para>
 211
 212     <para>If
 213     <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 214     is not running (the socket is not present), those functions do
 215     nothing, and also return 0.</para>
 216   </refsect1>
 217
 218   <refsect1>
 219     <title>Async signal safety</title>
 220     <para><function>sd_journal_sendv()</function> is "async signal
 221     safe" in the meaning of
 222     <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 223     </para>
 224
 225     <para><function>sd_journal_print</function>,
 226     <function>sd_journal_printv</function>,
 227     <function>sd_journal_send</function>, and
 228     <function>sd_journal_perror</function> are
 229     not async signal safe.</para>
 230   </refsect1>
 231
 232   <refsect1>
 233     <title>Notes</title>
 234
 235     <para>The <function>sd_journal_print()</function>,
 236     <function>sd_journal_printv()</function>,
 237     <function>sd_journal_send()</function> and
 238     <function>sd_journal_sendv()</function> interfaces are available
 239     as a shared library, which can be compiled and linked to with the
 240     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 241     file.</para>
 242   </refsect1>
 243
 244   <refsect1>
 245     <title>See Also</title>
 246
 247     <para>
 248       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 249       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 250       <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 251       <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 252       <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 253       <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 257     </para>
 258   </refsect1>
 259
 260 </refentry>