1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_journal_print" xmlns:xi="http://www.w3.org/2001/XInclude">
7
8  <refentryinfo>
9    <title>sd_journal_print</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>sd_journal_print</refentrytitle>
15    <manvolnum>3</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>sd_journal_print</refname>
20    <refname>sd_journal_printv</refname>
21    <refname>sd_journal_send</refname>
22    <refname>sd_journal_sendv</refname>
23    <refname>sd_journal_perror</refname>
24    <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname>
25    <refname>sd_journal_print_with_location</refname>
26    <refname>sd_journal_printv_with_location</refname>
27    <refname>sd_journal_send_with_location</refname>
28    <refname>sd_journal_sendv_with_location</refname>
29    <refname>sd_journal_perror_with_location</refname>
30
31    <refpurpose>Submit log entries to the journal</refpurpose>
32  </refnamediv>
33
34  <refsynopsisdiv>
35    <funcsynopsis>
36      <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
37
38      <funcprototype>
39        <funcdef>int <function>sd_journal_print</function></funcdef>
40        <paramdef>int <parameter>priority</parameter></paramdef>
41        <paramdef>const char *<parameter>format</parameter></paramdef>
42        <paramdef>…</paramdef>
43      </funcprototype>
44
45      <funcprototype>
46        <funcdef>int <function>sd_journal_printv</function></funcdef>
47        <paramdef>int <parameter>priority</parameter></paramdef>
48        <paramdef>const char *<parameter>format</parameter></paramdef>
49        <paramdef>va_list <parameter>ap</parameter></paramdef>
50      </funcprototype>
51
52      <funcprototype>
53        <funcdef>int <function>sd_journal_send</function></funcdef>
54        <paramdef>const char *<parameter>format</parameter></paramdef>
55        <paramdef>…</paramdef>
56      </funcprototype>
57
58      <funcprototype>
59        <funcdef>int <function>sd_journal_sendv</function></funcdef>
60        <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
61        <paramdef>int <parameter>n</parameter></paramdef>
62      </funcprototype>
63
64      <funcprototype>
65        <funcdef>int <function>sd_journal_perror</function></funcdef>
66        <paramdef>const char *<parameter>message</parameter></paramdef>
67      </funcprototype>
68
69      <funcprototype>
70        <funcdef>int <function>sd_journal_print_with_location</function></funcdef>
71        <paramdef>int <parameter>priority</parameter></paramdef>
72        <paramdef>const char *<parameter>file</parameter></paramdef>
73        <paramdef>const char *<parameter>line</parameter></paramdef>
74        <paramdef>const char *<parameter>func</parameter></paramdef>
75        <paramdef>const char *<parameter>format</parameter></paramdef>
76        <paramdef>…</paramdef>
77      </funcprototype>
78
79      <funcprototype>
80        <funcdef>int <function>sd_journal_printv_with_location</function></funcdef>
81        <paramdef>int <parameter>priority</parameter></paramdef>
82        <paramdef>const char *<parameter>file</parameter></paramdef>
83        <paramdef>const char *<parameter>line</parameter></paramdef>
84        <paramdef>const char *<parameter>func</parameter></paramdef>
85        <paramdef>const char *<parameter>format</parameter></paramdef>
86        <paramdef>va_list <parameter>ap</parameter></paramdef>
87      </funcprototype>
88
89      <funcprototype>
90        <funcdef>int <function>sd_journal_send_with_location</function></funcdef>
91        <paramdef>const char *<parameter>file</parameter></paramdef>
92        <paramdef>const char *<parameter>line</parameter></paramdef>
93        <paramdef>const char *<parameter>func</parameter></paramdef>
94        <paramdef>const char *<parameter>format</parameter></paramdef>
95        <paramdef>…</paramdef>
96      </funcprototype>
97
98      <funcprototype>
99        <funcdef>int <function>sd_journal_sendv_with_location</function></funcdef>
100        <paramdef>const char *<parameter>file</parameter></paramdef>
101        <paramdef>const char *<parameter>line</parameter></paramdef>
102        <paramdef>const char *<parameter>func</parameter></paramdef>
103        <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
104        <paramdef>int <parameter>n</parameter></paramdef>
105      </funcprototype>
106
107      <funcprototype>
108        <funcdef>int <function>sd_journal_perror_with_location</function></funcdef>
109        <paramdef>const char *<parameter>file</parameter></paramdef>
110        <paramdef>const char *<parameter>line</parameter></paramdef>
111        <paramdef>const char *<parameter>func</parameter></paramdef>
112        <paramdef>const char *<parameter>message</parameter></paramdef>
113      </funcprototype>
114    </funcsynopsis>
115  </refsynopsisdiv>
116
117  <refsect1>
118    <title>Description</title>
119
120    <para><function>sd_journal_print()</function> may be used to submit simple, plain text log entries to the system
121    journal. The first argument is a priority value. This is followed by a format string and its parameters, similar to
122    <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
123    <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
124    Note that currently the resulting message will be truncated to <constant>LINE_MAX - 8</constant>.
125    The priority value is one of <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>,
126    <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>, <constant>LOG_WARNING</constant>,
127    <constant>LOG_NOTICE</constant>, <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as defined in
128    <filename>syslog.h</filename>, see <citerefentry
129    project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details. It is
130    recommended to use this call to submit log messages in the application locale or system locale and in UTF-8 format,
131    but no such restrictions are enforced. Note that log messages written using this function are generally not
132    expected to end in a new-line character. However, as all trailing whitespace (including spaces, new-lines,
133    tabulators and carriage returns) are automatically stripped from the logged string, it is acceptable to specify one
134    (or more). Empty lines (after trailing whitespace removal) are suppressed. On non-empty lines, leading whitespace
135    (as well as inner whitespace) is left unmodified. </para>
136
137    <para><function>sd_journal_printv()</function> is similar to
138    <function>sd_journal_print()</function> but takes a variable
139    argument list encapsulated in an object of type
140    <varname>va_list</varname> (see
141    <citerefentry project='man-pages'><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
142    for more information) instead of the format string. It is
143    otherwise equivalent in behavior.</para>
144
145    <para><function>sd_journal_send()</function> may be used to submit structured log entries to the system journal. It
146    takes a series of format strings, each immediately followed by their associated parameters, terminated by
147    <constant>NULL</constant>. The strings passed should be of the format <literal>VARIABLE=value</literal>.  The
148    variable name must be in uppercase and consist only of characters, numbers and underscores, and may not begin with
149    an underscore. (All assignments that do not follow this syntax will be ignored.) The value can be of any size and
150    format. It is highly recommended to submit text strings formatted in the UTF-8 character encoding only, and submit
151    binary fields only when formatting in UTF-8 strings is not sensible. A number of well-known fields are defined, see
152    <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
153    details, but additional application defined fields may be used. A variable may be assigned more than one value per
154    entry. If this function is used, trailing whitespace is automatically removed from each formatted field.</para>
155
156    <para><function>sd_journal_sendv()</function> is similar to <function>sd_journal_send()</function> but takes an
157    array of <varname>struct iovec</varname> (as defined in <filename>uio.h</filename>, see <citerefentry
158    project='man-pages'><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details)
159    instead of the format string. Each structure should reference one field of the entry to submit. The second argument
160    specifies the number of structures in the array.  <function>sd_journal_sendv()</function> is particularly useful to
161    submit binary objects to the journal where that is necessary. Note that this function will not strip trailing
162    whitespace of the passed fields, but passes the specified data along unmodified. This is different from both
163    <function>sd_journal_print()</function> and <function>sd_journal_send()</function> described above, which are based
164    on format strings, and do strip trailing whitespace.</para>
165
166    <para><function>sd_journal_perror()</function> is a similar to
167    <citerefentry project='die-net'><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
168    and writes a message to the journal that consists of the passed
169    string, suffixed with ": " and a human-readable representation of
170    the current error code stored in
171    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
172    If the message string is passed as <constant>NULL</constant> or
173    empty string, only the error string representation will be
174    written, prefixed with nothing. An additional journal field ERRNO=
175    is included in the entry containing the numeric error code
176    formatted as decimal string. The log priority used is
177    <constant>LOG_ERR</constant> (3).</para>
178
179    <para>Note that <function>sd_journal_send()</function> is a
180    wrapper around <function>sd_journal_sendv()</function> to make it
181    easier to use when only text strings shall be submitted. Also, the
182    following two calls are mostly equivalent:</para>
183
184    <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
185
186sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
187                "PRIORITY=%i", LOG_INFO,
188                NULL);</programlisting>
189
190    <para>Note that these calls implicitly add fields for the source file, function name and code line where
191    invoked. This is implemented with macros. If this is not desired, it can be turned off by defining
192    <constant>SD_JOURNAL_SUPPRESS_LOCATION</constant> before including <filename>sd-journal.h</filename>.
193    </para>
194
195    <para><function>sd_journal_print_with_location()</function>,
196    <function>sd_journal_printv_with_location()</function>, <function>sd_journal_send_with_location()</function>,
197    <function>sd_journal_sendv_with_location()</function>, and
198    <function>sd_journal_perror_with_location()</function> are similar to their counterparts without
199    <literal>_with_location</literal>, but accept additional parameters to explicitly set the source file
200    name, function, and line. Those arguments must contain valid journal entries including the variable name,
201    e.g. <literal>CODE_FILE=src/foo.c</literal>, <literal>CODE_LINE=666</literal>,
202    <literal>CODE_FUNC=myfunc</literal>. These variants are primarily useful when writing custom wrappers,
203    for example in bindings for a different language.</para>
204
205    <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
206    and <function>sd_journal_print()</function> may
207    largely be used interchangeably
208    functionality-wise. However, note that log messages
209    logged via the former take a different path to the
210    journal server than the later, and hence global
211    chronological ordering between the two streams cannot
212    be guaranteed. Using
213    <function>sd_journal_print()</function> has the
214    benefit of logging source code line, filenames, and
215    functions as metadata along all entries, and
216    guaranteeing chronological ordering with structured
217    log entries that are generated via
218    <function>sd_journal_send()</function>. Using
219    <function>syslog()</function> has the benefit of being
220    more portable.</para>
221
222    <para>These functions implement a client to the <ulink
223    url="https://systemd.io/JOURNAL_NATIVE_PROTOCOL">Native Journal Protocol</ulink>.</para>
224  </refsect1>
225
226  <refsect1>
227    <title>Return Value</title>
228
229    <para>The ten functions return 0 on success or a negative errno-style error code. The
230    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
231    variable itself is not altered.</para>
232
233    <para>If
234    <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>
235    is not running (the socket is not present), those functions do
236    nothing, and also return 0.</para>
237  </refsect1>
238
239  <refsect1>
240    <title>Thread safety</title>
241
242    <xi:include href="threads-aware.xml" xpointer="safe"/>
243
244    <para><function>sd_journal_sendv()</function> and <function>sd_journal_sendv_with_location()</function>
245    are "async signal safe" in the meaning of
246    <citerefentry project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
247    </para>
248
249    <para><function>sd_journal_print()</function>,
250    <function>sd_journal_printv()</function>,
251    <function>sd_journal_send()</function>,
252    <function>sd_journal_perror()</function>,
253    and their counterparts with <literal>_with_location</literal>
254    are not async signal safe.</para>
255  </refsect1>
256
257  <xi:include href="libsystemd-pkgconfig.xml" />
258
259  <refsect1>
260    <title>See Also</title>
261
262    <para>
263      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
264      <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
265      <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
266      <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
267      <citerefentry project='die-net'><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
268      <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
269      <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
270      <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
271      <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
272    </para>
273  </refsect1>
274
275</refentry>
276