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">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_journal_stream_fd" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_journal_stream_fd
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_journal_stream_fd
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_journal_stream_fd
</refname>
23 <refpurpose>Create log stream file descriptor to the journal
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
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>
41 <title>Description
</title>
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>
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
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
66 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
67 for more information.
</para>
69 <para>It is recommended that applications log UTF-
8 messages only
70 with this API, but this is not enforced.
</para>
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>
78 <title>Return Value
</title>
80 <para>The call returns a valid write-only file descriptor on
81 success or a negative errno-style error code.
</para>
85 <title>Signal safety
</title>
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>.
95 <xi:include href=
"threads-aware.xml" xpointer=
"safe"/>
97 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
101 <title>Examples
</title>
103 <para>Creating a log stream suitable for
104 <citerefentry project='man-pages'
><refentrytitle>fprintf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>:
</para>
106 <programlisting>#include
<syslog.h
>
107 #include
<stdio.h
>
108 #include
<string.h
>
109 #include
<unistd.h
>
110 #include
<systemd/sd-journal.h
>
111 #include
<systemd/sd-daemon.h
>
113 int main(int argc, char *argv[]) {
116 fd = sd_journal_stream_fd(
"test", LOG_INFO,
1);
118 fprintf(stderr,
"Failed to create stream fd: %s\n", strerror(-fd));
121 log = fdopen(fd,
"w");
123 fprintf(stderr,
"Failed to create file object: %m\n");
127 fprintf(log,
"Hello World!\n");
128 fprintf(log, SD_WARNING
"This is a warning!\n");
136 <title>See Also
</title>
139 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
140 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
141 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
142 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
143 <citerefentry project='man-pages'
><refentrytitle>syslog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
144 <citerefentry project='man-pages'
><refentrytitle>fprintf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
145 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>