diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-20 20:45:14 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-21 09:08:14 +0200 |
commit | c11edfee986ecef0cacd803e65b5a26373db87af (patch) | |
tree | f0442dd68abc680bc83891f615de6bacca224609 /man/sd_journal_print.xml | |
parent | 842a362c3a439f88186fa3a2d5903390f9fe5181 (diff) | |
download | systemd-c11edfee986ecef0cacd803e65b5a26373db87af.tar.gz |
man: document sd_journal_*_with_location
Diffstat (limited to 'man/sd_journal_print.xml')
-rw-r--r-- | man/sd_journal_print.xml | 88 |
1 files changed, 75 insertions, 13 deletions
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index f6973087f3..84adab5c7b 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -22,6 +22,12 @@ <refname>sd_journal_sendv</refname> <refname>sd_journal_perror</refname> <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname> + <refname>sd_journal_print_with_location</refname> + <refname>sd_journal_printv_with_location</refname> + <refname>sd_journal_send_with_location</refname> + <refname>sd_journal_sendv_with_location</refname> + <refname>sd_journal_perror_with_location</refname> + <refpurpose>Submit log entries to the journal</refpurpose> </refnamediv> @@ -60,6 +66,51 @@ <paramdef>const char *<parameter>message</parameter></paramdef> </funcprototype> + <funcprototype> + <funcdef>int <function>sd_journal_print_with_location</function></funcdef> + <paramdef>const char *<parameter>file</parameter></paramdef> + <paramdef>const char *<parameter>line</parameter></paramdef> + <paramdef>const char *<parameter>func</parameter></paramdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_printv_with_location</function></funcdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char *<parameter>file</parameter></paramdef> + <paramdef>const char *<parameter>line</parameter></paramdef> + <paramdef>const char *<parameter>func</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_send_with_location</function></funcdef> + <paramdef>const char *<parameter>file</parameter></paramdef> + <paramdef>const char *<parameter>line</parameter></paramdef> + <paramdef>const char *<parameter>func</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_sendv_with_location</function></funcdef> + <paramdef>const char *<parameter>file</parameter></paramdef> + <paramdef>const char *<parameter>line</parameter></paramdef> + <paramdef>const char *<parameter>func</parameter></paramdef> + <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> + <paramdef>int <parameter>n</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_perror_with_location</function></funcdef> + <paramdef>const char *<parameter>file</parameter></paramdef> + <paramdef>const char *<parameter>line</parameter></paramdef> + <paramdef>const char *<parameter>func</parameter></paramdef> + <paramdef>const char *<parameter>message</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -136,11 +187,20 @@ 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> + <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 + <constant>SD_JOURNAL_SUPPRESS_LOCATION</constant> before including <filename>sd-journal.h</filename>. + </para> + + <para><function>sd_journal_print_with_location</function>, + <function>sd_journal_printv_with_location</function>, <function>sd_journal_send_with_location</function>, + <function>sd_journal_sendv_with_location</function>, and + <function>sd_journal_perror_with_location</function> are similar to their counterparts without + <literal>_with_location</literal>, but accept additional parameters to explicitly set the source file + name, function, and line. Those arguments must contain valid journal entries including the variable name, + e.g. <literal>CODE_FILE=src/foo.c</literal>, <literal>CODE_LINE=666</literal>, + <literal>CODE_FUNC=myfunc</literal>. These variants are primarily useful when writing custom wrappers, + for example in bindings for a different language.</para> <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <function>sd_journal_print()</function> may @@ -163,9 +223,9 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( <refsect1> <title>Return Value</title> - <para>The five 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>The ten functions 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> @@ -178,15 +238,17 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( <xi:include href="threads-aware.xml" xpointer="safe"/> - <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry - project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + <para><function>sd_journal_sendv()</function> and <function>sd_journal_sendv_with_location()</function> + are "async signal safe" in the meaning of + <citerefentry project='man-pages'><refentrytitle>signal-safety</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> + <function>sd_journal_send</function>, + <function>sd_journal_perror</function>, + and their counterparts with <literal>_with_location</literal> + are not async signal safe.</para> </refsect1> <xi:include href="libsystemd-pkgconfig.xml" /> |