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+
8 This file is part of systemd.
10 Copyright 2012 Lennart Poettering
13 <refentry id=
"sd_journal_stream_fd">
16 <title>sd_journal_stream_fd
</title>
17 <productname>systemd
</productname>
21 <contrib>Developer
</contrib>
22 <firstname>Lennart
</firstname>
23 <surname>Poettering
</surname>
24 <email>lennart@poettering.net
</email>
30 <refentrytitle>sd_journal_stream_fd
</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_journal_stream_fd
</refname>
36 <refpurpose>Create log stream file descriptor to the journal
</refpurpose>
41 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
44 <funcdef>int
<function>sd_journal_stream_fd
</function></funcdef>
45 <paramdef>const char *
<parameter>identifier
</parameter></paramdef>
46 <paramdef>int
<parameter>priority
</parameter></paramdef>
47 <paramdef>int
<parameter>level_prefix
</parameter></paramdef>
54 <title>Description
</title>
56 <para><function>sd_journal_stream_fd()
</function> may be used to
57 create a log stream file descriptor. Log messages written to this
58 file descriptor as simple newline-separated text strings are
59 written to the journal. This file descriptor can be used
60 internally by applications or be made standard output or standard
61 error of other processes executed.
</para>
63 <para><function>sd_journal_stream_fd()
</function> takes a short
64 program identifier string as first argument, which will be written
65 to the journal as _SYSLOG_IDENTIFIER= field for each log entry
67 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
68 for more information). The second argument shall be the default
69 priority level for all messages. The priority level is one of
70 <constant>LOG_EMERG
</constant>,
<constant>LOG_ALERT
</constant>,
71 <constant>LOG_CRIT
</constant>,
<constant>LOG_ERR
</constant>,
72 <constant>LOG_WARNING
</constant>,
<constant>LOG_NOTICE
</constant>,
73 <constant>LOG_INFO
</constant>,
<constant>LOG_DEBUG
</constant>, as
74 defined in
<filename>syslog.h
</filename>, see
75 <citerefentry project='man-pages'
><refentrytitle>syslog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
76 for details. The third argument is a boolean: if true kernel-style
77 log level prefixes (such as
<constant>SD_WARNING
</constant>) are
79 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
80 for more information.
</para>
82 <para>It is recommended that applications log UTF-
8 messages only
83 with this API, but this is not enforced.
</para>
85 <para>Each invocation of
<function>sd_journal_stream_fd()
</function> allocates a new log stream file descriptor,
86 that is not shared with prior or later invocations. The file descriptor is write-only (its reading direction is
87 shut down), and
<constant>O_NONBLOCK
</constant> is turned off initially.
</para>
91 <title>Return Value
</title>
93 <para>The call returns a valid write-only file descriptor on
94 success or a negative errno-style error code.
</para>
98 <title>Signal safety
</title>
100 <para><function>sd_journal_stream_fd()
</function> is
"async signal safe" in the meaning of
<citerefentry
101 project='man-pages'
><refentrytitle>signal-safety
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
108 <para>Function
<function>sd_journal_stream_fd()
</function> is thread-safe and may be called
109 from multiple threads.
</para>
111 <para>The
<function>sd_journal_stream_fd()
</function> interface is
112 available as a shared library, which can be compiled and linked to
114 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
119 <title>Examples
</title>
121 <para>Creating a log stream suitable for
122 <citerefentry project='man-pages'
><refentrytitle>fprintf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>:
</para>
124 <programlisting>#include
<syslog.h
>
125 #include
<stdio.h
>
126 #include
<string.h
>
127 #include
<unistd.h
>
128 #include
<systemd/sd-journal.h
>
129 #include
<systemd/sd-daemon.h
>
131 int main(int argc, char *argv[]) {
134 fd = sd_journal_stream_fd(
"test", LOG_INFO,
1);
136 fprintf(stderr,
"Failed to create stream fd: %s\n", strerror(-fd));
139 log = fdopen(fd,
"w");
141 fprintf(stderr,
"Failed to create file object: %m\n");
145 fprintf(log,
"Hello World!\n");
146 fprintf(log, SD_WARNING
"This is a warning!\n");
154 <title>See Also
</title>
157 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
158 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
159 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
160 <citerefentry><refentrytitle>sd_journal_print
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
161 <citerefentry project='man-pages'
><refentrytitle>syslog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
162 <citerefentry project='man-pages'
><refentrytitle>fprintf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
163 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>