X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_journal_print.xml;h=068b10e7cac0635b61202d7f4c4399b9ba65524a;hb=1c11181458990715e0ffd49e848baac5959e3c89;hp=c40498b38a318e57d4945929dd5f20d1321d2ba0;hpb=a8eedf4953d379dc09ee2b04e69a0a54ba247a02;p=elogind.git

diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
index c40498b38..068b10e7c 100644
--- a/man/sd_journal_print.xml
+++ b/man/sd_journal_print.xml
@@ -1,6 +1,6 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,184 +23,238 @@
 
 <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());
+  <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>
+    <refname>sd_journal_perror</refname>
+    <refname>SD_JOURNAL_SUPPRESS_LOCATION</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>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_perror</function></funcdef>
+        <paramdef>const char *<parameter>message</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 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or
+    <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    The priority value is one of
+    <constant>LOG_EMERG</constant>,
+    <constant>LOG_ALERT</constant>,
+    <constant>LOG_CRIT</constant>,
+    <constant>LOG_ERR</constant>,
+    <constant>LOG_WARNING</constant>,
+    <constant>LOG_NOTICE</constant>,
+    <constant>LOG_INFO</constant>,
+    <constant>LOG_DEBUG</constant>, as defined in
+    <filename>syslog.h</filename>, see
+    <citerefentry project='man-pages'><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
+    <varname>va_list</varname> (see
+    <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for more information) instead of the format string. It is
+    otherwise equivalent in behavior.</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 <constant>NULL</constant>. 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. (All assignments that do not follow this syntax will
+    be ignored.) 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. A variable may be assigned more than one value per
+    entry.</para>
+
+    <para><function>sd_journal_sendv()</function> is similar to
+    <function>sd_journal_send()</function> but takes an array of
+    <varname>struct iovec</varname> (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><function>sd_journal_perror()</function> is a similar to
+    <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and writes a message to the journal that consists of the passed
+    string, suffixed with ": " and a human readable representation of
+    the current error code stored in
+    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    If the message string is passed as <constant>NULL</constant> or
+    empty string, only the error string representation will be
+    written, prefixed with nothing. An additional journal field ERRNO=
+    is included in the entry containing the numeric error code
+    formatted as decimal string. The log priority used is
+    <constant>LOG_ERR</constant> (3).</para>
+
+    <para>Note that <function>sd_journal_send()</function> is a
+    wrapper 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>
+    "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>
+
+    <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and <function>sd_journal_print()</function> may
+    largely be used interchangeably
+    functionality-wise. However, note that log messages
+    logged via the former take a different path to the
+    journal server than the later, and hence global
+    chronological ordering between the two streams cannot
+    be guaranteed. Using
+    <function>sd_journal_print()</function> has the
+    benefit of logging source code line, filenames, and
+    functions as metadata along all entries, and
+    guaranteeing chronological ordering with structured
+    log entries that are generated via
+    <function>sd_journal_send()</function>. Using
+    <function>syslog()</function> has the benefit of being
+    more portable.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>The four calls return 0 on success or a negative errno-style
+    error code. The
+    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    variable itself is not altered.</para>
+
+    <para>If
+    <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    is not running (the socket is not present), those functions do
+    nothing, and also return 0.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Async signal safety</title>
+    <para><function>sd_journal_sendv()</function> is "async signal
+    safe" in the meaning of
+    <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_journal_print</function>,
+    <function>sd_journal_printv</function>,
+    <function>sd_journal_send</function>, and
+    <function>sd_journal_perror</function> are
+    not async signal safe.</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 a shared library, which can be compiled and linked to with the
+    <constant>libsystemd</constant> <citerefentry project='die-net'><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>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
 
 </refentry>