<?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">

<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>

<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 project='man-pages'><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 project='man-pages'><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 project='die-net'><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>

<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 project='man-pages'><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 project='die-net'><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 project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>