man/sd_journal_stream_fd.xml

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