.\"
.\" ep - extended pipelining
.\"
.\" doc/man/ep.1 - main extended pipelining manpage
.\" ____________________________________________________________
.\"
.\" Developed by Ondrej Jombik
.\" and Lubomir Host
.\" Copyright (c) 2000-2003 Platon SDG, http://platon.sk/
.\" All rights reserved.
.\"
.\" See README file for more information about this software.
.\" See COPYING file for license information.
.\"
.\" Download the latest version from
.\" http://platon.sk/projects/ep/
.\"
.TH "@PACKAGE@" "@MANVOLNUM@" "@DATE_HUMAN@" "@PACKAGE@ @VERSION@" "@PACKAGE@ @VERSION@"
.BY "Ondrej Jombik"
.SH NAME
@PACKAGE@ \- extended pipelining
.SH SYNOPSIS
.PP
@PACKAGE@ [ GLOBAL OPTIONS -- ] [ PROCESSES OPTIONS ]
.SH DESCRIPTION
.B @PACKAGE@
is an easy-to-use pipeline process (re)director. It has the main
ability to run any number of subprocesses and redirect them basic
filedescriptors. Basic filedescriptors are 0 (standart input),
1 (standart output) and 2 (standart errput). There is no restriction
of pipe connection except that process outputs (output, errput) must
be bound with one or more processes input.
.P
.B @PACKAGE@
is a pipeline connector. For most of UNIX user there was a time
they wanted to bend the pipe (ie. make a bidirectional pipe) which
could render many problems to a simple tasks of creating modules.
Application is mostly used for creating a communication tree between
several programs which communicate trhough STDIN, STDOUT and STDERR
pipelines.
.B @PACKAGE@
supports cyclic pipelining (A -> B, B -> A) between
processes thus standing for a powerful tool for creating script-based
modular projects.
.SH GLOBAL OPTIONS
.TP
\f3-h\f1, \f3--help\f1
Print a help screen.
.TP
\f3-q\f1, \f3--quiet\f1
Force quiet mode.
.TP
\f3-v\f1, \f3--verbose\f1
Enable verbose mode. More \f3-v\f1 means more verbose.
.TP
\f3-f\f1, \f3--config-file\f1 \f2\f1
Load user defined configuration file.
.TP
\f3--disable-global-config\f1
Disable global configuration file loading.
.TP
\f3--disable-user-config\f1
Disable user configuration file loading.
.SH PROCESSES OPTIONS
Processes are specified on command line after global options. Each process can
be configured by
.B @PACKAGE@
processes options. After these options process command to run has to be
defined. At the end, there is a separator "--" and the next process
configuration can begin.
.P
[ [ [ \f2PROCS_1\f1 \f2cmd_1\f1 ] \f2--\f1 \f2PROCS_2\f1 \f2cmd_2\f1 ] ... ]
.P
\f2PROCS_n\f1 are options of particular process, \f2cmd_2\f1 is command to run
a process.
.TP
\f3-i\f1, \f3--input\f1 \f2\f1
Links binded to standart input (STDIN).
.TP
\f3-o\f1, \f3--output\f1 \f2\f1
Links binded to standart output (STDOUT).
.TP
\f3-e\f1, \f3--errput\f1 \f2\f1
Links binded to standart error output (STDERR).
.TP
\f3-n\f1, \f3--name\f1 \f2\f1
Name of process. Process can have zero, one or more names.
.TP
\f3-N\f1, \f3--nice\f1 \f2\f1
Process run priority. A value from 20 to -20. Only superuser may specify
negative values.
.PP
When using \f3--input\f1, \f3--output\f1 or \f3--errput\f1 option, you have to
pass link specification as a parameter. Link specification consist of two parts
separated with comma: linked process name and its stream name. For example if you
want to link process output to other process with name "telnet" input, you have
to write something like \f3--output\f1 \f2telnet.input\f1.
.PP
Processes have automatically assigned its index number as a name. Any amount of
other names or aliases can be specified fro one process. Process with index 0
is means STDIN, STDOUT and STDERR. Other process indexes are counted from 1
according to their order of definition on command line or configuration file.
.SH EXAMPLES
Here is an example how to create simple pop3 e-mails fetcher. You have to write
the "my-pop3-client.sh" script file, which will communicate via STDIN and
STDOUT streams. It's aim is to simulate human presence at the other end of the
telnet connection, so in example it will type "USER jones", "PASS
mysecretpassword" and other appropriate POP3 commands as if you typed them.
.PP
@PACKAGE@ -i 0.in,1.out -o 2.in -e 0.err telnet example.com 110
.br
-- -i 1.out -o 0.out,1in -e 0.err ./my_pop3_client.sh
.PP
Now we can try something more useful. Let's create encryption/decryption
communication layer between our terminal and remote host. Assume we have the
"encoder.sh", "decoder.sh", "logger.sh" scripts.
.PP
@PACKAGE@ -i 0.i -o 2.i -e 0.e ./encoder.sh
.br
-- -i 1.o -o 3.i -e 0.e telnet secret.example.com
.br
-- -i 2.o -o 0.o -e 0.e ./decoder.sh
.br
-- -i 1.o,2.o,3.o,1.e,2.e,3.e -o 0.o -e 0.e ./logger.sh
.br
.P
Now take closer look at this scheme.
.B @PACKAGE@
represents the user. The output goes to the screen, the input is taken from
keyboard. The shortcuts or better say process indexes are:
.PP
0 - user
.br
1 - encoder
.br
2 - telnet
.br
3 - decoder
.br
4 - logger
.PP
The communication streams between programs are here showed graphically:
.PP
+----------+ +---------+
.br
| keyboard | -> | encoder |
.br
+----------+ +---------+
.br
| |
.br
v v
.br
+--------+ +--------+
.br
| telnet | -> | logger |
.br
+--------+ +--------+
.br
| ^
.br
v |
.br
+---------+ +---------+
.br
| monitor | <- | decoder |
.br
+---------+ +---------+
.br
.SH FILES
.TP
/etc/@PACKAGE@.conf
global configuration file
.TP
~/.@PACKAGE@.conf
per-user configuration file
.SH AUTHORS
Developed by Ondrej Jombik
and Lubomir Host
.sp
Copyright (c) 2000-2003 Platon SDG, http://platon.sk/
.sp
Comments, suggestions, bug reports and patches are always welcome. Please
e-mail them to the following e-mail address and write
.B @PACKAGE@
keyword in the Subject line.
.sp
This manual page was initially written by Martin Karas in April 2001 and
updated by Ondrej Jombik in 18th April 2003.
.SH HOMEPAGE
The official
.B @PACKAGE@
homepage is:
.sp
.RS
.UR
http://platon.sk/projects/@PACKAGE@/
.sp
.UE
.RE
The @PACKAGE@ project management page is:
.sp
.RS
.UR
http://platon.sk/projects/main_page.php?project_id=8
.sp
.UE
.RE
Use
.B @PACKAGE@
project management page to submit bugs, feature requests,
suggestions for improvements or improved code. There is also online
documentation browser, download central and discussion forum available for
asking support questions.
.SH LICENSE
This program 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, or (at your option) any later version.
.sp
This program 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.
.sp
You should have received a copy of the GNU General Public License along with
this library; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.
.SH "SEE ALSO"
.BR cat (1),
.BR grep (1),
.BR bash (1),
.BR pipe (2)