man: document sd_print() and friends
This commit is contained in:
Lennart Poettering
parent
1235509582
commit
a8eedf4953
12
Makefile.am
12
Makefile.am
|
|
@ -504,7 +504,9 @@ MANPAGES = \
|
|||
man/systemd.preset.5 \
|
||||
man/sd-id128.7 \
|
||||
man/sd_id128_to_string.3 \
|
||||
man/sd_id128_randomize.3
|
||||
man/sd_id128_randomize.3 \
|
||||
man/sd-journal.7 \
|
||||
man/sd_journal_print.3
|
||||
|
||||
MANPAGES_ALIAS = \
|
||||
man/reboot.8 \
|
||||
|
|
@ -541,7 +543,10 @@ MANPAGES_ALIAS = \
|
|||
man/sd_id128_equal.7 \
|
||||
man/sd_id128_from_string.3 \
|
||||
man/sd_id128_get_machine.3 \
|
||||
man/sd_id128_get_boot.3
|
||||
man/sd_id128_get_boot.3 \
|
||||
man/sd_journal_printv.3 \
|
||||
man/sd_journal_send.3 \
|
||||
man/sd_journal_sendv.3
|
||||
|
||||
man/reboot.8: man/halt.8
|
||||
man/poweroff.8: man/halt.8
|
||||
|
|
@ -578,6 +583,9 @@ man/sd_id128_equal.7: man/sd-id128.7
|
|||
man/sd_id128_from_string.3: man/sd_id128_to_string.3
|
||||
man/sd_id128_get_machine.3: man/sd_id128_randomize.3
|
||||
man/sd_id128_get_boot.3: man/sd_id128_randomize.3
|
||||
man/sd_journal_printv.3: man/sd_journal_print.3
|
||||
man/sd_journal_send.3: man/sd_journal_print.3
|
||||
man/sd_journal_sendv.3: man/sd_journal_print.3
|
||||
|
||||
XML_FILES = \
|
||||
${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,125 @@
|
|||
<?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">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2012 Lennart Poettering
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="sd-journal">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd-journal</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</refentrytitle>
|
||||
<manvolnum>7</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd-journal</refname>
|
||||
<refpurpose>APIs for submitting and querying log entries to and from the Journal</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
|
||||
</funcsynopsis>
|
||||
|
||||
<cmdsynopsis>
|
||||
<command>pkg-config --cflags --libs libsystemd-journal</command>
|
||||
</cmdsynopsis>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><filename>sd-journal.h</filename> provides APIs
|
||||
to submit and query log entries. The APIs exposed act
|
||||
both as client for the
|
||||
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
journal service and as parser for the journal files
|
||||
on disk.
|
||||
</para>
|
||||
|
||||
<para>See
|
||||
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
and
|
||||
<citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
for more information about the functions
|
||||
implemented.</para>
|
||||
|
||||
<para>Command line access for submitting entries to
|
||||
the journal is available with the
|
||||
<citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
tool. Command line access for querying entries from
|
||||
the journal is available with the
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
tool.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>These APIs are implemented 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_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -125,7 +125,7 @@
|
|||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>The three calls returns 0 on success (in which
|
||||
<para>The three calls return 0 on success (in which
|
||||
case <parameter>ret</parameter> is filled in), or a
|
||||
negative errno-style error code.</para>
|
||||
</refsect1>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,206 @@
|
|||
<?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">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2012 Lennart Poettering
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<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>
|
||||
<refpurpose>Submit log entries to the journal</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-journal.h></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>
|
||||
|
||||
</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 a 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>Note that <function>sd_journal_send()</function>
|
||||
is a wapper 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>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>The four calls return 0 on success or a
|
||||
negative errno-style error code.</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>7</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -165,7 +165,8 @@
|
|||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -53,11 +53,12 @@
|
|||
<para>Entries in the journal resemble an environment
|
||||
block in their syntax, however with fields that can
|
||||
include binary data. Primarily, fields are formatted
|
||||
ASCII strings, and binary formatting is used only
|
||||
where formatting as ASCII makes little sense. New
|
||||
fields may be freely defined by applications, but a
|
||||
few fields have special meaning. All fields with
|
||||
special meaning are optional.</para>
|
||||
UTF-8 text strings, and binary formatting is used only
|
||||
where formatting as UTF-8 text strings makes little
|
||||
sense. New fields may freely be defined by
|
||||
applications, but a few fields have special
|
||||
meaning. All fields with special meanings are
|
||||
optional.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
|
@ -355,7 +356,8 @@
|
|||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ int sd_journal_printv(int priority, const char *format, va_list ap);
|
|||
int sd_journal_send(const char *format, ...) __attribute__((sentinel));
|
||||
int sd_journal_sendv(const struct iovec *iov, int n);
|
||||
|
||||
/* Used by the macros below */
|
||||
/* Used by the macros below. Don't call this directly. */
|
||||
int sd_journal_print_with_location(int priority, const char *file, const char *line, const char *func, const char *format, ...) __attribute__ ((format (printf, 5, 6)));
|
||||
int sd_journal_printv_with_location(int priority, const char *file, const char *line, const char *func, const char *format, va_list ap);
|
||||
int sd_journal_send_with_location(const char *file, const char *line, const char *func, const char *format, ...) __attribute__((sentinel));
|
||||
|
|
|
|||
Loading…
Reference in New Issue