Skip to content

Commit

Permalink
man: fix sd_journal_*_with_location's func argument
Browse files Browse the repository at this point in the history
`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__)

(cherry picked from commit 673ed95)
(cherry picked from commit 121bbb5)
(cherry picked from commit 2d2ec1e)
  • Loading branch information
vai-hanlo authored and bluca committed Jul 10, 2023
1 parent 0d8dd90 commit 4a2dbd9
Showing 1 changed file with 5 additions and 4 deletions.
9 changes: 5 additions & 4 deletions man/sd_journal_print.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 4a2dbd9

Please sign in to comment.