man/sd_journal_stream_fd.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_stream_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_journal_stream_fd</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_journal_stream_fd</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_journal_stream_fd</refname>
  23     <refpurpose>Create log stream file descriptor to the journal</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int <function>sd_journal_stream_fd</function></funcdef>
  32         <paramdef>const char *<parameter>identifier</parameter></paramdef>
  33         <paramdef>int <parameter>priority</parameter></paramdef>
  34         <paramdef>int <parameter>level_prefix</parameter></paramdef>
  35       </funcprototype>
  36
  37     </funcsynopsis>
  38   </refsynopsisdiv>
  39
  40   <refsect1>
  41     <title>Description</title>
  42
  43     <para><function>sd_journal_stream_fd()</function> may be used to
  44     create a log stream file descriptor. Log messages written to this
  45     file descriptor as simple newline-separated text strings are
  46     written to the journal. This file descriptor can be used
  47     internally by applications or be made standard output or standard
  48     error of other processes executed.</para>
  49
  50     <para><function>sd_journal_stream_fd()</function> takes a short
  51     program identifier string as first argument, which will be written
  52     to the journal as _SYSLOG_IDENTIFIER= field for each log entry
  53     (see
  54     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  55     for more information). The second argument shall be the default
  56     priority level for all messages. The priority level is one of
  57     <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>,
  58     <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>,
  59     <constant>LOG_WARNING</constant>, <constant>LOG_NOTICE</constant>,
  60     <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as
  61     defined in <filename>syslog.h</filename>, see
  62     <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  63     for details. The third argument is a boolean: if true kernel-style
  64     log level prefixes (such as <constant>SD_WARNING</constant>) are
  65     interpreted, see
  66     <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  67     for more information.</para>
  68
  69     <para>It is recommended that applications log UTF-8 messages only
  70     with this API, but this is not enforced.</para>
  71
  72     <para>Each invocation of <function>sd_journal_stream_fd()</function> allocates a new log stream file descriptor,
  73     that is not shared with prior or later invocations. The file descriptor is write-only (its reading direction is
  74     shut down), and <constant>O_NONBLOCK</constant> is turned off initially.</para>
  75   </refsect1>
  76
  77   <refsect1>
  78     <title>Return Value</title>
  79
  80     <para>The call returns a valid write-only file descriptor on
  81     success or a negative errno-style error code.</para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>Signal safety</title>
  86
  87     <para><function>sd_journal_stream_fd()</function> is "async signal safe" in the meaning of <citerefentry
  88     project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  89     </para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Notes</title>
  94
  95     <xi:include href="threads-aware.xml" xpointer="safe"/>
  96
  97     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Examples</title>
 102
 103     <para>Creating a log stream suitable for
 104     <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para>
 105
 106     <programlisting>#include &lt;syslog.h&gt;
 107 #include &lt;stdio.h&gt;
 108 #include &lt;string.h&gt;
 109 #include &lt;unistd.h&gt;
 110 #include &lt;systemd/sd-journal.h&gt;
 111 #include &lt;systemd/sd-daemon.h&gt;
 112
 113 int main(int argc, char *argv[]) {
 114   int fd;
 115   FILE *log;
 116   fd = sd_journal_stream_fd("test", LOG_INFO, 1);
 117   if (fd &lt; 0) {
 118     fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd));
 119     return 1;
 120   }
 121   log = fdopen(fd, "w");
 122   if (!log) {
 123     fprintf(stderr, "Failed to create file object: %m\n");
 124     close(fd);
 125     return 1;
 126   }
 127   fprintf(log, "Hello World!\n");
 128   fprintf(log, SD_WARNING "This is a warning!\n");
 129   fclose(log);
 130   return 0;
 131 }</programlisting>
 132
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>See Also</title>
 137
 138     <para>
 139       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 144       <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 145       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 146     </para>
 147   </refsect1>
 148
 149 </refentry>