Commit 9aac0b2c authored by Lennart Poettering's avatar Lennart Poettering
Browse files

man: document systemd-cat(1)

parent ccdbaf91
......@@ -691,7 +691,8 @@ MANPAGES = \
man/machine-info.5 \
man/modules-load.d.5 \
man/sysctl.d.5 \
man/systemd-ask-password.1
man/systemd-ask-password.1 \
man/systemd-cat.1
MANPAGES_ALIAS = \
man/reboot.8 \
......
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemd-cat">
<refentryinfo>
<title>systemd-cat</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-cat</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-cat</refname>
<refpurpose>Connect a pipeline or program's output with the journal</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-cat</command> may be used to
connect STDOUT and STDERR of a process with the
journal, or as a filter tool in a shell pipeline to
pass the output the previous pipeline element
generates to the journal.</para>
<para>If no parameter is passed
<command>systemd-command</command> will write
everything it reads from standard input (STDIN) to the journal.</para>
<para>If parameters are passed they are executed as
command line with standard output (STDOUT) and standard
error output (STDERR) connected to the journal, so
that all it writes is stored in the journal.</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--h</option></term>
<term><option>--help</option></term>
<listitem><para>Prints a short help
text and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Prints a short version
string and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option></term>
<term><option>--identifier=</option></term>
<listitem><para>Specify a short string
that is used to identify the logging
tool. If not specified no identifying
string is written to the journal.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option></term>
<term><option>--priority=</option></term>
<listitem><para>Specify the default
priority level for the logged
messages. Pass one of
<literal>emerg</literal>,
<literal>alert</literal>,
<literal>crit</literal>,
<literal>err</literal>,
<literal>warning</literal>,
<literal>notice</literal>,
<literal>info</literal>,
<literal>debug</literal>, resp. a
value between 0 and 7 (corresponding
to the same named levels). These
priority values are the same as
defined by
<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults
to <literal>info</literal>. Note that
this simply controls the default,
individual lines may be logged with
different levels if they are prefixed
accordingly. For details see
<option>--level-prefix=</option>
below.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--level-prefix=</option></term>
<listitem><para>Controls whether lines
read are parsed for syslog priority
level prefixes. If enabled (the
default) a line prefixed with a
priority prefix such as
<literal>&lt;5&gt;</literal> is logged
at priority 5
(<literal>notice</literal>), and
similar for the other priority
levels. Takes a boolean
argument.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success 0 is returned, a non-zero failure
code otherwise.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Invoke a program</title>
<para>This calls <filename>/bin/ls</filename>
with STDOUT/STDERR connected to the
journal:</para>
<programlisting># systemd-cat ls</programlisting>
</example>
<example>
<title>Usage in a shell pipeline</title>
<para>This builds a shell pipeline also
invoking <filename>/bin/ls</filename> and
writes the output it generates to the
journal:</para>
<programlisting># ls | systemd-cat</programlisting>
</example>
<para>Even though the two examples have very similar
effects the first is preferable since only one process
is running at a time, and both STDOUT and STDERR are
captured while in the second example only STDOUT is
captured.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
......@@ -94,6 +94,13 @@
text and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Prints a short version
string and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--ready</option></term>
......
......@@ -59,7 +59,7 @@ static int parse_argv(int argc, char *argv[]) {
static const struct option options[] = {
{ "help", no_argument, NULL, 'h' },
{ "version" , no_argument, NULL, ARG_VERSION },
{ "version", no_argument, NULL, ARG_VERSION },
{ "identifier", required_argument, NULL, 't' },
{ "priority", required_argument, NULL, 'p' },
{ "level-prefix", required_argument, NULL, ARG_LEVEL_PREFIX },
......@@ -139,7 +139,7 @@ int main(int argc, char *argv[]) {
fd = sd_journal_stream_fd(arg_identifier, arg_priority, arg_level_prefix);
if (fd < 0) {
log_error("Failed to create stream fd: %s", strerror(fd));
log_error("Failed to create stream fd: %s", strerror(-fd));
r = fd;
goto finish;
}
......@@ -148,7 +148,7 @@ int main(int argc, char *argv[]) {
if (dup3(fd, STDOUT_FILENO, 0) < 0 ||
dup3(fd, STDERR_FILENO, 0) < 0) {
log_error("Failed to duplicate fd: %s", strerror(fd));
log_error("Failed to duplicate fd: %m");
r = -errno;
goto finish;
}
......@@ -163,12 +163,13 @@ int main(int argc, char *argv[]) {
else
execvp(argv[optind], argv + optind);
r = -errno;
/* Let's try to restore a working stderr, so we can print the error message */
if (saved_stderr >= 0)
dup3(saved_stderr, STDERR_FILENO, 0);
log_error("Failed to execute process: %m");
r = -errno;
log_error("Failed to execute process: %s", strerror(-r));
finish:
if (fd >= 0)
......
......@@ -33,6 +33,7 @@
#include "util.h"
#include "log.h"
#include "sd-readahead.h"
#include "build.h"
static bool arg_ready = false;
static pid_t arg_pid = 0;
......@@ -45,6 +46,7 @@ static int help(void) {
printf("%s [OPTIONS...] [VARIABLE=VALUE...]\n\n"
"Notify the init system about service status updates.\n\n"
" -h --help Show this help\n"
" --version Show package version\n"
" --ready Inform the init system about service start-up completion\n"
" --pid[=PID] Set main pid of daemon\n"
" --status=TEXT Set status text\n"
......@@ -59,6 +61,7 @@ static int parse_argv(int argc, char *argv[]) {
enum {
ARG_READY = 0x100,
ARG_VERSION,
ARG_PID,
ARG_STATUS,
ARG_BOOTED,
......@@ -67,6 +70,7 @@ static int parse_argv(int argc, char *argv[]) {
static const struct option options[] = {
{ "help", no_argument, NULL, 'h' },
{ "version", no_argument, NULL, ARG_VERSION },
{ "ready", no_argument, NULL, ARG_READY },
{ "pid", optional_argument, NULL, ARG_PID },
{ "status", required_argument, NULL, ARG_STATUS },
......@@ -88,6 +92,12 @@ static int parse_argv(int argc, char *argv[]) {
help();
return 0;
case ARG_VERSION:
puts(PACKAGE_STRING);
puts(DISTRIBUTION);
puts(SYSTEMD_FEATURES);
return 0;
case ARG_READY:
arg_ready = true;
break;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment