1!	 $eterna: exec,v 1.13 2018/06/10 02:25:30 mrg Exp $
2!
3! Copyright (c) 1990-2018  Michael Sandrof, Troy Rollo, Matthew Green,
4! and other ircII contributors.
5!
6! All rights reserved.  See the HELP IRCII COPYRIGHT file for more
7! information.
8!
9Usage: EXEC <shell commands>
10       EXEC -NAME <name> <shell commands>
11       EXEC -OUT [%<process id>|<shell commands]
12       EXEC -MSG <nickname> [%<process id>|<shell commands>]
13       EXEC -NOTICE <nickname> [%<process id>|<shell commands>]
14       EXEC -IN %<process id> <text to send to process>
15       EXEC -WINDOW [%<process id>|<shell commands>]
16       EXEC -<signal> %<process id>
17       EXEC -CLOSE %<process id>
18       EXEC -TARGET [<shell commands]
19       EXEC -FILTER <funcname> <shell commands>
20
21  EXEC allows you to start subprocesses in ircII and manipulate
22  them in various ways.  You can start multiple subprocesses
23  simultaneously and access them via a process number assigned
24  by ircII.  You can list all currently running subprocesses by
25  using EXEC with no parameters.  The process id of a process
26  is the number assigned by ircII for that process, or the
27  name of the process given by the -NAME flag.  If a NAME is
28  given to a process, that name may be used anyway in place of
29  the process number assigned by ircII.
30
31  The first form of EXEC will simply start a subprocess and send
32  its output to your display.
33
34  The second form tells IRCII to send the output of the process
35  to your current channel.  For example:
36    EXEC -OUT ls
37  sends the output of ls to your channel.
38    EXEC -OUT %1
39  tells ircII to send the output of subprocess 1 to your channel.
40  Subprocess 1 must exist already by a previous call to EXEC.
41
42  The third form is much like the second, except that it sends
43  to the specified nickname or nicknames (the format of the
44  nicknames is the same as for MSG).  As with the second form,
45  you can start a subprocess with -MSG, or you can change an
46  already running process to send its output to the given nicknames.
47
48  The fourth form is identical to the first, except the messages
49  are send as NOTICEs not as PRIVMSG's.
50
51  The fifth form lets you send a line of input to a running
52  subprocess.  For example:
53    EXEC -IN %shell This is a test.
54  Sends "This is a test." to subprocess 0.  This processes must
55  have previously been started with a call to EXEC -NAME shell.
56  An alternate method of sending text to processes is using the
57  MSG or QUERY command.  In the place of a nickname, you may
58  specify %n, when  n is a current running processes id.   For
59  example:
60    MSG %shell This is a test.
61  is equivalent to the previous example.
62
63  The sixth form lets you specify that you want all output from
64  the process to go to the current window.  Normally, output
65  from processes goes to whichever window has a level setting of
66  CRAP.  This locks the output into the current window.
67    EXEC -WINDOW %1
68  Sends the output of process 1 to the current window.
69
70  The seventh form lets you send various signals to subprocesses.
71  The allowable signals are:
72    HUP     INT     QUIT     ILL     TRAP     IOT     EMT
73    FPE     KILL    BUS      SEGV    SYS      PIPE    ALRM
74    TERM    URG     STOP     TSTP    CONT     CHLD    TTIN
75    TTOU    IO      XCPU     XFSZ    VTALRM   PROF    WINCH
76    LOST    USR1    USR2
77  What these signals do depends on the process running, etc.
78    EXEC -KILL %0
79  Sends a KILL signal to process 0, forcing it to exit
80  immediately.  If you want to read more about these signals, do
81  a "man kill" at your shell prompt.
82
83  The eigth form is for really ornery processes that simply won't
84  die.  Sometimes this is because an EXEC'd process has forked
85  off subprocesses which don't die when you use -KILL (or other
86  flag).  Doing a:
87    EXEC -CLOSE %0
88  closes all of ircII's connections to that processes.  This means
89  that even if the processes is still sending output you won't see
90  it.  This also means (in most cases) that the process will be
91  killed by a SIGPIPE when it tries to send to ircII.
92
93  The ninth form sends its output to whatever the current $T
94  points to:
95    EXEC -TARGET
96
97  The tenth form uses a filter function to handle the output
98  from the command. Example:
99    EXEC -FILTER method ./prog $0-
100  Would call $method() for every line of output the ./prog
101  causes. The $method() would get the line as parameters.
102  If the function returns value, the first word of the
103  exec output line will be stripped away and the rest
104  will be appended to the return value and the result
105  executed as a command.
106  This is very useful if $method() is a function returning
107  a command and ./prog outputs the recipient nickname as
108  the first word on every line.
109  /on exec could also be used, but it does not work right
110  if you work on multiple servers at the same time.
111  NOTE: If the program outputs lines longer than the ircII
112  line length limit is, the lines are handled as if they
113  were split, and this may not work expectedly. Be careful.
114
115  Note that unless EXEC_PROTECTION is set to OFF, the /EXEC
116  command is not available while a /ON hook is executing.  See the
117  SET EXEC_PROTECTION help page for more information about
118  this feature.
119
120See Also:
121  SET SHELL
122  SET SHELL_FLAGS
123  SET SHELL_LIMIT
124  SET NOTIFY_ON_TERMINATION
125  SET EXEC_PROTECTION
126