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 <systemd/sd-journal.h></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 <syslog.h> 104#include <stdio.h> 105#include <string.h> 106#include <unistd.h> 107#include <systemd/sd-journal.h> 108#include <systemd/sd-daemon.h> 109 110int main(int argc, char *argv[]) { 111 int fd; 112 FILE *log; 113 fd = sd_journal_stream_fd("test", LOG_INFO, 1); 114 if (fd < 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> 147