man/systemd-cat.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-cat"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-cat</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-cat</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-cat</refname>
  24     <refpurpose>Connect a pipeline or program's output with the journal</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
  30     </cmdsynopsis>
  31     <cmdsynopsis>
  32       <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>systemd-cat</command> may be used to connect the
  40     standard input and output of a process to the journal, or as a
  41     filter tool in a shell pipeline to pass the output the previous
  42     pipeline element generates to the journal.</para>
  43
  44     <para>If no parameter is passed, <command>systemd-cat</command>
  45     will write everything it reads from standard input (stdin) to the
  46     journal.</para>
  47
  48     <para>If parameters are passed, they are executed as command line
  49     with standard output (stdout) and standard error output (stderr)
  50     connected to the journal, so that all it writes is stored in the
  51     journal.</para>
  52   </refsect1>
  53
  54   <refsect1>
  55     <title>Options</title>
  56
  57     <para>The following options are understood:</para>
  58
  59     <variablelist>
  60       <xi:include href="standard-options.xml" xpointer="help" />
  61       <xi:include href="standard-options.xml" xpointer="version" />
  62
  63       <varlistentry>
  64         <term><option>-t</option></term>
  65         <term><option>--identifier=</option></term>
  66
  67         <listitem><para>Specify a short string that is used to
  68         identify the logging tool. If not specified, no identification
  69         string is written to the journal.</para></listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term><option>-p</option></term>
  74         <term><option>--priority=</option></term>
  75
  76         <listitem><para>Specify the default priority level for the
  77         logged messages. Pass one of
  78         <literal>emerg</literal>,
  79         <literal>alert</literal>,
  80         <literal>crit</literal>,
  81         <literal>err</literal>,
  82         <literal>warning</literal>,
  83         <literal>notice</literal>,
  84         <literal>info</literal>,
  85         <literal>debug</literal>, or a
  86         value between 0 and 7 (corresponding to the same named
  87         levels). These priority values are the same as defined by
  88         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  89         Defaults to <literal>info</literal>. Note that this simply
  90         controls the default, individual lines may be logged with
  91         different levels if they are prefixed accordingly. For details,
  92         see <option>--level-prefix=</option> below.</para></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><option>--level-prefix=</option></term>
  97
  98         <listitem><para>Controls whether lines read are parsed for
  99         syslog priority level prefixes. If enabled (the default), a
 100         line prefixed with a priority prefix such as
 101         <literal>&lt;5&gt;</literal> is logged at priority 5
 102         (<literal>notice</literal>), and similar for the other
 103         priority levels. Takes a boolean argument.</para></listitem>
 104       </varlistentry>
 105
 106     </variablelist>
 107
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Exit status</title>
 112
 113     <para>On success, 0 is returned, a non-zero failure code
 114     otherwise.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Examples</title>
 119
 120     <example>
 121       <title>Invoke a program</title>
 122
 123       <para>This calls <filename noindex='true'>/bin/ls</filename>
 124       with standard output and error connected to the journal:</para>
 125
 126       <programlisting># systemd-cat ls</programlisting>
 127     </example>
 128
 129     <example>
 130       <title>Usage in a shell pipeline</title>
 131
 132       <para>This builds a shell pipeline also invoking
 133       <filename>/bin/ls</filename> and writes the output it generates
 134       to the journal:</para>
 135
 136       <programlisting># ls | systemd-cat</programlisting>
 137     </example>
 138
 139     <para>Even though the two examples have very similar effects the
 140     first is preferable since only one process is running at a time,
 141     and both stdout and stderr are captured while in the second
 142     example, only stdout is captured.</para>
 143   </refsect1>
 144
 145   <refsect1>
 146     <title>See Also</title>
 147     <para>
 148       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 150       <citerefentry project='man-pages'><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 151     </para>
 152   </refsect1>
 153
 154 </refentry>