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     <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be called
  96     from multiple threads.</para>
  97
  98     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
  99   </refsect1>
 100
 101   <refsect1>
 102     <title>Examples</title>
 103
 104     <para>Creating a log stream suitable for
 105     <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para>
 106
 107     <programlisting>#include &lt;syslog.h&gt;
 108 #include &lt;stdio.h&gt;
 109 #include &lt;string.h&gt;
 110 #include &lt;unistd.h&gt;
 111 #include &lt;systemd/sd-journal.h&gt;
 112 #include &lt;systemd/sd-daemon.h&gt;
 113
 114 int main(int argc, char *argv[]) {
 115   int fd;
 116   FILE *log;
 117   fd = sd_journal_stream_fd("test", LOG_INFO, 1);
 118   if (fd &lt; 0) {
 119     fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd));
 120     return 1;
 121   }
 122   log = fdopen(fd, "w");
 123   if (!log) {
 124     fprintf(stderr, "Failed to create file object: %m\n");
 125     close(fd);
 126     return 1;
 127   }
 128   fprintf(log, "Hello World!\n");
 129   fprintf(log, SD_WARNING "This is a warning!\n");
 130   fclose(log);
 131   return 0;
 132 }</programlisting>
 133
 134   </refsect1>
 135
 136   <refsect1>
 137     <title>See Also</title>
 138
 139     <para>
 140       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 144       <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 145       <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 146       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 147     </para>
 148   </refsect1>
 149
 150 </refentry>