diff options
Diffstat (limited to 'man/sd_journal_print.xml')
| -rw-r--r-- | man/sd_journal_print.xml | 251 |
1 files changed, 0 insertions, 251 deletions
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml deleted file mode 100644 index 7742268f5d..0000000000 --- a/man/sd_journal_print.xml +++ /dev/null @@ -1,251 +0,0 @@ -<?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> - <refname>sd_journal_perror</refname> - <refname>SD_JOURNAL_SUPPRESS_LOCATION</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> - - <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 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 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. (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 <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 <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> |