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