From: Hannu Lounento <hannu.lounento@vaisala.com>
Date: Tue, 30 May 2023 10:48:20 +0000 (+0300)
Subject: man: fix sd_journal_*_with_location's func argument
X-Git-Tag: v254-rc1~306
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=673ed95966c741807f993f7fd6b5d93bbc504458;p=thirdparty%2Fsystemd.git

man: fix sd_journal_*_with_location's func argument

`sd_journal_print_with_location` and similar functions behave
inconsistently compared to their documentation, which says:

    sd_journal_print_with_location(), sd_journal_printv_with_location(),
    sd_journal_send_with_location(), sd_journal_sendv_with_location(),
    and sd_journal_perror_with_location() [...] 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. "CODE_FILE=src/foo.c", "CODE_LINE=666",
    "CODE_FUNC=myfunc".

Calling e.g. `sd_journal_sendv_with_location` with
`CODE_FUNC=myfunction` as the value of the argument `func` results in

    "CODE_FUNC" : "CODE_FUNC=myfunction"

because `sd_journal_*_with_location` implicitly prefix the argument
`func` with `CODE_FUNC=`. For example:

    _public_ int sd_journal_sendv_with_location(
                    const char *file, const char *line,
                    const char *func,
                    const struct iovec *iov, int n) {
            [...]
            char *f;
            [...]
            niov = newa(struct iovec, n + 3);
            [...]
            ALLOCA_CODE_FUNC(f, func);
            [...]
            niov[n++] = IOVEC_MAKE_STRING(f);

            return sd_journal_sendv(niov, n);
    }

where `ALLOCA_CODE_FUNC` is:

    #define ALLOCA_CODE_FUNC(f, func)                 \
            do {                                      \
                    size_t _fl;                       \
                    const char *_func = (func);       \
                    char **_f = &(f);                 \
                    _fl = strlen(_func) + 1;          \
                    *_f = newa(char, _fl + 10);       \
                    memcpy(*_f, "CODE_FUNC=", 10);    \
                    memcpy(*_f + 10, _func, _fl);     \
            } while (false)

The arguments `file` and `line` are _not_ prefixed similarly but
expected to be prefixed already with `CODE_FILE=` and `CODE_LINE=`
respectively and sent as is like the documentation describes.

That is, the argument `func` is treated differently and behaves
inconsistently compared to the arguments `file` and `line`. The behavior
seems still intentional:

    _public_ int sd_journal_printv_with_location(int priority, const char *file, const char *line, const char *func, const char *format, va_list ap) {
            [...]
            /* func is initialized from __func__ which is not a macro, but
            * a static const char[], hence cannot easily be prefixed with
            * CODE_FUNC=, hence let's do it manually here. */
            ALLOCA_CODE_FUNC(f, func);
            [...]
    }

Thus, change the documentation to match the actual behavior.

Note: `sd_journal_{print,send}` and `sd_journal_{print,send}v` work as
expected as they only pass the function name (i.e. without `CODE_FUNC=`)
to the `func` argument of the `sd_journal_*_with_location` functions
they call. For example:

    #define sd_journal_print(priority, ...) sd_journal_print_with_location(priority, "CODE_FILE=" __FILE__, "CODE_LINE=" _SD_STRINGIFY(__LINE__), __func__, __VA_ARGS__)
---

diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
index 503bf9ec37a..77782342f2d 100644
--- a/man/sd_journal_print.xml
+++ b/man/sd_journal_print.xml
@@ -197,10 +197,11 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
     <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>
+    name, function, and line. The arguments <literal>file</literal> and <literal>line</literal> must contain valid
+    journal entries including the variable name, e.g. <literal>CODE_FILE=src/foo.c</literal> and
+    <literal>CODE_LINE=666</literal>, while <literal>func</literal> must only contain the function name, i.e. the value
+    without <literal>CODE_FUNC=</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