diff options
Diffstat (limited to 'man/sd_journal_print.xml')
| -rw-r--r-- | man/sd_journal_print.xml | 246 |
1 files changed, 0 insertions, 246 deletions
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml deleted file mode 100644 index 2d8dd635aa..0000000000 --- a/man/sd_journal_print.xml +++ /dev/null @@ -1,246 +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 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. Note that log messages written using this function are generally not - expected to end in a new-line character. However, as all trailing whitespace (including spaces, new-lines, - tabulators and carriage returns) are automatically stripped from the logged string, it is acceptable to specify one - (or more). Empty lines (after trailing whitespace removal) are suppressed. On non-empty lines, leading whitespace - (as well as inner whitespace) is left unmodified. </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. If this function is used, trailing whitespace is automatically removed from each formatted field.</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. Note that this function wil not strip trailing - whitespace of the passed fields, but passes the specified data along unmodified. This is different from both - <function>sd_journal_print()</function> and <function>sd_journal_send()</function> described above, which are based - on format strings, and do strip trailing whitespace.</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>Thread safety</title> - <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para> - - <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> |