chiark / gitweb /
service: add FailureAction= option
[elogind.git] / 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   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd-cat"
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>systemd-cat</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>systemd-cat</refentrytitle>
43                 <manvolnum>1</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>systemd-cat</refname>
48                 <refpurpose>Connect a pipeline or program's output with the journal</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <cmdsynopsis>
53                         <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
54                 </cmdsynopsis>
55                 <cmdsynopsis>
56                         <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command>
57                 </cmdsynopsis>
58         </refsynopsisdiv>
59
60         <refsect1>
61                 <title>Description</title>
62
63                 <para><command>systemd-cat</command> may be used to
64                 connect the standard input and output of a process to the
65                 journal, or as a filter tool in a shell pipeline to
66                 pass the output the previous pipeline element
67                 generates to the journal.</para>
68
69                 <para>If no parameter is passed,
70                 <command>systemd-cat</command> will write
71                 everything it reads from standard input (stdin) to the journal.</para>
72
73                 <para>If parameters are passed, they are executed as
74                 command line with standard output (stdout) and standard
75                 error output (stderr) connected to the journal, so
76                 that all it writes is stored in the journal.</para>
77         </refsect1>
78
79         <refsect1>
80                 <title>Options</title>
81
82                 <para>The following options are understood:</para>
83
84                 <variablelist>
85                         <xi:include href="standard-options.xml" xpointer="help" />
86                         <xi:include href="standard-options.xml" xpointer="version" />
87
88                         <varlistentry>
89                                 <term><option>-t</option></term>
90                                 <term><option>--identifier=</option></term>
91
92                                 <listitem><para>Specify a short string
93                                 that is used to identify the logging
94                                 tool. If not specified, no identification
95                                 string is written to the journal.</para></listitem>
96                         </varlistentry>
97
98                         <varlistentry>
99                                 <term><option>-p</option></term>
100                                 <term><option>--priority=</option></term>
101
102                                 <listitem><para>Specify the default
103                                 priority level for the logged
104                                 messages. Pass one of
105                                 <literal>emerg</literal>,
106                                 <literal>alert</literal>,
107                                 <literal>crit</literal>,
108                                 <literal>err</literal>,
109                                 <literal>warning</literal>,
110                                 <literal>notice</literal>,
111                                 <literal>info</literal>,
112                                 <literal>debug</literal>, or a
113                                 value between 0 and 7 (corresponding
114                                 to the same named levels). These
115                                 priority values are the same as
116                                 defined by
117                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults
118                                 to <literal>info</literal>. Note that
119                                 this simply controls the default,
120                                 individual lines may be logged with
121                                 different levels if they are prefixed
122                                 accordingly. For details see
123                                 <option>--level-prefix=</option>
124                                 below.</para></listitem>
125                         </varlistentry>
126
127                         <varlistentry>
128                                 <term><option>--level-prefix=</option></term>
129
130                                 <listitem><para>Controls whether lines
131                                 read are parsed for syslog priority
132                                 level prefixes. If enabled (the
133                                 default), a line prefixed with a
134                                 priority prefix such as
135                                 <literal>&lt;5&gt;</literal> is logged
136                                 at priority 5
137                                 (<literal>notice</literal>), and
138                                 similar for the other priority
139                                 levels. Takes a boolean
140                                 argument.</para></listitem>
141                         </varlistentry>
142
143                 </variablelist>
144
145         </refsect1>
146
147         <refsect1>
148                 <title>Exit status</title>
149
150                 <para>On success, 0 is returned, a non-zero failure
151                 code otherwise.</para>
152         </refsect1>
153
154         <refsect1>
155                 <title>Examples</title>
156
157                 <example>
158                         <title>Invoke a program</title>
159
160                         <para>This calls <filename noindex='true'>/bin/ls</filename>
161                         with standard output and error connected to the
162                         journal:</para>
163
164                         <programlisting># systemd-cat ls</programlisting>
165                 </example>
166
167                 <example>
168                         <title>Usage in a shell pipeline</title>
169
170                         <para>This builds a shell pipeline also
171                         invoking <filename>/bin/ls</filename> and
172                         writes the output it generates to the
173                         journal:</para>
174
175                         <programlisting># ls | systemd-cat</programlisting>
176                 </example>
177
178                 <para>Even though the two examples have very similar
179                 effects the first is preferable since only one process
180                 is running at a time, and both stdout and stderr are
181                 captured while in the second example, only stdout is
182                 captured.</para>
183         </refsect1>
184
185         <refsect1>
186                 <title>See Also</title>
187                 <para>
188                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
189                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
190                         <citerefentry><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry>
191                 </para>
192         </refsect1>
193
194 </refentry>