<?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><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><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><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><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><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><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

<citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>