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.5/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     <refname>sd_journal_stream_fd_with_namespace</refname>
  21     <refpurpose>Create log stream file descriptor to the journal</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <funcsynopsis>
  26       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  27
  28       <funcprototype>
  29         <funcdef>int <function>sd_journal_stream_fd</function></funcdef>
  30         <paramdef>const char *<parameter>identifier</parameter></paramdef>
  31         <paramdef>int <parameter>priority</parameter></paramdef>
  32         <paramdef>int <parameter>level_prefix</parameter></paramdef>
  33       </funcprototype>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_journal_stream_fd_with_namespace</function></funcdef>
  37         <paramdef>const char *<parameter>name_space</parameter></paramdef>
  38         <paramdef>const char *<parameter>identifier</parameter></paramdef>
  39         <paramdef>int <parameter>priority</parameter></paramdef>
  40         <paramdef>int <parameter>level_prefix</parameter></paramdef>
  41       </funcprototype>
  42
  43     </funcsynopsis>
  44   </refsynopsisdiv>
  45
  46   <refsect1>
  47     <title>Description</title>
  48
  49     <para><function>sd_journal_stream_fd()</function> may be used to create a log stream file descriptor.
  50     Log messages written to this file descriptor as simple newline-separated text strings are written
  51     to the journal. This file descriptor can be used internally by applications or be made standard output
  52     or standard error of other processes executed.</para>
  53
  54     <para><function>sd_journal_stream_fd()</function> takes a short program identifier string as
  55     first argument, which will be written to the journal as SYSLOG_IDENTIFIER= field for each log entry
  56     (see
  57     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  58     for more information). The second argument shall be the default priority level for all messages.
  59     The priority level is one of
  60     <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>,
  61     <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>,
  62     <constant>LOG_WARNING</constant>, <constant>LOG_NOTICE</constant>,
  63     <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as
  64     defined in <filename>syslog.h</filename>, see
  65     <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  66     for details. The third argument is a boolean: if true kernel-style
  67     log level prefixes (such as <constant>SD_WARNING</constant>) are
  68     interpreted, see
  69     <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  70     for more information.</para>
  71
  72     <para><function>sd_journal_stream_fd_with_namespace()</function> is similar to
  73     <function>sd_journal_stream_fd()</function>, but takes an additional <parameter>name_space</parameter> parameter
  74     that specifies which journal namespace to operate on. If specified as <constant>NULL</constant> the call
  75     is identical to <function>sd_journal_stream_fd()</function>. For details about journal namespaces, see
  76     <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  77
  78     <para>It is recommended that applications log UTF-8 messages only with this API, but this is not enforced.</para>
  79
  80     <para>Each invocation of these functions allocates a new log stream file descriptor,
  81     that is not shared with prior or later invocations. The file descriptor is write-only (its reading direction
  82     is shut down), and <constant>O_NONBLOCK</constant> is turned off initially.</para>
  83   </refsect1>
  84
  85   <refsect1>
  86     <title>Return Value</title>
  87
  88     <para>The call returns a valid write-only file descriptor on success or a negative errno-style error code.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Signal safety</title>
  93
  94     <para><function>sd_journal_stream_fd()</function> and <function>sd_journal_stream_fd_with_namespace()</function>
  95     are "async signal safe" in the meaning of <citerefentry
  96     project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  97     </para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Notes</title>
 102
 103     <xi:include href="threads-aware.xml" xpointer="safe"/>
 104
 105     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Examples</title>
 110
 111     <para>Creating a log stream suitable for
 112     <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para>
 113
 114     <programlisting><xi:include href="journal-stream-fd.c" parse="text" /></programlisting>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>History</title>
 119     <para><function>sd_journal_stream_fd()</function> was added in version 187.</para>
 120     <para><function>sd_journal_stream_fd_with_namespace()</function> was added in version 256.</para>
 121   </refsect1>
 122
 123   <refsect1>
 124     <title>See Also</title>
 125
 126     <para><simplelist type="inline">
 127       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 128       <member><citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 129       <member><citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 130       <member><citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 131       <member><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 132       <member><citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 133       <member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 134     </simplelist></para>
 135   </refsect1>
 136
 137 </refentry>