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
  97                 used to submit simple, plain text log entries to the
  98                 system journal. The first argument is a priority
  99                 value. This is followed by a format string and its
 100                 parameters, similar to
 101                 <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102                 or
 103                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
 104                 priority value is one of
 105                 <literal>LOG_EMERG</literal>,
 106                 <literal>LOG_ALERT</literal>,
 107                 <literal>LOG_CRIT</literal>,
 108                 <literal>LOG_ERR</literal>,
 109                 <literal>LOG_WARNING</literal>,
 110                 <literal>LOG_NOTICE</literal>,
 111                 <literal>LOG_INFO</literal>,
 112                 <literal>LOG_DEBUG</literal>, as defined in
 113                 <filename>syslog.h</filename>, see
 114                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 115                 for details. It is recommended to use this call to
 116                 submit log messages in the application locale or system
 117                 locale and in UTF-8 format, but no such restrictions
 118                 are enforced.</para>
 119
 120                 <para><function>sd_journal_printv()</function> is
 121                 similar to <function>sd_journal_print()</function> but
 122                 takes a variable argument list encapsulated in an
 123                 object of type <literal>va_list</literal> (see
 124                 <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 125                 for more information) instead of the format string. It
 126                 is otherwise equivalent in behaviour.</para>
 127
 128                 <para><function>sd_journal_send()</function> may be
 129                 used to submit structured log entries to the system
 130                 journal. It takes a series of format strings, each
 131                 immediately followed by their associated parameters,
 132                 terminated by NULL. The strings passed should be of
 133                 the format <literal>VARIABLE=value</literal>. The
 134                 variable name must be in uppercase and consist only
 135                 of characters, numbers and underscores, and may not
 136                 begin with an underscore. The value can be of any size
 137                 and format. It is highly recommended to submit
 138                 text strings formatted in the UTF-8 character encoding
 139                 only, and submit binary fields only when formatting in
 140                 UTf-8 strings is not sensible. A number of well known
 141                 fields are defined, see
 142                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 143                 for details, but additional application defined fields
 144                 may be used.</para>
 145
 146                 <para><function>sd_journal_sendv()</function> is
 147                 similar to <function>sd_journal_send()</function> but
 148                 takes an array of <literal>struct iovec</literal> (as
 149                 defined in <filename>uio.h</filename>, see
 150                 <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 151                 for details) instead of the format string. Each
 152                 structure should reference one field of the entry to
 153                 submit. The second argument specifies the number of
 154                 structures in the
 155                 array. <function>sd_journal_sendv()</function> is
 156                 particularly useful to submit binary objects to the
 157                 journal where that is necessary.</para>
 158
 159                 <para><function>sd_journal_perror()</function> is a
 160                 similar to
 161                 <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 162                 and writes a message to the journal that consists of
 163                 the passed string, suffixed with ": " and a human
 164                 readable representation of the current error code
 165                 stored in
 166                 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
 167                 the message string is passed as NULL or empty string
 168                 only the error string representation will be written,
 169                 prefixed with nothing. An additional journal field
 170                 ERRNO= is included in the entry containing the numeric
 171                 error code formatted as decimal string. The log
 172                 priority used is <literal>LOG_ERR</literal> (3).</para>
 173
 174                 <para>Note that <function>sd_journal_send()</function>
 175                 is a wrapper around
 176                 <function>sd_journal_sendv()</function> to make it
 177                 easier to use when only text strings shall be
 178                 submitted. Also, the following two calls are
 179                 mostly equivalent:</para>
 180
 181                 <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
 182
 183 sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
 184                 "PRIORITY=%i", LOG_INFO,
 185                 NULL);</programlisting>
 186
 187                 <para>Note that these calls implicitly add fields for
 188                 the source file, function name and code line where
 189                 invoked. This is implemented with macros. If this is
 190                 not desired it can be turned off by defining
 191                 SD_JOURNAL_SUPPRESS_LOCATION before including
 192                 <filename>sd-journal.h</filename>.</para>
 193
 194                 <para><citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 195                 and and <function>sd_journal_print()</function> may
 196                 largely be used interchangeably
 197                 functionality-wise. However, note that log messages
 198                 logged via the former take a different path to the
 199                 journal server than the later, and hence global
 200                 chronological ordering between the two streams cannot
 201                 be guaranteed. Using
 202                 <function>sd_journal_print()</function> has the
 203                 benefit of logging source code line, file names, and
 204                 functions as meta data along all entries, and
 205                 guaranteeing chronological ordering with structured
 206                 log entries that are generated via
 207                 <function>sd_journal_send()</function>. Using
 208                 <function>syslog()</function> has the benefit of being
 209                 more portable.</para>
 210         </refsect1>
 211
 212         <refsect1>
 213                 <title>Return Value</title>
 214
 215                 <para>The four calls return 0 on success or a negative
 216                 errno-style error code. The
 217                 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 218                 variable itself is not altered.</para>
 219         </refsect1>
 220
 221         <refsect1>
 222                 <title>Notes</title>
 223
 224                 <para>The <function>sd_journal_print()</function>,
 225                 <function>sd_journal_printv()</function>,
 226                 <function>sd_journal_send()</function> and
 227                 <function>sd_journal_sendv()</function> interfaces
 228                 are available as shared library, which can be compiled
 229                 and linked to with the
 230                 <literal>libsystemd-journal</literal>
 231                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 232                 file.</para>
 233         </refsect1>
 234
 235         <refsect1>
 236                 <title>See Also</title>
 237
 238                 <para>
 239                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 240                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 241                         <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 242                         <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 243                         <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 244                         <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 245                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 246                 </para>
 247         </refsect1>
 248
 249 </refentry>