summaryrefslogtreecommitdiff
path: root/man/sd_journal_print.xml
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2012-07-09 15:46:21 +0200
committerLennart Poettering <lennart@poettering.net>2012-07-09 15:46:21 +0200
commita8eedf4953d379dc09ee2b04e69a0a54ba247a02 (patch)
treeca0558e7177bccb7ccd112320a24089dff164ef6 /man/sd_journal_print.xml
parent12355095821fc17529af5b6eaefa31c3c520be39 (diff)
man: document sd_print() and friends
Diffstat (limited to 'man/sd_journal_print.xml')
-rw-r--r--man/sd_journal_print.xml206
1 files changed, 206 insertions, 0 deletions
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
new file mode 100644
index 0000000000..c40498b38a
--- /dev/null
+++ b/man/sd_journal_print.xml
@@ -0,0 +1,206 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2012 Lennart Poettering
+
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
+ (at your option) any later version.
+
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_journal_print">
+
+ <refentryinfo>
+ <title>sd_journal_print</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_journal_print</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_journal_print</refname>
+ <refname>sd_journal_printv</refname>
+ <refname>sd_journal_send</refname>
+ <refname>sd_journal_sendv</refname>
+ <refpurpose>Submit log entries to the journal</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_print</function></funcdef>
+ <paramdef>int <parameter>priority</parameter></paramdef>
+ <paramdef>const char* <parameter>format</parameter></paramdef>
+ <paramdef>...</paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_printv</function></funcdef>
+ <paramdef>int <parameter>priority</parameter></paramdef>
+ <paramdef>const char* <parameter>format</parameter></paramdef>
+ <paramdef>va_list <parameter>ap</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_send</function></funcdef>
+ <paramdef>const char* <parameter>format</parameter></paramdef>
+ <paramdef>...</paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_sendv</function></funcdef>
+ <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
+ <paramdef>int <parameter>n</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_journal_print()</function> may be
+ used to submit simple, plain text log entries to the
+ system journal. The first argument is a priority
+ value. This is followed by a format string and its
+ parameters, similar to
+ <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ or
+ <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
+ priority value is one of
+ <literal>LOG_EMERG</literal>,
+ <literal>LOG_ALERT</literal>,
+ <literal>LOG_CRIT</literal>,
+ <literal>LOG_ERR</literal>,
+ <literal>LOG_WARNING</literal>,
+ <literal>LOG_NOTICE</literal>,
+ <literal>LOG_INFO</literal>,
+ <literal>LOG_DEBUG</literal>, as defined in
+ <filename>syslog.h</filename>, see
+ <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for details. It is recommended to use this call to
+ submit log messages in the application locale or system
+ locale and in UTF-8 format, but no such restrictions
+ are enforced.</para>
+
+ <para><function>sd_journal_printv()</function> is
+ similar to <function>sd_journal_print()</function> but
+ takes a variable argument list encapsulated in an
+ object of type <literal>va_list</literal> (see
+ <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for more information) instead of the format string. It
+ is otherwise equivalent in behaviour.</para>
+
+ <para><function>sd_journal_send()</function> may be
+ used to submit structured log entries to the system
+ journal. It takes a series of format strings, each
+ immediately followed by their associated parameters,
+ terminated by a NULL. The strings passed should be of
+ the format <literal>VARIABLE=value</literal>. The
+ variable name must be in uppercase and consist only
+ of characters, numbers and underscores, and may not
+ begin with an underscore. The value can be of any size
+ and format. It is highly recommended to submit
+ text strings formatted in the UTF-8 character encoding
+ only, and submit binary fields only when formatting in
+ UTf-8 strings is not sensible. A number of well known
+ fields are defined, see
+ <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details, but additional application defined fields
+ may be used.</para>
+
+ <para><function>sd_journal_sendv()</function> is
+ similar to <function>sd_journal_send()</function> but
+ takes an array of <literal>struct iovec</literal> (as
+ defined in <filename>uio.h</filename>, see
+ <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for details) instead of the format string. Each
+ structure should reference one field of the entry to
+ submit. The second argument specifies the number of
+ structures in the
+ array. <function>sd_journal_sendv()</function> is
+ particularly useful to submit binary objects to the
+ journal where that is necessary.</para>
+
+ <para>Note that <function>sd_journal_send()</function>
+ is a wapper around
+ <function>sd_journal_sendv()</function> to make it
+ easier to use when only text strings shall be
+ submitted. Also, the following two calls are
+ mostly equivalent:</para>
+
+ <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
+
+sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
+ "PRIORITY=%i", LOG_INFO,
+ NULL);</programlisting>
+
+ <para>Note that these calls implicitly add fields for
+ the source file, function name and code line where
+ invoked. This is implemented with macros. If this is
+ not desired it can be turned off by defining
+ SD_JOURNAL_SUPPRESS_LOCATION before including
+ <filename>sd-journal.h</filename>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>The four calls return 0 on success or a
+ negative errno-style error code.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>The <function>sd_journal_print()</function>,
+ <function>sd_journal_printv()</function>,
+ <function>sd_journal_send()</function> and
+ <function>sd_journal_sendv()</function> interfaces
+ are available as shared library, which can be compiled
+ and linked to with the
+ <literal>libsystemd-journal</literal>
+ <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ file.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>