chiark / gitweb /
man: add sd_event_add_child(3)
[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
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>