chiark / gitweb /
include <poll.h> instead of <sys/poll.h>
[elogind.git] / 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>