man: updates to the passive target section

[elogind.git] / man / sd_journal_print.xml

diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
index cdaea8c2ef1003b2283f8a9c5e34616ee776363c..0b78502c5fef33993413ded4bdefa0ccd6ebfb80 100644 (file)
--- a/man/sd_journal_print.xml
+++ b/man/sd_journal_print.xml
@@ -59,20 +59,20 @@
                         <funcprototype>
                                 <funcdef>int <function>sd_journal_print</function></funcdef>
                                 <paramdef>int <parameter>priority</parameter></paramdef>
                         <funcprototype>
                                 <funcdef>int <function>sd_journal_print</function></funcdef>
                                 <paramdef>int <parameter>priority</parameter></paramdef>

-                                <paramdef>const char* <parameter>format</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>...</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>const char *<parameter>format</parameter></paramdef>

                                 <paramdef>va_list <parameter>ap</parameter></paramdef>
                         </funcprototype>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_journal_send</function></funcdef>
                                 <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>const char *<parameter>format</parameter></paramdef>

                                 <paramdef>...</paramdef>
                         </funcprototype>
 
                                 <paramdef>...</paramdef>
                         </funcprototype>
 


@@ -84,7 +84,7 @@
 
                         <funcprototype>
                                 <funcdef>int <function>sd_journal_perror</function></funcdef>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_journal_perror</function></funcdef>

-                                <paramdef>const char* <parameter>message</parameter></paramdef>
+                                <paramdef>const char *<parameter>message</parameter></paramdef>

                         </funcprototype>
 
                 </funcsynopsis>
                         </funcprototype>
 
                 </funcsynopsis>


@@ -102,14 +102,14 @@
                 or
                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
                 priority value is one of
                 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
+                <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><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 for details. It is recommended to use this call to
                 <filename>syslog.h</filename>, see
                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 for details. It is recommended to use this call to


@@ -120,7 +120,7 @@
                 <para><function>sd_journal_printv()</function> is
                 similar to <function>sd_journal_print()</function> but
                 takes a variable argument list encapsulated in an
                 <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
+                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>
                 <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 for more information) instead of the format string. It
                 is otherwise equivalent in behavior.</para>


@@ -129,7 +129,7 @@
                 used to submit structured log entries to the system
                 journal. It takes a series of format strings, each
                 immediately followed by their associated parameters,
                 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 NULL. The strings passed should be of
+                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
                 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


@@ -147,14 +147,14 @@
 
                 <para><function>sd_journal_sendv()</function> is
                 similar to <function>sd_journal_send()</function> but
 
                 <para><function>sd_journal_sendv()</function> is
                 similar to <function>sd_journal_send()</function> but

-                takes an array of <literal>struct iovec</literal> (as
+                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
                 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
+                structures in the array.
+                <function>sd_journal_sendv()</function> is

                 particularly useful to submit binary objects to the
                 journal where that is necessary.</para>
 
                 particularly useful to submit binary objects to the
                 journal where that is necessary.</para>
 


@@ -166,12 +166,12 @@
                 readable representation of the current error code
                 stored in
                 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
                 readable representation of the current error code
                 stored in
                 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If

-                the message string is passed as NULL or empty string
+                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
                 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 <literal>LOG_ERR</literal> (3).</para>
+                priority used is <constant>LOG_ERR</constant> (3).</para>

 
                 <para>Note that <function>sd_journal_send()</function>
                 is a wrapper around
 
                 <para>Note that <function>sd_journal_send()</function>
                 is a wrapper around


@@ -189,7 +189,7 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
                 <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
                 <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
+                not desired, it can be turned off by defining

                 SD_JOURNAL_SUPPRESS_LOCATION before including
                 <filename>sd-journal.h</filename>.</para>
 
                 SD_JOURNAL_SUPPRESS_LOCATION before including
                 <filename>sd-journal.h</filename>.</para>
 


@@ -202,8 +202,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
                 chronological ordering between the two streams cannot
                 be guaranteed. Using
                 <function>sd_journal_print()</function> has the
                 chronological ordering between the two streams cannot
                 be guaranteed. Using
                 <function>sd_journal_print()</function> has the

-                benefit of logging source code line, file names, and
-                functions as meta data along all entries, and
+                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
                 guaranteeing chronological ordering with structured
                 log entries that are generated via
                 <function>sd_journal_send()</function>. Using


@@ -218,6 +218,24 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
                 errno-style error code. The
                 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 variable itself is not altered.</para>
                 errno-style error code. The
                 <citerefentry><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>
         </refsect1>
 
         <refsect1>


@@ -227,10 +245,9 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
                 <function>sd_journal_printv()</function>,
                 <function>sd_journal_send()</function> and
                 <function>sd_journal_sendv()</function> interfaces
                 <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
+                are available as a shared library, which can be compiled

                 and linked to with the
                 and linked to with the

-                <literal>libsystemd-journal</literal>
-                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

                 file.</para>
         </refsect1>
 
                 file.</para>
         </refsect1>
 


@@ -244,7 +261,9 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
                         <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</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>
 
                 </para>
         </refsect1>