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 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102                 or
 103                 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
 104                 priority value is one of
 105                 <constant>LOG_EMERG</constant>,
 106                 <constant>LOG_ALERT</constant>,
 107                 <constant>LOG_CRIT</constant>,
 108                 <constant>LOG_ERR</constant>,
 109                 <constant>LOG_WARNING</constant>,
 110                 <constant>LOG_NOTICE</constant>,
 111                 <constant>LOG_INFO</constant>,
 112                 <constant>LOG_DEBUG</constant>, as defined in
 113                 <filename>syslog.h</filename>, see
 114                 <citerefentry project='man-pages'><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 <varname>va_list</varname> (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 behavior.</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 <constant>NULL</constant>. The strings passed should be of
 133                 the format <literal>VARIABLE=value</literal>. The
 134                 variable name must be in uppercase and consist only of
 135                 characters, numbers and underscores, and may not begin
 136                 with an underscore. (All assignments that do not
 137                 follow this syntax will be ignored.) The value can be
 138                 of any size and format. It is highly recommended to
 139                 submit text strings formatted in the UTF-8 character
 140                 encoding only, and submit binary fields only when
 141                 formatting in UTF-8 strings is not sensible. A number
 142                 of well known fields are defined, see
 143                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 144                 for details, but additional application defined fields
 145                 may be used. A variable may be assigned more than one
 146                 value per entry.</para>
 147
 148                 <para><function>sd_journal_sendv()</function> is
 149                 similar to <function>sd_journal_send()</function> but
 150                 takes an array of <varname>struct iovec</varname> (as
 151                 defined in <filename>uio.h</filename>, see
 152                 <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 153                 for details) instead of the format string. Each
 154                 structure should reference one field of the entry to
 155                 submit. The second argument specifies the number of
 156                 structures in the array.
 157                 <function>sd_journal_sendv()</function> is
 158                 particularly useful to submit binary objects to the
 159                 journal where that is necessary.</para>
 160
 161                 <para><function>sd_journal_perror()</function> is a
 162                 similar to
 163                 <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 164                 and writes a message to the journal that consists of
 165                 the passed string, suffixed with ": " and a human
 166                 readable representation of the current error code
 167                 stored in
 168                 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
 169                 the message string is passed as <constant>NULL</constant> or empty string,
 170                 only the error string representation will be written,
 171                 prefixed with nothing. An additional journal field
 172                 ERRNO= is included in the entry containing the numeric
 173                 error code formatted as decimal string. The log
 174                 priority used is <constant>LOG_ERR</constant> (3).</para>
 175
 176                 <para>Note that <function>sd_journal_send()</function>
 177                 is a wrapper around
 178                 <function>sd_journal_sendv()</function> to make it
 179                 easier to use when only text strings shall be
 180                 submitted. Also, the following two calls are
 181                 mostly equivalent:</para>
 182
 183                 <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
 184
 185 sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
 186                 "PRIORITY=%i", LOG_INFO,
 187                 NULL);</programlisting>
 188
 189                 <para>Note that these calls implicitly add fields for
 190                 the source file, function name and code line where
 191                 invoked. This is implemented with macros. If this is
 192                 not desired, it can be turned off by defining
 193                 SD_JOURNAL_SUPPRESS_LOCATION before including
 194                 <filename>sd-journal.h</filename>.</para>
 195
 196                 <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 197                 and <function>sd_journal_print()</function> may
 198                 largely be used interchangeably
 199                 functionality-wise. However, note that log messages
 200                 logged via the former take a different path to the
 201                 journal server than the later, and hence global
 202                 chronological ordering between the two streams cannot
 203                 be guaranteed. Using
 204                 <function>sd_journal_print()</function> has the
 205                 benefit of logging source code line, filenames, and
 206                 functions as metadata along all entries, and
 207                 guaranteeing chronological ordering with structured
 208                 log entries that are generated via
 209                 <function>sd_journal_send()</function>. Using
 210                 <function>syslog()</function> has the benefit of being
 211                 more portable.</para>
 212         </refsect1>
 213
 214         <refsect1>
 215                 <title>Return Value</title>
 216
 217                 <para>The four calls return 0 on success or a negative
 218                 errno-style error code. The
 219                 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 220                 variable itself is not altered.</para>
 221
 222                 <para>If
 223                 <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 224                 is not running (the socket is not present), those
 225                 functions do nothing, and also return 0.</para>
 226         </refsect1>
 227
 228         <refsect1>
 229                 <title>Async signal safety</title>
 230                 <para><function>sd_journal_sendv()</function> is "async signal
 231                 safe" in the meaning of <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 232                 </para>
 233
 234                 <para><function>sd_journal_print</function>,
 235                 <function>sd_journal_printv</function>,
 236                 <function>sd_journal_send</function>, and
 237                 <function>sd_journal_perror</function> are
 238                 not async signal safe.</para>
 239         </refsect1>
 240
 241         <refsect1>
 242                 <title>Notes</title>
 243
 244                 <para>The <function>sd_journal_print()</function>,
 245                 <function>sd_journal_printv()</function>,
 246                 <function>sd_journal_send()</function> and
 247                 <function>sd_journal_sendv()</function> interfaces
 248                 are available as a shared library, which can be compiled
 249                 and linked to with the
 250                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 251                 file.</para>
 252         </refsect1>
 253
 254         <refsect1>
 255                 <title>See Also</title>
 256
 257                 <para>
 258                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 259                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 260                         <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 261                         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 262                         <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 263                         <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 264                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 265                         <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 266                         <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 267                 </para>
 268         </refsect1>
 269
 270 </refentry>