<?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><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>

or

<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The

priority value is one of

<literal>LOG_EMERG</literal>,

<literal>LOG_ALERT</literal>,

<literal>LOG_CRIT</literal>,

<literal>LOG_ERR</literal>,

<literal>LOG_WARNING</literal>,

<literal>LOG_NOTICE</literal>,

<literal>LOG_INFO</literal>,

<literal>LOG_DEBUG</literal>, as defined in

<filename>syslog.h</filename>, see

<citerefentry><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 <literal>va_list</literal> (see

<citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry>

for more information) instead of the format string. It

is otherwise equivalent in behaviour.</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 NULL. 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. 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.</para>

<para><function>sd_journal_sendv()</function> is

similar to <function>sd_journal_send()</function> but

takes an array of <literal>struct iovec</literal> (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><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If

the message string is passed as NULL 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 <literal>LOG_ERR</literal> (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><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>

and 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, file names, and

functions as meta data 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><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>

variable itself is not altered.</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 shared library, which can be compiled

and linked to with the

<literal>libsystemd-journal</literal>

<citerefentry><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><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>