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-or-later -->
   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><xi:include href="journal-stream-fd.c" parse="text" /></programlisting>
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>History</title>
 108     <para><function>sd_journal_stream_fd()</function> was added in version 187.</para>
 109   </refsect1>
 110
 111   <refsect1>
 112     <title>See Also</title>
 113
 114     <para>
 115       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 116       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 117       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 118       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 119       <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 120       <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 122     </para>
 123   </refsect1>
 124
 125 </refentry>