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">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_journal_print">
27 <title>sd_journal_print</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_journal_print</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
57 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
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>
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>
74 <funcdef>int <function>sd_journal_send</function></funcdef>
75 <paramdef>const char* <parameter>format</parameter></paramdef>
76 <paramdef>...</paramdef>
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>
86 <funcdef>int <function>sd_journal_perror</function></funcdef>
87 <paramdef>const char* <parameter>message</parameter></paramdef>
94 <title>Description</title>
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>
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
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>
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
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
155 array. <function>sd_journal_sendv()</function> is
156 particularly useful to submit binary objects to the
157 journal where that is necessary.</para>
159 <para><function>sd_journal_perror()</function> is a
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
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>
174 <para>Note that <function>sd_journal_send()</function>
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>
181 <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
183 sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
184 "PRIORITY=%i", LOG_INFO,
185 NULL);</programlisting>
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>
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
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>
213 <title>Return Value</title>
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>
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>
236 <title>See Also</title>
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>